Java Internal Poller Example

What is the Java Internal Poller Example ?

OPUS is distributed with a sample pipeline which demonstrates some of the capabilities of the OPUS system. That pipeline includes both internal and external pollers as pipeline applications. Up until version 4.2, all internal pollers needed to be written in C++. Pipeline application writers can now take advantage of new OAPI capabilities to create applications in other languages, using CORBA to interact with OPUS as internal pollers. If desired, internally polling applications can now be written in any language for which a CORBA binding exists. Of course, externally polling applications can, as always, be written in any language.

This Java example is included to illustrate such an application. It is written in Java (1.3, 4, or 5) and runs on all OPUS supported platforms. It uses the CORBA software that is included with both the JDK and OPUS. There is some preliminary setup required, but hopefully that will be made less complicated by the following information.
What do I have to do to set this up ?

This process requires one addition to your environment, and after that the appropriate OPUS files need to be created. The following steps are required:

  1. OPUS_CLASSPATH:
    The TASK for this process, as listed in the resource file, is a Java process which requires two of the jar files that are included with OPUS. They are: "OPUS_API.jar" and "UTIL.jar", and they are located in the "opus/bin/java" directory of the OPUS tree. The task assumes you have an environment variable named "OPUS_CLASSPATH" which specifies their location. You can set this variable to the full path locations of the two jar files under the installed OPUS tree, or, for example, let's assume that user "joe" has copied them to his home directory. Then add this to your environment settings (e.g. your .cshrc file):


    In versions 5.4b and earlier, the name EXAMPLE_CLPATH was used in place of OPUS_CLASSPATH. Any name will work, so long as it matches what is used in the TASK line of the resource file (below). Also for those versions, JOPUS.jar must be added to the list of jar files.

  2. Note that the Java source code for this process, in the file "JIntPoller.java", has already been compiled for you, residing inside "UTIL.jar". You do not need to recompile it for this example, no matter what OS you are using.

  3. Install the process resource file. This has been included and is located in "opus/definitions/unix/jpoller.resource". Simply copy this into your OPUS_DEFINITIONS_DIR. If you are already setup to run the sample pipeline, then you may skip this step.

  4. Install the path file. You may create your own, or you may use the included "quick.path" path file that has been installed for use with the sample pipeline. If you wish to create your own, follow the format of "quick.path", set the directory locations to your needs, then simply copy it into your OPUS_DEFINITIONS_DIR. If you are already setup to run the sample pipeline, and you wish to use "quick.path", then you may skip this step.

Now that I have configured everything, how do I run it ?

Via the PMG and the OMG.

Once the Java jar files are located under $OPUS_CLASSPATH, and the resource and path files are located in your OPUS_DEFINITIONS_DIR directory, simply start the OPUS servers and then run the PMG and the OMG (as explained in detail in the OPUS PMG and OMG documentation). Find "jpoller" under the "Processes" tree in the PMG, listed under OPUS / Processes / SAMPLE / ALL. Drag it to the "quick" path tab on the right side of the PMG and select a node to run it on in the popup window. When it is listed as "pending", use the PMG menu to start the pending process.

If all goes well, it will eventually sit, listed as "idle", waiting to be triggered. At this point, you will be able to view the process log file ("View" menu) and verify that the Java process has started and, as its first task, has listed all the resource values it read from the resource file, via the OAPI.

In contrast to the Python example, the Java example uses an OSF trigger. Therefore, you must create an OSF and then set the appropriate column to the appropriate value (as defined in the resource file) before OPUS will trigger the process. Follow these steps:
  1. At the command line, create an OSF with the name "my_osf" by typing: 
    osf_create -p quick.path -f my_osf -s _
    This will create an OSF named "my_osf" and will set the status of all its columns to "_".

  2. In the OMG, open the "quick" path.

  3. Your newly created OSF will show up. Set the "KW" column to "w" to trigger the process. Click "OK" in the popup dialog. There is no special significance to the "KW" stage/column for this example, we simply chose an existing stage in an existing path. This Java process does nothing with keywords.

The jpoller task has now been triggered to process a dataset. Within 10 seconds (i.e., the default POLLING_TIME), the jpoller process will wake up. You will be able to see the status change in the PMG as well as in the OMG. In the OMG, the "KW" column of the OSF will change to "p" while processing, then to "c" when complete, or to "e" if an error is encountered. You will be able to view the results in the log file. You have successfully processed a dataset though a Java internal poller using OPUS.

Now that I can run the example, how do I make my own ?

The most difficult part of this process was getting the example to run. If that was successful, then you can either write your own from scratch, or simply copy the example as a template. You may only want or need to edit the contents of the "processDataset()" method in JIntPoller.java, inserting the code that does your own specific processing. Or you may want to make some changes in the main loop to take more full advantage of the OAPI than is done by this example.
How do I run this task on an unsupported platform ? (optional)

After a successful test of this example on a supported platform, you may wish to use it to prove to yourself that OPUS Java internal pollers can be run basically anywhere. If you have access to a node running an operating system that is not on the list of supported operating systems, give the following a try and let us know how it goes.

Here are the modifications needed to run this task on an unsupported operating system, e.g. on a machine called "node_x", while the servers will be running on a machine (supported operating system) called "ServerNode" :

  1. On "node_x", verify that Java is installed and that it is in your path. Login temporarily to "node_x" to run "java -version", then logout.
  2. On "ServerNode", verify that you can run remote-shell commands to "node_x" without being prompted for a password. From "ServerNode", run the command "$OPUS_REMOTE_SHELL node_x date" and verify that the correct output of the "date" command, for that system, is printed.
  3. Copy the two jar files, OPUS_API.jar and UTIL.jar, found in your OPUS installation on "ServerNode", to your home directory on "node_x". (This need not be your home directory, but we will assume so for simplicity.)
  4. On "ServerNode", edit the TASK line of the jpoller.resource file to change "$OPUS_CLASSPATH" to "OPUS_API.jar:UTIL.jar" (or, if you have problems with that, try using the absolute path on "node_x", e.g. "/home/joe/OPUS_API.jar:/home/joe/UTIL.jar"). Note that the colon might be a semi-colon on Windows, depending on the shell software being used. If you do not have write permissions to the resource file where it exists, simply copy the installed version to the front most directory location in your OPUS_DEFINITIONS_DIR, and edit it.
  5. On "ServerNode", before starting the OPUS servers, edit the "opus.env" file to add "node_x" to the item called REMOTE_LITE_NODES. Again, if you can not write to the opus.env file (found via osfile_stretch_file OPUS_DEFINITIONS_DIR:opus.env), simply copy the installed version to the front most directory location in your OPUS_DEFINITIONS_DIR, and edit it. Using "node_x" (and maybe another node, say "node_y") this way, the entire line would appear as: 
    	REMOTE_LITE_NODES = node_x,node_y
    This will signal OPUS that any and all processes started on these nodes will be treated specially, as nodes with no OPUS-specific information installed (other than the 2 jar files). Do not list any nodes here that are used to spawn regular OPUS tasks, as this will cause problems for them.
  6. On "ServerNode", start the OPUS servers as you did for the example above.
  7. In the PMG, click "Tools -> Select Nodes" to bring "node_x" into the PMG's list of node choices.
  8. In the PMG, start the "jpoller" task on "node_x", similar to how you did for the example above.
  9. On "ServerNode", trigger the task with an OSF, as you did for the example above.

If you find this to be a useful capability, you may wish to develop your own Java internal pollers for deployment on such nodes, using the above example as your guide.


 

Back to the Top

Top of OPUS FAQ