Figure 1: Directory structure illustrating the relative relationship between directories created to run a JavaSpaces application
|
|
NOTE: The following has been written for staff and students in the Computer Science Department at the University of Liverpool and thus assumes the hardware setup and network configuration available within that Department. It is also assumes the Linux OS. |
JavsSpaces is a technology, founded on Java RMI and Jini, to allow the creation of distributed software applications. This WWW page, and its connected pages, describe the process of creating a JavaSpaces application from scratch, i.e. from downloading jini, through writing appropriate shell scripts and code, to running the final application. The process will be described in a step by step manner as follows:
[1] Downloading the appropriate APIs:
Section 2 describes how this is done.
[2] Creating a number of directories in which to store classes, log file etc. This is described in Section 3.
[3] Writing and compiling a JavaSpaces application. As a first attempt we will write a classic HelloWorld application (see Section 4).
[4] Creating a Security Policy file (Section 5).
[5] Starting up the additional services required. JavaSpaces relies on RMI (Remote Method Invocation) and Jini which extends RMI. We thus need to start the RMI activation daemon (rmid) and a lockup service to maintain information about Jini services. This is best done using a sequence of shell scripts as described in Section 6. Note that JavaSpaces also requires a WWW server to enable Jini clients to download class files through RMI, we will umake use of the existing WWW server already running within the Department of Computer Science at Liverpool.
[6] Running the application (Section 7).
Before you start, create a directory in which to place the JSK and JSTK, we will call this directory Java.
To obtain the JSK and JSTK you must be a registered member of the "Java Developer Connection" (its free). To do this go to the Jini System Software Product Offerings page at http://developer.java.sun.com/developer/products/jini/product.offerings.html. Scroll down this page and select "Register and accept the SCSL to access software downloads". This takes you to the "Jini Network Technology" page, scroll down and select "How to download this code" to get to the next page, scroll down and select "proceed to Download". You will be invited to join the "Java Developer Connection".
Once you have registered you will be able to download the Jini Technology Starter Kit (JSK), which includes the JSTK. First complete a license form and then download the zipped JSK file (in June 2002 this was jini-1_2_1-src.zip --- 8135658 bytes) into the Java directory.
Unzip the file. A directory, jini1_2_1, will have been created. "cd" into this and you will see five further directories:
and a file index.html. Open this later using a HTML browser and select "building from the source code". This will take you to another page which will give instructions on how to build the Jini technology packages from the source code, e.g.
gmake PRODUCT=1 all
(in June 2002). The JSTK will be automatically included.
In addition to the Java directory created above you will need a number of additional directories as follows:
[1] Create a directory, JavaSpacesClasses in your public_html directory. The path to this directory will be somthing like /home/staff5/ra/frans/, thus the path to the newly created JavaSpacesClasses directory will be of the form /home/staff5/ra/frans/public_html/ JavaSpacesClasses. Copy the files: (1) reggie-dl.jar, (2) mahalo-dl.jar and (3) outrigger-dl.jar; across from /frans/Java/jini1_2_1/lib to the JavaSpacesClasses directory:
cp ~frans/Java/jini1_2_1/lib/reggie-dl.jar ~frans/public_html/JavaSpacesClasses/. cp ~frans/Java/jini1_2_1/lib/mahalo-dl.jar ~frans/public_html/JavaSpacesClasses/. cp ~frans/Java/jini1_2_1/lib/outrigger-dl.jar ~frans/public_html/JavaSpacesClasses/.
and make sure they are executable.
[2] Create a directory JavaProgs, with a subdirectory JavaSpaces in which we will place all our JavaSpaces application files and packages.
[3] Create a directory in which to place jini log files, we will call it JiniLog and will place this in our home directory ---- /home/staff5/ra/frans/jiniLog/.
[4] To start up the RMI deamon, and the jini and JavaSpaces services, we will write a number of shell scripts (five in total); create a directory Scripts in the JavaSpaces directory created in [2] in which to place these shell scripts.
[5] A bin directory in which to put additional shell scripts. You may already have one of these, if not create one in your home directory (the way that the computer system within the CS department at Liverpool is set up means that a path to this directory, e.g. ~frans/bin/ will already exist.
Figure 1 shows the directory structure yoy should now jave (including the bin and public_html directories. (Later you will also create two more directories, JavaSpacesUtils and HelloWorld, and place them in the /home/staff5/ra/frans/JavaProgs/JacaSpaces directory.)
Figure 1: Directory structure illustrating the relative relationship between directories created to run a JavaSpaces application
Creating JavaSpaces applications is fairly straightforward (assuming a good understanding of Java).
Whatever the application it will need to access a "space". This is best achived by creating an appropriate "JavaSpacesUitils" package (containing a SpaceAccessor class) which can be used by whatever JavaSpaces applications you might wish to create. Such a package is described in detail at spaceAccess.html.
We now need an application class, we will assume the "HelloWorld" application described in helloWorld.html which comprises two classes: Message and HelloWorkd.
Compile all of the above three classes as described in Sub-section 4.1 below. Make sure that the resulting Message and HelloWorkd class files are all stored in the same directory, we will call this directory ~frans/JavaProgs/JavaSpaces/HelloWorld/.
To compile a JavaSpace programme we need to include the paths to the appropriate Jini classes. A shell script to achieve this is presented in Table 1.
javac -classpath /home/staff5/ra/frans/JavaProgs/JavaSpaces/: /home/staff5/ra/frans/Java/jini1_2_1/lib/jini-core.jar: /home/staff5/ra/frans/Java/jini1_2_1/lib/jini-ext.jar: /home/staff5/ra/frans/Java/jini1_2_1/lib/sun-util.jar:. $1 |
Table 1 javacc shell script
The classpath includes paths to our JavaSpaces directory (which contains the SpaceAccessor class --- see spaceAccess.html for details), the jini library packages, and the current directory. $1 is the file to be compiled.
Include the above in your bin directory. Remember to make sure that the shell script is executable.
Normally, to run a Java application we enter java < FILE_NAME >, running a JavaSpaces application is a little more complicated. In Table 2 an appropriate script is presented which we have called javaRun.
java -Xms500m -Xmx500m -Djava.security.policy=policy.all -classpath .:/home/staff5/ra/frans/JavaProgs/JavaSpaces/: /home/staff5/ra/frans/Java/jini1_2_1/lib/space-examples.jar: /home/staff5/ra/frans/Java/jini1_2_1/lib/jini-core.jar: /home/staff5/ra/frans/jini1_2_1/lib/jini-ext.jar $1 |
Table 2 javaRun shell script
Include this script in your application directory (~frans/JavaProgs/JavaSpaces/HelloWorld/ in this case).
Security policy files are external text files with certain syntax and class names. Create a text file (called policy.all) as shown in Table 3.
// Policy.all
// Grant all possible permissions!
grant {
permission java.security.AllPermission;
};
|
Table 3 Policy file
Place copies of this file in:
Below (Table 4) is a shell script (we will call it runJS) to start up the various services and daemons required:
rm -r ~/JiniLog mkdir ~/JiniLog xterm -e ./runrmid & ./runlookup ./runmahalo ./runtspace |
Table 4 runJS shell script
In this shell script we start of by removing the our JiniLog directory and then recreating it (a simple way of emptying the directory of its contents). We then call xterm which is a terminal emulator for the X Window System. The -e option is used to specify the program (and its command line arguments) to be run in the xterm window (in this case in the backgornd --- &). The script to be run in the background is runrmid. Once this is up and running three more shell scripts are invoked: runlookup, runmahalo and runtspace. Each of these is discussed in more detail below.
All the shell scripts described in this section should be placed in your Scripts directory.
The runrmid script (Table 5) starts up the RMI activatuion daemon (rmid). RMI stands for Remote Method Invocation; this allows Java objects running in separate processes/computers to communicate with one another using remote method calls. rmid is a server process that manages the registration, activation and decativation of remote objects. The script is as follows:
echo "runrmid" rmid -J-Dsun.rmi.activation.execPolicy=none -log /home/staff5/ra/frans/JiniLog/rmid.log |
Table 5 runrmid shell script
The -log oprion tells rmid to write log text to the indicated file in the JiniLog directory created previously.
The runlookup shell script (Table 6) is used to start up a lookup service to maintain information about available Jini services, and to enable clients to discover and use those swervices.
echo "runlookup" java -jar /home/staff5/ra/frans/Java/jini1_2_1/lib/reggie.jar http://www.csc.liv.ac.uk:80/~frans/JavaSpacesClasses/reggie-dl.jar /home/staff5/ra/frans/Java/jini1_2_1/policy/policy.all /home/staff5/ra/frans/JiniLog/reggie_log frans_group -Xms2m -Xmx4m |
Table 6 runlookup shell script
This contains full paths to the: reggie.jar file in our JavaSpacesClasses ditectort, a policy file, and our JiniLog directory; and a group name (frans_group). www.csc.liv.ac.uk is the hostname of the machine on which the Department's WWW server is running, and 80 specifies the port number from which the WWW server will accept conections. The last two options, -Xms2m -Xmx4m, specify storage requirements.
The runmahalo shell script (Table 7) invokes the security policy created in Section 5.
echo "runmahalo" java -jar -Djava.security.policy= /home/staff5/ra/frans/Java/jini1_2_1/policy/policy.all /home/staff5/ra/frans/Java/jini1_2_1/lib/mahalo.jar http://www.csc.liv.ac.uk:80/~frans/JavaSpacesClasses/mahalo-dl.jar /home/staff5/ra/frans/Java/jini1_2_1/policy/policy.all /home/staff5/ra/frans/JiniLog/mahalo_log frans_group -Xms2m -Xmx4m |
Table 7 runmahalo shell script
Note that this contains a path to the mahalo-dl.jar file copied across to the JavaSpacesClasases directory.
The runtspace sgell script starts the transient JavaSpaces service (the alternative is the persistent JavaSpaces service).
echo "runtspace" java -Xms500m -Xmx500m -jar -Djava.security.policy= /home/staff5/ra/frans/Java/jini1_2-1/policy/policy.all -Djava.rmi.server.codebase=http://www.csc.liv.ac.uk/ ~frans/JavaSpacesClasses/outrigger-dl.jar -Dcom.sun.jini.outrigger.spaceName=frans_space /home/staff5/ra/frans/Java/jini1_2_1/lib/transient-outrigger.jar frans_group |
Table 8 runtspace shell script
Note that the default space name is frans_space, and the script contains a path to the outrigger-dl.jar file copied across to the JavaSpacesClasases directory.
Note: Remember to make sure that all your shell scripts are executable.
To run the above scripts "ssh" into a "Linux box", for example linux10 (login in the usual manner). Once in, "cd" to your Scripts directory and issue the command runJS:
$ ssh linux10 The authenticity of host 'linux11 (138.253.184.151)' can't be established. RSA key fingerprint is 2c:69:23:b3:e8:0c:f1:d7:30:3d:b6:a6:3f:74:4c:b4. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'linux11,138.253.184.151' (RSA) to the list of known hosts. frans@linux11's password: frans$ cd ~frans/JavaProgs/JavaSpaces/Scripts ./runJS
You will see some output:
runlookup using absolute policy path: /home/staff5/ra/frans/JavaProgs/JavaSpaces /Scripts/policy.all runmahalo using absolute policy path: /home/staff5/ra/frans/JavaProgs/JavaSpaces /Scripts/policy.all runtspace
and a "runrmid" window will appear of the form shown in Figure 2.
Figure 2: runrmid window
To stop the servers etc. "kill" the xterm window (top right icon). If you need to you can find out what processes are running on a particular machine using the command ps -fu < USER_NANE >. To find out what machine you are on use uname -a.
We are now ready to run the "HelloWorld" JavaSpaces application described in Section 4 and compiled as described in Sub-section 4.1. Before you start, make sure that the following are contained in the directory ~frans/JavaProgs/JavaSpaces/HelloWorld/ created in section 4:
In the directory ~frans/JavaProgs/JavaSpaces/JavaSpacesUtils/ as described earlier. The overall directory and file structure you should now have is illustrated in Figure 3.
Figure 3: Complete directory structure illustrating the relative relationship between directories and files required to run a JavaSpaces application
In another window log into another (or the same) "Linux box", and "cd" to the directory where your "HelloWorld" programme resides. Then run your programme using the javaRun script developed in Sub-section 4.2, you will see some output of the form:
$ ./javaRun HelloWorld START Create Message entry jiniURL = jini://linux10 spaceName = frans_space Get JavaSpace Message is: Hello World END
A more sophisticated version of the above (involving more than one process) can be found at HellowWorld2.
Java archive files are known as JAR files and are created using the Java Archive Utility. For example:
jar cf
cf = create file
To run a jar file:
$java jar.jar
Created and maintained by Frans Coenen. Last updated 21 August 2003