| Running the Raytrace example |
|
|
Instructions for running the Raytrace example using the Jini(TM)
Technology Starter Kit v1.2.1 and v2.0
June 5, 2003 |
The Raytrace application is one of the first examples created for the Jini(TM) Technology Starter Kit (starter kit). Two applications, one named worker and one named trace, work together to produce a raytraced scene of four semi-transparent colored balls suspended in space. The trace application divides up the scene into many separate parts and, through the use of a JavaSpaces(TM) service, takes those many parts to create separate work assignments for the worker processes. The worker process takes each assignment for rendering a portion of the scene, completes it, and puts the results back in the JavaSpaces service. The raytrace application retrieves these scene elements and displays them in the window.
This page describes how to build and run this set of applications for both the v1.2.1 and the new v2.0 starter kits.
The files for this example may be found insrc/com/sun/jini/example/ray.
All directories and paths mentioned below are relative to this directory.
For an overview of how this example works, please see the API documentation. This API documentation includes detailed descriptions and diagrams that describe, step by step, how the example works. The main discussions are in
com.sun.jini.example.ray.ex1.raytracecom.sun.jini.example.ray.ex2.raytraceex1 and ex2)
It is interesting to note that the Java source code for the v1.2.1 compatible example
in the ex1 directory and the source code for the v2.0 compatible example
in the ex2 directory are identical (except for the package names). While this will not be true of
other examples presented in the examples bundle, it happens to be true with the raytrace example.
There are changes between the two versions of this example but these changes are confined to the scripts that start the examples, the build script that builds the example, the way the JAR files are constructed, the policy files needed to run these examples, and the addition of configuration files for the v2.0 compatible version.
There are several directories associated with this example. The description for each of these directories follows.
ex1build.xml Ant script compiles the source and produces three
JAR files: trace1.jar, trace1-dl.jar, and
worker1.jar.
ex2build.xml Ant script compiles the source and produces three
JAR files: trace2.jar, trace2-dl.jar, and
worker2.jar.
bat12bin12bat20bin20libex1 and ex2 directories. When run with v2.0 of the
starter kit, this directory should also contain copies of the jsk-platform.jar
and jsk-resources.jar distributed with the starter kit.
jsk-platform.jar
and jsk-resources.jar) from the distribution to the lib
directory with each build. If you wish to run the example from the pre-built JAR
files included in the examples release before you have run Ant, you must copy
two files jsk-platform.jar and jsk-resources.jar) to the
lib directory yourself.
policy
configconfig files. config
files are new with v2.0 of the starter kit and are used to start services, supply
values for application settings, configure RMI transports, and other tasks. These
config files are one of the important changes introduced in v2.0
of the starter kit.
manifestindex.htmlThis section provides instructions for running the raytrace example with v1.2.1 of the starter kit. The following section describes how to run these examples in the UNIX(TM) operating environment. To run these examples in the Microsoft Windows operating environment, click here.
Files from the following directories are used to run the raytrace example under starter kit v1.2.1:
bin12ex1policylibtrace1.jar, trace1-dl.jar,
and worker1.jar.
The example is run by executing scripts in the bin12 directory. While
it is possible to have many Jini services running concurrently on a given
computer, it is most simple to run these examples on a computer that has no other
Jini services running. The instructions below will walk you through the
steps necessary to ensure that the only Jini services running are associated with this
example.
Here are the steps to run this example with v1.2.1 of the starter kit in the UNIX operating environment:
cd bin12
JINI_HOME.sh file
EXJINIHOME.
This should be set to the root directory for the v1.2.1 starter kit you wish to use.
Other scripts in this directory will source this file to pick up that
definition.
lib directory, and another
servicing requests on port 8082 for JAR files in the local lib directory.
rmid is not running
rmid to support the activatable service
Reggie (a Jini lookup service). If rmid is
running type rmid -stop at a command prompt.
run_allray1.sh at a command prompt. This will start all
of the programs necessary to run this example, including rmid,
two HTTP servers, Reggie, Outrigger, and the
worker and trace Jini applications.
run_allray1.sh script starts all of the necessary
programs in the background. Therefore, the script may exit immediately
but the programs it has started may take a few moments to complete
their start up. Two programs should present windows on the screen:
worker and trace. Adjust the locations of these windows
on the screen such that the trace window is completely visible
(not covered by other windows).
com.sun.jini.example.ray.ex1.raytrace
contains a detailed description for how to use the running programs to produce
a raytraced image. The root of the ray_ex1 package is located
here. Click on the
com.sun.jini.example.ray.ex1.raytrace link to access these instructions.
../lib/worker1.jar
on its command line and the trace application is executed in the process that
mentions trace1.jar on its command line.
rmid
run_allray1.sh
script. They are Reggie and Outrigger. Reggie is an activatable
service so stopping rmid will stop its child Reggie. This is done by
typing the following command at a command prompt: rmid -stop.
transient-outrigger.jar on its command
line. Kill that process.
run_allray1.sh command started two HTTP servers. Kill those
processes. These processes mention tools.jar on their command lines.
The steps explicitly outlined above for stopping the example are important. It can become very confusing when processes from a previous run of an example continue running during the execution of a new example. As discussed above, real world deployment of Jini services can include many instances of a particular service running on a given computer but such arrangements only increase the likelihood of confusion during debugging and experimentation. Therefore, it is strongly recommended that the machine used for running these examples be "emptied" of other Jini or Jini-associated processes before an example is run.
Files from the following directories are used to run the raytrace example under starter kit v1.2.1:
bat12ex1policylibtrace1.jar, trace1-dl.jar,
and worker1.jar.
The example is run by executing the batch files in the bat12 directory. While
it is possible to have many Jini services running concurrently on a given
computer, it is most simple to run these examples on a computer that has no other
Jini services running. The instructions below will walk you through the
steps necessary to ensure that the only Jini services running are associated with this
example.
Here are the steps to run this example with v1.2.1 of the starter kit in the Windows operating environment:
cd bat12
JINI_HOME.bat file
EXJINIHOME.
This should be set to the root directory for the v1.2.1 starter kit you wish to use.
Other batch files in this directory will call this file to pick up that
definition.
lib directory, and another
servicing requests on port 8082 for JAR files in the local lib directory.
rmid is not running
rmid to support the activatable service
Reggie (a Jini lookup service). If rmid is
running type rmid -stop at a command prompt.
run_allray1.bat at a command prompt. This will start all
of the programs necessary to run this example, including rmid,
two HTTP servers, Reggie, Outrigger, and the
worker and trace Jini applications.
run_allray1.bat batch file starts all of the necessary
programs in the background. Therefore, the batch file may exit immediately
but the programs it has started may take a few moments to complete
their start up. Two programs should present windows on the screen:
worker and trace. Adjust the locations of these windows
on the screen such that the trace window is completely visible
(not covered by other windows).
com.sun.jini.example.ray.ex1.raytrace
contains a detailed description for how to use the running programs to produce
a raytraced image. The root of the ray_ex1 package is located
here. Click on the
com.sun.jini.example.ray.ex1.raytrace link to access these instructions.
..\lib\worker1.jar
on its command line and the trace application is executed in the process that
mentions trace1.jar on its command line.
rmid
run_allray1.sh
script. They are Reggie and Outrigger. Reggie is an activatable
service so stopping rmid will stop its child Reggie. This is done by
typing the following command at a command prompt: rmid -stop.
transient-outrigger.jar on its command
line. Kill that process.
run_allray1.bat command started two HTTP servers. Kill those
processes. These processes mention tools.jar on their command lines.
The steps explicitly outlined above for stopping the example are important. It can become very confusing when processes from a previous run of an example continue running during the execution of a new example. As discussed above, real world deployment of Jini services can include many instances of a particular service running on a given computer but such arrangements only increase the likelihood of confusion during debugging and experimentation. Therefore, it is strongly recommended that the machine used for running these examples be "emptied" of other Jini or Jini-associated processes before an example is run.
hostname. On Windows, the batch files use %computername%
to accomplish this. Should you wish to run these examples on a set of
machines (instead of all on one machine) this setting would need to be adjusted
in each of the appropriate scripts.
codebase
command-line arguments were selected arbitrarily. Other numbers should work as well.
If these port numbers are already in use on the computer you are using, you may carefully
change these port numbers in the scripts to accommodate your environment.
/tmp directory on UNIX.
Other directories would serve the purpose as well. Systematically changing
the location of the temporary files should not adversely affect the example.
For the Windows batch files, the temporary files are local to the scripts
directory.
policy.all
run_browser.sh at a command prompt on
UNIX or run_browser.bat on Windows.
After running these examples with v1.2.1 of the starter kit try running the example again with v2.0 of the starter kit to see what has changed.
This section provides instructions for running the raytrace example with v2.0 of the starter kit. The following section describes how to run these examples in the UNIX operating environment. To run these examples in the Microsoft Windows operating environment, click here.
Files from the following directories are used to run the raytrace example under starter kit v2.0:
bin20ex2policylibtrace2.jar, trace2-dl.jar,
and worker2.jar. It should also include jsk-platform.jar
and jsk-resources.jar.
jsk-platform.jar
and jsk-resources.jar from the distribution to the lib
directory with each build. If you wish to run the example from the pre-built JAR
files included in the examples release before you have run Ant, you must copy
two files jsk-platform.jar and jsk-resources.jar) to the
lib directory yourself.
config
The example is run by executing scripts in the bin20 directory. While
it is possible to have many Jini services running concurrently on a given
computer, it is most simple to run these examples on a computer that has no other
Jini services running. The instructions below will walk you through the
steps necessary to ensure that the only Jini services running are associated with this
example.
Here are the steps to run this example with v2.0 of the starter kit in the UNIX operating environment:
cd lib
jsk-platform.jar
and jsk-resources.jar to this directory yourself.
Confirm that these files are present in the lib
directory before proceeding. (See the lib directory
description above.) Then,
cd ..
cd bin20
JINI_HOME.sh file
EXJINIHOME.
This variable should be set to the root directory for the starter kit you wish to use.
Other scripts in this directory will source this file to pick up that
definition.
lib directory, and another
servicing requests on port 8082 for JAR files in the local lib directory.
run_allray2.sh at a command prompt. This will start all
of the programs necessary to run this example including Phoenix,
two HTTP servers, Reggie, Outrigger, and the
worker and trace Jini applications.
run_allray2.sh script starts all of the necessary
programs in the background. Therefore, the script may exit immediately
but the programs it has started may take a few moments to complete
their start up. Two programs should present windows on the screen:
worker and trace. Adjust the locations of these windows
on the screen such that the trace window is completely visible
(not covered by other windows).
com.sun.jini.example.ray.ex2.raytrace
contains a detailed description for how to use the running programs to produce
a raytraced image. The root of the ray_ex2 package is located
here. Click on the
com.sun.jini.example.ray.ex2.raytrace link to access these instructions.
../lib/worker2.jar
on its command line and the trace application is executed in the process that
mentions trace2.jar on its command line.
Phoenix
rmid. This example uses Phoenix to
start the activatable service Reggie, the contributed implementation
of a Jini lookup service. Stopping Phoenix will normally
destroy all of its child processes (activated service).
Reggie
Outrigger
start-transient-jrmp-outrigger.config
on its command line. Kill that process.
run_allray2.sh command started two HTTP servers. Kill those
processes. These processes mention tools.jar on their command lines.
The steps explicitly outlined above for stopping the example are important. It can become very confusing when processes from a previous run of an example continue running during the execution of a new example. As discussed above, real world deployment of Jini services can include many instances of a particular service running on a given computer, but such arrangements only increase the likelihood of confusion during debugging and experimentation. Therefore, it is strongly recommended that the machine used for running these examples be "emptied" of other Jini or Jini-associated processes before an example is run.
Files from the following directories are used to run the raytrace example under starter kit v2.0:
bat20ex2policylibtrace2.jar, trace2-dl.jar,
and worker2.jar. It should also include jsk-platform.jar
and jsk-resources.jar.
jsk-platform.jar
and jsk-resources.jar) from the distribution to the lib
directory with each build. If you wish to run the example from the pre-built JAR
files included in the examples release before you have run Ant, you must copy
two files jsk-platform.jar and jsk-resources.jar) to the
lib directory yourself.
config
The example is run by executing batch files in the bat20 directory. While
it is possible to have many Jini services running concurrently on a given
computer, it is most simple to run these examples on a computer that has no other
Jini services running. The instructions below will walk you through the
steps necessary to ensure that the only Jini services running are associated with this
example.
Here are the steps to run this example with v2.0 of the starter kit in the Windows operating environment:
cd lib
jsk-platform.jar
and jsk-resources.jar to this directory yourself.
Confirm that these files are present in the lib
directory before proceeding. See the lib description
above. Then,
cd ..
cd bat20
JINI_HOME.bat file
EXJINIHOME.
This variable should be set to the root directory for the starter kit you wish to use.
Other scripts in this directory will call this file to pick up that
definition.
lib directory, and another
servicing requests on port 8082 for JAR files in the local lib directory.
run_allray2.bat at a command prompt. This will start all
of the programs necessary to run this example including Phoenix,
two HTTP servers, Reggie, Outrigger, and the
worker and trace Jini applications.
run_allray2.bat batch file starts all of the necessary
programs in the background. Therefore, the script may exit immediately
but the programs it has started may take a few moments to complete
their start up. Two programs should present windows on the screen:
worker and trace. Adjust the locations of these windows
on the screen such that the trace window is completely visible
(not covered by other windows).
com.sun.jini.example.ray.ex2.raytrace
contains a detailed description for how to use the running programs to produce
a raytraced image. The root of the ray_ex2 package is located
here. Click on the
com.sun.jini.example.ray.ex2.raytrace link to access these instructions.
..\lib\worker2.jar
on its command line and the trace application is executed in the process that
mentions trace2.jar on its command line.
Phoenix
rmid. This example uses Phoenix to
start the activatable service Reggie, the contributed implementation
of a Jini lookup service. Stopping Phoenix will normally
destroy all of its child processes (activated service).
Reggie
Outrigger
start-transient-jrmp-outrigger.config
on its command line. Kill that process.
run_allray2.bat command started two HTTP servers. Kill those
processes. These processes mention tools.jar on their command lines.
The steps explicitly outlined above for stopping the example are important. It can become very confusing when processes from a previous run of an example continue running during the execution of a new example. As discussed above, real world deployment of Jini services can include many instances of a particular service running on a given computer, but such arrangements only increase the likelihood of confusion during debugging and experimentation. Therefore, it is strongly recommended that the machine used for running these examples be "emptied" of other Jini or Jini-associated processes before an example is run.
Here are some final notes on these scripts:
hostname. On Windows, the batch files use %computername%
to accomplish this. Should you wish to run these examples on a set of
machines (instead of all on one machine) this setting would need to be adjusted
in each of the appropriate scripts.
codebase
command line arguments were selected arbitrarily. Other numbers should work as well.
If these port numbers are already in use on the computer you are using, you may carefully
change these port numbers in these scripts to accommodate your environment.
bat20 for Windows, bin20 for UNIX).
Other directories would serve the purpose as well. Systematically changing
the location of the temporary files should not adversely affect the example.
Note that both the scripts and configuration files would need to be altered.
policy.all
run_browser.bat at a command prompt.
Here are the known bugs: