Running the Raytrace example Example logo
Instructions for running the Raytrace example using the Jini(TM) Technology Starter Kit v1.2.1 and v2.0
June 5, 2003

Description

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 in src/com/sun/jini/example/ray. All directories and paths mentioned below are relative to this directory.

For instructions for running with starter kit v1.2.1 click here.
For instructions for running with starter kit v2.0 click here.

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

Below are links to the top level packages (ex1 and ex2)

Interesting note

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.

Raytrace example directory contents

There are several directories associated with this example. The description for each of these directories follows.

ex1
This directory contains the source code for building the version of the raytrace application compatible with v1.2.1 of the starter kit. The build.xml Ant script compiles the source and produces three JAR files: trace1.jar, trace1-dl.jar, and worker1.jar.
ex2
This directory contains the source code for building the version of the raytrace application compatible with v2.0 of the starter kit. The build.xml Ant script compiles the source and produces three JAR files: trace2.jar, trace2-dl.jar, and worker2.jar.
bat12
This directory contains Windows batch files used to start the various Jini technology-based services (Jini services) needed to support the example and the two raytrace application programs. These files are for running this example with v1.2.1 of the starter kit.
bin12
This directory contains Bourne shell scripts used to start the various Jini services needed to support the example and the two raytrace application programs. These shell scripts are for running this example with v1.2.1 of the starter kit.
bat20
This directory contains Windows batch files used to start the various Jini services needed to support the example and the two raytrace application programs. These batch files are for running this example with v2.0 of the starter kit.
bin20
This directory contains Bourne shell scripts used to start the various Jini services needed to support the example and the two raytrace application programs. These shell scripts are for running this example with v2.0 of the starter kit.
lib
This directory contains the results of the builds from both the ex1 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.
The Ant build script copies these two files (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
This directory contains policy files needed to run the examples.
config
This directory contains config 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.
manifest
This directory contains the manifest files used to help construct the JAR files.
index.html
This file.

Running with starter kit v1.2.1

This 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.

Running in the UNIX operating environment

Files from the following directories are used to run the raytrace example under starter kit v1.2.1:

bin12
This directory contains shell scripts used to start the required Jini services and the raytrace application programs.
ex1
This directory contains the source code for the raytrace application.
policy
This directory contains the policy files.
lib
This directory contains the JAR files built from the raytrace source code. They include: trace1.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:

  1. cd bin12
    All of the scripts needed to be run are located in this directory.
  2. Edit the JINI_HOME.sh file
    Within this file is a definition for the environment variable 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.
  3. Ensure that no HTTP servers are running on ports 8081 and 8082
    This example will start two HTTP servers: one servicing requests on port 8081 for JAR files in the starter kit lib directory, and another servicing requests on port 8082 for JAR files in the local lib directory.
  4. Ensure that rmid is not running
    This example will start rmid to support the activatable service Reggie (a Jini lookup service). If rmid is running type rmid -stop at a command prompt.
  5. Ensure that no other Jini services are running
    If such services are running, kill those processes.
  6. Start the example
    Type 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.
  7. Wait for the applications to complete their start up
    The 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).
  8. Follow the instruction in the API documentation
    The API documentation for 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.
  9. Quit the trace and worker applications
    Once the raytrace image has been created you may exit the two raytrace applications. You may need to locate the processes explicitly to kill them. The worker is executed in the process that mentions ../lib/worker1.jar on its command line and the trace application is executed in the process that mentions trace1.jar on its command line.
  10. Stop rmid
    Even after quitting the two raytrace applications, there are still Jini services running in the background that were started by the 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.
  11. Stop Outrigger
    The Outrigger process mentions transient-outrigger.jar on its command line. Kill that process.
  12. Stop the two HTTP servers
    The 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.

Running in the Microsoft Windows operating environment

Files from the following directories are used to run the raytrace example under starter kit v1.2.1:

bat12
This directory contains Windows batch files used to start the required Jini services and the raytrace application programs.
ex1
This directory contains the source code for the raytrace application.
policy
This directory contains the policy files.
lib
This directory contains the JAR files built from the raytrace source code. They include: trace1.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:

  1. cd bat12
    All of the batch files needed to be run are located in this directory.
  2. Edit the JINI_HOME.bat file
    Within this file is a definition for the environment variable 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.
  3. Ensure that no HTTP servers are running on ports 8081 and 8082
    This example will start two HTTP servers: one servicing requests on port 8081 for JAR files in the starter kit lib directory, and another servicing requests on port 8082 for JAR files in the local lib directory.
  4. Ensure that rmid is not running
    This example will start rmid to support the activatable service Reggie (a Jini lookup service). If rmid is running type rmid -stop at a command prompt.
  5. Ensure that no other Jini services are running
    If such services are running, kill those processes.
  6. Start the example
    Type 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.
  7. Wait for the applications to complete their start up
    The 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).
  8. Follow the instruction in the API documentation
    The API documentation for 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.
  9. Quit the trace and worker applications
    Once the raytrace image has been created you may exit the two raytrace applications. You may need to locate the processes explicitly to kill them. The worker is executed in the process that mentions ..\lib\worker1.jar on its command line and the trace application is executed in the process that mentions trace1.jar on its command line.
  10. Stop rmid
    Even after quitting the two raytrace applications, there are still Jini services running in the background that were started by the 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.
  11. Stop Outrigger
    The Outrigger process mentions transient-outrigger.jar on its command line. Kill that process.
  12. Stop the two HTTP servers
    The 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.

