The Nuts and Bolts of Compiling and Running JavaSpaces Programs

1. Starting an HTTP Server

   Web servers are used for delivering class code to Jini clients. Let's take a brief look at how this works; for a more in-depth discussion, you should refer to the references given in Resources.

   Whenever you run a JavaSpaces application that needs to serve classes to clients (for example, one that writes entries into a JavaSpace), you need to include "codebase" information on the command line (as you'll see in Running JavaSpaces Programs). The codebase specifies locations--usually URLs--from which a client can download the class files. Whenever your code writes entry objects into the space, the entries get annotated with that information. When a client of the space later removes or reads an entry object from the space, the entry's codebase annotation tells the client where to look for the class code, which is downloaded from an HTTP server (if the class doesn't already exist in the classpath). Typically you'll run a web server on each machine that needs to export code.

   Any web server that's capable of serving documents can do the job, but for convenience, the Jini distribution provides a simple HTTP server in the tools.jar package. Here is the command to start the supplied HTTP server (where optional parameters are shown in square brackets):

   
   java -jar C:\jini1_0_1\lib\tools.jar
     [-port port-number]
     [-dir document-root-dir]
     [-verbose]
   

   For example, on the Windows platform, you might issue this command:

   
   java -jar C:\jini1_0_1\lib\tools.jar
     -port 8081
     -dir C:\jini1_0_1\lib
     -verbose
   

   On Solaris, the equivalent command is:

   
   java -jar /jini1_0_1/lib/tools.jar
     -port 8081
     -dir /jini1_0_1/lib
     -verbose
   

   The JAR file containing the HTTP Server is C:\jini1_0_1\lib\tools.jar; this is an "executable JAR" file (introduced in the Java 2 platform), which means that it starts a default program (in this case, the HTTP server) when it's invoked as shown.

   Here, you started the HTTP Server at port 8081 (if left unspecified, the port number would be 8080). The -dir option specifies which directory the server uses as its "document root." Here, you specified the Jini lib directory as the root, so this HTTP server is able to serve all the Jini JAR files in that directory (as well as other classes you might put there). The -verbose option causes information to be displayed about each request to the server, and is useful for debugging purposes.

   Back to the Top

2. Starting an RMI Activation Daemon

   An RMI Activation Daemon is needed by several other services--the Transaction Manager, the persistent JavaSpaces Service, and the Jini Lookup Service--and an instance of the daemon needs to be run on each of the machines where you run these services. What does an activation daemon do? Suppose you have a service that you'd like to be automatically restarted if it crashes (for instance, if the machine it is running on crashes). Or, suppose you're interested in conserving computational resources, so you'd like a service to be brought down when it has no active clients and reactivated later when a client tries to use the service. An activation daemon takes care of restarting, deactivating, and reactivating your services (such as the Jini services mentioned above).

   Let's see how to start an RMI activation daemon. First, be sure your executable path points to the bin directory of JDK1.2.2; this is where rmid is located. Again, make sure that you haven't modified your CLASSPATH environment variable or placed JAR files in the Java extensions directory.

   Then, to start rmid under Windows or Solaris, the command takes the form:

   
   rmid [-port port-number] [-log dir] 
   

   For example, to start the RMI Activation Daemon on either Windows or Solaris, you could use the command:

   rmid

   to start the daemon on the default port of 1098. For further information on starting rmid, refer to the manual pages for Solaris or Windows.

   Back to the Top

3. Starting a Lookup Service

   A lookup service registers the Jini services available on the local network, and is used by applications to locate services such as a JavaSpace. You can currently choose to use either the RMI registry or the Jini lookup service to serve this purpose, but you should be aware that future versions of Jini services may not support the use of the RMI registry. Therefore, this document only covers using the Jini lookup service (if you really want to use the RMI registry, you can find the details in C:\jini1_0_1\doc\example\StartingService.html).

   The command to start the Jini lookup service takes this form:

   java -Djava.security.policy=security-policy-file -jar C:\jini1_0_1\lib\reggie.jar lookup-codebase security-policy-file log-directory [lookup-group]

   
   

   Let's examine each of the parameters.

   The -Djava.security.policy option to java specifies a "security policy file" for the JVM to use when it runs the lookup service JAR file. The concept of a security policy file is new in the Java 2 platform; it is used to specify what resources a program can use when it runs--for example, whether it is permitted to access system properties, create and listen to socket connections, write to log files, and so on--and what level of privileges to grant to any downloaded code.

   The JAR file containing Sun's implementation of the lookup service (called "reggie") is C:\jini1_0_1\lib\reggie.jar. Once again, this is an executable JAR file, which means it will start running (in a "setup JVM") when it's invoked as shown. First the remaining parameters are parsed, then the reggie lookup service is registered with the RMI Activation Daemon you started earlier on the same machine, and then the setup JVM exits (don't be alarmed that your command returns at this point, and that your DOS window, under Windows, says "Finished"). The lookup service is activatable: It will be restarted automatically by the activation daemon after crashes, and it will shift between "active" and "inactive" states as appropriate. In this case, the activation daemon spawns a new "server JVM" to run the lookup service; in fact, whenever a lookup service is activated, a new "server JVM" is spawned to run that instance of the service.

   The final four parameters deserve a closer look. The lookup-codebase option specifies a URL that points to the reggie-dl.jar file, which contains the code that clients need to download to use the lookup service. For example, you might specify a URL to the HTTP server you started earlier, that is, http://hostname:port/reggie-dl.jar, where hostname is the name or IP address of the machine on which the HTTP server is running, and port is the port number at which it is running. You also need to ensure that the specified HTTP server can access reggie-dl.jar under its document root directory. To test to make sure the JAR file is accessible, you can try accessing it from a browser, using the codebase URL. Since you started the web server in verbose mode, you should see a request logged to its screen, and you'll most likely see a "Save To" dialog box (unless the browser has been configured to handle .jar files).

   The next option, lookup-policy-file, specifies another security policy file. The first security policy file you specified is used only by the setup JVM, while this second (potentially different) security policy file is used by the server JVM whenever the lookup service is reactivated.

   The next parameter, log-directory, specifies an absolute path name to a directory (on the file system where the lookup service is running) where the lookup service writes its logs. It's important to point out that this directory should not already exist, or the setup JVM will exit without registering the lookup service.

   The final, optional parameter, lookup-group, is used to specify a "group" of services for which reggie provides lookup service. Usually, you use the special group name public, which Jini services conventionally join; if you omit the parameter, the default is public.

   Here is an example command for starting the reggie lookup service on Windows:

   java -Djava.security.policy= C:\jini1_0_1\example\lookup\policy.all -jar C:\jini1_0_1\lib\reggie.jar http://hostname:8081/reggie-dl.jar C:\jini1_0_1\example\lookup\policy.all C:\tmp\reggie_log public

   
   

   where hostname is the name or IP address of the machine on which the HTTP server is running.

   Here is what the example command looks like on the Solaris platform:

   java -Djava.security.policy= /jini1_0_1/example/lookup/policy.all -jar /jini1_0_1/lib/reggie.jar http://hostname:8081/reggie-dl.jar /jini1_0_1/example/lookup/policy.all /tmp/reggie_log public

   
   You should note that using the policy.all file as shown is fine when you're experimenting with your code, but it's not recommended for production use, since it grants all permissions to all code (trusted or not). When deploying your code in a production environment, make sure you've devised careful policies that restrict access appropriately (for instance, your policy might state that downloaded code cannot access certain parts of your file system). The topic of security in the Java 2 platform is beyond the scope of this article, but the references in the Resources section will point you in the right direction.

   Back to the Top

4. Starting a Transaction Manager

   If your JavaSpaces applications make use of transactions, you'll need to start a transaction manager service next, with a command of the form:

   java -Djava.security.policy= security-policy-file -Dcom.sun.jini.mahalo.managerName= txnmanager-name -jar C:\jini1_0_1\lib\mahalo.jar txnmanager-codebase security-policy-file log-directory [lookup-group]

   
   

   (Note that, if you're using an RMI registry instead of the Jini Lookup, you'll need to modify the command slightly; refer to C:\jini1_0_1\doc\example\StartingService.html.)

   The executable JAR file containing Sun's implementation of the Transaction Manager Service (called "mahalo") is C:\jini1_0_1\lib\mahalo.jar. Like the lookup service, the transaction manager service is activatable: When the command above is run, a "setup JVM" registers the transaction manager with the RMI activation daemon--which activates the manager in a newly spawned "server JVM"--and then exits. Once again, the command line returns once the registration is complete, and you should see a command prompt.

   The security-policy-file options mean what you would expect, given our previous discussion about starting the Jini Lookup Service: The -Djava.security.policy option governs the permissions the setup JVM uses, while the second security-policy-file option specifies the permissions that the server JVM uses whenever the Transaction Manager Service is activated.

   The option -Dcom.sun.jini.mahalo.managerName allows you to specify a name (such as "TransactionManager") for the transaction manager if you wish: this name becomes an attribute attached to the transaction manager in the lookup service, and can be used to look up this particular transaction service later on.

   Just as you did with the lookup service, you need to supply a codebase option to the service, specifying a URL to the mahalo-dl.jar file, which contains the code that clients need to download to use the transaction manager service. For example, you might supply a URL pointing to the hostname and port number of the HTTP server you started earlier. Be sure that the specified HTTP server can access mahalo-dl.jar under its root directory. Once again, you may want to try accessing the JAR file using a web browser and your codebase URL, to make sure the file is accessible.

   The next parameter, log-directory, should specify an absolute path name to a directory (on the file system where the Transaction Manager service is running) where the service writes its logs. You should make sure that the log file doesn't already exist.

   For the last (optional) parameter, you can specify the name of a Jini group for the Transaction Manager to join; for example, public means the manager should become part of the public group.

   Here's an example of starting a Transaction Manager, using the Jini Lookup service, on Windows:

   java -Djava.security.policy= C:\jini1_0_1\example\txn\policy.all -jar C:\jini1_0_1\lib\mahalo.jar http://hostname:8081/mahalo-dl.jar C:\jini1_0_1\example\txn\policy.all C:\tmp\txn_log public

   
   

   where again, hostname is the name or IP address of the machine on which the HTTP server is running. On Solaris, the command looks like this:

   java -Djava.security.policy= /jini1_0_1/example/txn/policy.all -jar /jini1_0_1/lib/mahalo.jar http://hostname:8081/mahalo-dl.jar /jini1_0_1/example/txn/policy.all /tmp/txn_log public

   
   

   Back to the Top

5. Starting a JavaSpaces Service

   Now that you've started all the supporting services (HTTP Server, RMI Activation Daemon, Jini Lookup Service, and Transaction Manager Service), you can finally start a JavaSpaces service (Sun's implementation is known as "outrigger"). You can choose to start either a JavaSpaces service called TransientSpace (one that doesn't maintain data across crashes and restarts of the space) or a persistent JavaSpaces service called FrontEndSpace (one that does maintain data across crashes and restarts).

   Starting a Transient JavaSpace

   To start a TransientSpace JavaSpaces service, given that you're running a Jini Lookup Service, the command takes the following form:

   java -Djava.security.policy=security-policy-file -Djava.rmi.server.codebase=javaspace-codebase -Dcom.sun.jini.outrigger.spaceName=space-name -jar C:\jini1_0_1\lib\transient-outrigger.jar [lookup-group]

   
   

   (Refer to C:\jini1_0_1\doc\example\StartingService.html for the details of formatting the command if you're using an RMI registry instead.)

   Let's examine the parameters. The security-policy-file option governs the permissions the JVM uses when running the JavaSpaces service. The javaspace-codebase option specifies a URL that points to the outrigger-dl.jar code that clients must download in order to use the JavaSpaces service. The -Dcom.sun.jini.outrigger.spaceName option is used to specify a name for the JavaSpaces service (for example, "JavaSpaces"). And as you saw with the transaction manager service, you can optionally specify the name of a Jini community for this service to join.

   It's worth noting here that a transient JavaSpace service is not an activatable service, and the command above is handled by just a single JVM. This is why you don't need to pass additional arguments (codebase, security-policy-file, log-directory) at the end of the command as you did for the lookup service and transaction manager service. The JVM that executes the command will continue to run until the JavaSpaces service exits or gets killed, so unlike the activatable services, you will not be returned to the command prompt while the space is running.

   Here's an example of starting a transient JavaSpace, using the Jini Lookup service, on Windows:

   java -Djava.security.policy= C:\jini1_0_1\example\books\policy.all -Djava.rmi.server.codebase= http://hostname:8081/outrigger-dl.jar -Dcom.sun.jini.outrigger.spaceName=JavaSpaces -jar C:\jini1_0_1\lib\transient-outrigger.jar public

   
   

   On the Solaris platform, the equivalent command looks like this:

   java -Djava.security.policy= /jini1_0_1/example/books/policy.all -Djava.rmi.server.codebase= http://hostname:8081/outrigger-dl.jar -Dcom.sun.jini.outrigger.spaceName=JavaSpaces -jar /jini1_0_1/lib/transient-outrigger.jar public

   
   Again, you should note that the policy.all file is fine for your code experimentation, but you should revisit the security policy issue when you deploy your code in a production environment (see the Resources section).

   Starting a Persistent Javaspace

   In a deployment environment, you're likely going to want to run a persistent FrontEndSpace JavaSpaces service rather than a transient JavaSpaces service. A FrontEndSpace is able to maintain its data, even through crashes and restarts of the space.

   To start a FrontEndSpace JavaSpaces service, given that you're running a Jini Lookup Service, the command takes the following form:

   java -Djava.security.policy= security-policy-file -Dcom.sun.jini.outrigger.spaceName= space-name -jar C:\jini1_0_1\lib\outrigger.jar javaspace-codebase security-policy-file log-directory [lookup-group]

   
   

   Since FrontEndSpace is an activatable JavaSpaces service, you'll notice some differences from starting a transient space. First, the codebase is specified differently. Second, you must supply a second security policy file (as you did when starting the lookup service and the transaction manager, to be used when the service is reactivated by the RMI Activation Daemon). Last, you must supply an absolute path name to a directory where the JavaSpaces service writes log files.

   Note that outrigger.jar contains all the classes needed for the JavaSpaces service to run a FrontEndSpace. Here's an example of starting a FrontEndSpace, using a Jini Lookup service, on the Windows platform:

   java -Djava.security.policy= C:\jini1_0_1\example\books\policy.all -jar C:\jini1_0_1\lib\outrigger.jar http://hostname:8081/outrigger-dl.jar -Dcom.sun.jini.outrigger.spaceName=JavaSpaces C:\jini1_0_1\example\books\policy.all C:\tmp\js_log public

   
   

   Here's an example of starting a FrontEndSpace on Solaris:

   java -Djava.security.policy= /jini1_0_1/example/books/policy.all -jar /jini1_0_1/lib/outrigger.jar http://hostname:8081/outrigger-dl.jar -Dcom.sun.jini.outrigger.spaceName=JavaSpaces /jini1_0_1/example/books/policy.all /tmp/js_log public

   
   

   As you saw with other activatable services, issuing these commands returns a command prompt.

   Back to the Top

Compiling JavaSpaces Programs

If you wish, you can experiment with a very simple " Hello World " program from JavaSpaces Principles, Patterns and Practice. You need to edit the compile.bat file and replace localhost:8081 with the IP address and port number of your web server, and then you can simply run compile.bat and runit.bat to get the example up and running under Windows.

When compiling JavaSpaces programs, the javac compiler (and later the java bytecode interpreter) may need access to several different jar files:

• jini-core.jar, which contains the core Jini interfaces and classes and is needed whenever your program makes use of leases or events, for example.

• jini-ext.jar, which contains additional interfaces that are useful in building Jini applications, including the JavaSpaces interface.

• sun-util.jar, which contains a set of useful helper utilities. These classes may change, however, since they are regarded as non-standard.

• space-examples.jar, which contains various JavaSpaces technology examples and includes the classes com.sun.jini.mahout.Locator, com.sun.jini.outrigger.LookupFinder, and com.sun.jini.outrigger.Finder, which are needed when compiling the SpaceAccessor.java code found in Chapter 1 of the JavaSpaces Principles, Patterns and Practice.

When compiling your JavaSpaces programs, supply a -classpath option to the javac compiler. For example, to compile ExampleProgram.java on Windows, the command might look like this:

javac -d . -classpath 
  C:\jini1_0_1\lib\jini-core.jar;
  C:\jini1_0_1\lib\jini-ext.jar;
  C:\jini1_0_1\lib\sun-util.jar;
  C:\jini1_0_1\lib\space-examples.jar;.;
  ExampleProgram.java

Note that these JAR files might not all be necessary for every compilation; it depends on the specifics of the program you're compiling. Also note the use of the -d option; here it is used to specify that class files should be created in the current directory. The .; appearing at the end of the classpath option indicates that the current directory is searched for classes, along with the JAR files listed. You should tailor these options according to where you want your class files stored.

On Solaris, the equivalent command looks like this:

javac -d . -classpath 
  /jini1_0_1/lib/jini-core.jar:
  /jini1_0_1/lib/jini-ext.jar:
  /jini1_0_1/lib/sun-util.jar:
  /jini1_0_1/lib/space-examples.jar:.:
  ExampleProgram.java

Alternately, you could specify the required JAR files in the CLASSPATH environment variable or place JAR files in the Java extensions folder. However, during the code development phase--when you're likely running a JavaSpaces service and client programs on the same machine--avoiding these modifications to the classpath environment is a good policy: It helps to avoid unintended sharing of class files, and to simulate a deployment environment--when Jini services, such as a JavaSpace, and client programs that make use of them are likely to run on different machines. Avoiding use of the CLASSPATH and Java extensions can help to reduce the problems you'll encounter when you move from development to deployment.

Back to the Top

Running JavaSpaces Programs

java -Djava.security.policy=
C:\jini1_0_1\example\books\policy.all
  -Doutrigger.spacename=JavaSpaces
  -Dcom.sun.jini.lookup.groups=public
  -cp C:\jini1_0_1\lib\space-examples.jar;
      C:\jini1_0_1\lib\jini-core.jar;
      C:\jini1_0_1\lib\jini-ext.jar;
  -Djava.rmi.server.codebase=
  http://hostname:8081/space-examples-dl.jar
  ExampleProgram

java -Djava.security.policy=
/jini1_0_1/example/books/policy.all
  -Doutrigger.spacename=JavaSpaces
  -Dcom.sun.jini.lookup.groups=public
  -cp /jini1_0_1/lib/space-examples.jar:
      /jini1_0_1/lib/jini-core.jar:
      /jini1_0_1/lib/jini-ext.jar:
  -Djava.rmi.server.codebase=
  http://hostname:8081/space-examples-dl.jar
  ExampleProgram

Let's take a look at each of the parameters. The -Djava.security.policy option specifies the path to the security policy file you'd like your program to use when it runs downloaded code (for example, if your program retrieves an entry from a JavaSpace and invokes one of its methods). If you find none of the policy files provided in the Jini distribution to be suitable, you'll have to modify one to meet your needs (see the Resources section).

With the -Doutrigger.spacename option, you can specify the name of the specific JavaSpaces service you'd like your program to use (with the command above, you're specifying that your program should interact with a space called "JavaSpaces", if one can be found, not one called "Old JavaSpace" or anything else.

The -Dcom.sun.jini.lookup.groups option specifies which Jini community this program runs under (here, the public group).

The Java bytecode interpreter (java) needs access to several JAR files; the exact ones depend on what your program does. Refer to the list of JAR files in Compiling JavaSpaces Programs.

The codebase property needs to be set if your program is exporting downloadable code, for instance if your program is writing entries into a JavaSpace. In this case, when other programs read or remove those entries, they need to know where they can download the classes for those entries. This information is provided by your program, which annotates the entries it writes into the space with information from the codebase property. The codebase property also needs to be set if your program is requesting notification services from any of the Jini services; in this case the "listener" code needs to be exported.

Back to the Top

Summary

If you've successfully followed all the steps to this point, congratulations! By now you should have a pretty good idea how to prepare your machine environment and start the required services for JavaSpaces programs, as well as how to compile and run the programs. You should be ready to get down to the fun business of writing distributed applications with JavaSpaces technology.

If you're still having trouble getting up and running, you may want to refer to some of the references given under Resources. If you'd like to gain a more in-depth understanding of various topics important to how JavaSpaces programs run, but which have been covered only briefly in this article--for instance, codebase, RMI activation, and Java 2 security--the Resources also point you in the right direction for further exploration.

Back to the Top

Resources

For an exploration of space-based programming concepts and code examples, as well as an in-depth look at the JavaSpaces technology APIs, refer to Sun's official Jini Technology Series book on the topic: JavaSpaces Principles, Patterns, and Practice, by Eric Freeman, Susanne Hupfer, and Ken Arnold (Addison-Wesley, 1999). You may wish to experiment with the code from the book, which is downloadable from The Jini Technology Series.

The Jini specifications from Sun Microsystems are the definitive references on the JavaSpaces API (starting with the Jini Entry Specification and the JavaSpaces Specification).

The Jini specifications are also provided in The Jini Specification, another book in the Jini Technology Series, by Ken Arnold, Bryan O'Sullivan, Robert W. Scheifler, Jim Waldo, and Ann Wollrath (Addison-Wesley, 1999).

If you encounter problems as you try to get your JavaSpaces programs up and running, a good first place to look is the Release Notes and other documentation that you installed with the Jini and JavaSpaces software: C:\jini1_0_1\index.html (/jini1_0_1/index.html on Solaris)

Core Jini, by W. Keith Edwards (Prentice-Hall, 1999), provides in-depth treatment of Jini technology, and covers many nitty-gritty details of getting Jini (including JavaSpaces) programs up and running.

Whether you wish to share information with other developers (including the Sun engineers that developed the Jini and JavaSpaces technologies), or to seek troubleshooting advice, the official JavaSpaces-users mailing list is the place to go.

The Jini-users mailing list also has a considerable amount of JavaSpaces-related discussion.

For more detailed information on the use of codebase, refer to the article How Codebase Works, or to the tutorial Dynamic Code Downloading Using RMI.

For more information on Java 2 Security and creating policy files, refer to the book Just Java 2.0, by Peter van der Linden, or to the tutorial Security in Java 2 SDK 1.2.

For further information on RMI Activation and how it relates to the Jini and JavaSpaces services, an archived Javaspaces-users article-- Part 1 and and Part 2 -- provides a detailed discussion. Sun's official RMI specification is the definitive reference.

About the Author

Susanne Hupfer recently co-authored "JavaSpaces Principles, Patterns, and Practice", the official Sun Microsystems Jini Series book on the JavaSpaces distributed computing technology. Dr. Hupfer is a Senior Software Engineer at Mirror Worlds Technologies, a Java- and Jini-based software applications company, and a Research Affiliate in the Department of Computer Science at Yale University.

Thanks to Robert Resendes, Eric Freeman, Peter Sparago, and Elisabeth Freeman for their thoughtful comments on drafts of this article.