Final notes on the v1.2.1-compatible scripts

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.

Running with starter kit v2.0

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.

Running in the UNIX operating environment

Files from the following directories are used to run the raytrace example under starter kit v2.0:

bin20
This directory contains shell scripts used to start the required Jini services and the raytrace application programs.
ex2
This directory contains the source code for the raytrace application.
policy
This directory contains the policy files.
lib
This directory contains the JAR files built from the raytrace source code. They include: trace2.jar, trace2-dl.jar, and worker2.jar. It should also include jsk-platform.jar and jsk-resources.jar.
The Ant build script copies these two files 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
This directory contains configuration files used by the v2.0 Jini services. Support for configuration files is one of the key additions to the v2.0 starter kit.

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:

  1. cd lib
    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 this directory yourself. Confirm that these files are present in the lib directory before proceeding. (See the lib directory description above.) Then,
    cd ..
  2. cd bin20
    All of the scripts needed to be run are located in this directory.
  3. Edit the JINI_HOME.sh file
    Within this file is a definition for the environment variable 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.
  4. Ensure that no HTTP servers are running on ports 8081 and 8082
    This example will start two HTTP servers: one servicing requests on port 8081 for JAR files in the starter kit lib directory, and another servicing requests on port 8082 for JAR files in the local lib directory.
  5. Ensure that no other Jini services are running
    If such services are running, kill those processes.
  6. Start the example
    Type 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.
  7. Wait for the applications to complete their start up
    The 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).
  8. Follow the instruction in the API documentation
    The API documentation for 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.
  9. Quit the trace and worker applications
    Once the raytrace image has been created you may exit the two raytrace applications. You may need to locate the processes explicitly to kill them. The worker is executed in the process that mentions ../lib/worker2.jar on its command line and the trace application is executed in the process that mentions trace2.jar on its command line.
  10. Stop Phoenix
    Phoenix is an activation daemon that provides improved activation facilities over 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).
  11. Stop Reggie
    The termination of the Phoenix process should also terminate the Reggie process. If Reggie continues to run even after the destruction of the Phoenix process it should be terminated explicitly.
  12. Stop Outrigger
    The Outrigger process mentions start-transient-jrmp-outrigger.config on its command line. Kill that process.
  13. Stop the two HTTP servers
    The 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.

Running in the Microsoft Windows operating environment

Files from the following directories are used to run the raytrace example under starter kit v2.0:

bat20
This directory contains Windows batch files used to start the required Jini services and the raytrace application programs.
ex2
This directory contains the source code for the raytrace application.
policy
This directory contains the policy files.
lib
This directory contains the JAR files built from the raytrace source code. They include: trace2.jar, trace2-dl.jar, and worker2.jar. It should also include jsk-platform.jar and jsk-resources.jar.
The Ant build script copies these two files (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
This directory contains configuration files used by the v2.0 Jini services. Support for configuration files is one of the key additions to the v2.0 starter kit.

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:

  1. cd lib
    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 this directory yourself. Confirm that these files are present in the lib directory before proceeding. See the lib description above. Then,
    cd ..
  2. cd bat20
    All of the batch files needed to be run are located in this directory.
  3. Edit the JINI_HOME.bat file
    Within this file is a definition for the environment variable 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.
  4. Ensure that no HTTP servers are running on ports 8081 and 8082
    This example will start two HTTP servers: one servicing requests on port 8081 for JAR files in the starter kit lib directory, and another servicing requests on port 8082 for JAR files in the local lib directory.
  5. Ensure that no other Jini services are running
    If such services are running, kill those processes.
  6. Start the example
    Type 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.
  7. Wait for the applications to complete their start up
    The 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).
  8. Follow the instruction in the API documentation
    The API documentation for 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.
  9. Quit the trace and worker applications
    Once the raytrace image has been created you may exit the two raytrace applications. You may need to locate the processes explicitly to kill them. The worker is executed in the process that mentions ..\lib\worker2.jar on its command line and the trace application is executed in the process that mentions trace2.jar on its command line.
  10. Stop Phoenix
    Phoenix is an activation daemon that provides improved activation facilities over 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).
  11. Stop Reggie
    The termination of the Phoenix process should also terminate the Reggie process. If Reggie continues to run even after the destruction of the Phoenix process it should be terminated explicitly.
  12. Stop Outrigger
    The Outrigger process mentions start-transient-jrmp-outrigger.config on its command line. Kill that process.
  13. Stop the two HTTP servers
    The 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.

Final notes on the v2.0-compatible scripts

Here are some final notes on these scripts:

Known bugs

Here are the known bugs:


Copyright 2003 Sun Microsystems, Inc. All Rights Reserved.