Exer

ise lass 04/03/04: JAVA RMI

The aim of this tutorial is to explore JAVA RMI. At the end of this lass you
should be able to write, ompile and run some simple JAVA RMI programs.
We will use a shared whiteboard as an example (pp. 194-200). This is a
distributed program that allows a group of users to share a ommon view of
a drawing surfa e ontaining graphi al obje ts, su h as re tangles, lines and
ir les, ea h of whi h has been drawn by one of the users.
The whiteboard server has a version number (an integer) that it in rements
ea h time a new shape arrives. This version number is atta hed to the new
shape. The server provides operations allowing lients to enquire about its
version number and the version number of ea h shape, so that they may avoid
fet hing shapes that they already have.
NOTICE: we will implement a text-only version of this example, be ause
we are mainly interested in the ommuni ation between remote obje ts, not in
the graphi al details.

Prerequisites
 We assume familiarity with Java. You should be able to write, ompile

and run a simple Java program (CS1PR1).

 We assume familiarity with Obje t-Oriented programming. You should

be able to understand the dieren e between a lass and an instan e of

that lass. (CS1PR1).

 You need a working JDK installation. Again, you should know how to use

JDK from previous ourses (CS1PR1).

 We assume familiarity with the denition of JAVA interfa es (CS1PR1

and CS1PR2).

 You need some basi understanding of Data Stru tures (CS1DST).

Graphi al obje ts will be stored using the JAVA lass Ve tor() from java.util.*.

 You need a networked PC. Any PC in the labs is ne, Linux or Windows.

What should you do?

You will nd some Java programs below. First, you will nd the ode for
the whiteboard server. Then, you will nd a simple lient to test the server
implementation. Everything is ommented thoroughly. Here's the best ourse
of a tions to maximise your learning during this session:
1. Read the notes: they explain the meaning of the ode. This will help you
if you are not too ondent with your JAVA.
2. Write the programs yourself (i.e., open an editor, type them, and save
them appropriately).
1

3. Compile the programs.

4. Run the programs.
Graphi al obje ts

We rst de lare a lass for the obje ts that will be drawn on the whiteboard. As
we are not going to implement graphi al intera tions, we do not import graphi al
pa kages. However, this should be the le where to store all the graphi al
information, like olours, oordinates, et . In our example, a Graphi alObje t
has a type only (e.g. Cir le, Re tangle, et ). Noti e that Graphi alObje t must
implement the Serializable interfa e, as obje ts of this lass will be passed using
JAVA RMI.
// *********************************************************
// * Graphi alObje t.java
*
// * Comments follow the ommented line
*
// *********************************************************
import java.io.Serializable;
// Important! The lass must implement the Serializable interfa e
publi lass Graphi alObje t implements Serializable{
publi String type;
// A variable for the hara teristi s of the graphi al obje t
// In a proper example, here you should de lare oords, olours, et .
publi Graphi alObje t() { }
// an empty ontrsu tor
publi Graphi alObje t(String aType) {
// a better onstru tor

type = aType;
// just setting up the variable above.

publi void print(){

// a simple method to print all the details.
System.out.print(type);
}

Remote interfa es

We now dene the interfa es of the server. Remote interfa es (p. 173) spe ify
the remote methods implemented by a remote obje t, i.e. the methods that
may be invoked by lients.
There are two kind of remote obje ts on the server: the whiteboard itself
is seen as a list of shapes, and its methods are dened in the ShapeList.java
interfa e.
At the same time, shapes are drawn on the whiteboard, and ea h of these
shapes is seen as an obje t. The methods of the \shape obje ts" are dened in
the Shape.java interfa e.
//
//
//
//
//
//

*********************************************************
* ShapeList.java, page 195
*
* Comments follow the ommented line.
*
* This interfa e des ribe the methods implemented by
*
* the whiteboard, whi h is a remote obje t
*
*********************************************************

import java.rmi.*;
// THIS IS IMPORTANT!!
import java.util.Ve tor;
// Just a lass to store the list of shapes drawn on the board
publi interfa e ShapeList extends Remote {
// IMPORTANT! We are extending Remote here, to denote that
// this is a remote obje t.
Shape newShape(Graphi alObje t g) throws RemoteEx eption;
// This method will be used to add a new shape to the board.
// Noti e that an interfa e is returned (Shape). This is the ase
// with all remote obje ts (see pp.195-196)
Ve tor allShapes()throws RemoteEx eption;
// This method will return the list of all shapes.

int getVersion() throws RemoteEx eption;

// This method will return an integer

//
//
//
//
//
//

*********************************************************
* Shape.java, page 195
*
* Comments follow the ommented line.
*
* This interfa e des ribes the methods implemented by *
* the remote obje ts drawn on the whiteboard
*
*********************************************************

import java.rmi.*;
// IMPORTANT (see above)
publi interfa e Shape extends Remote {
//IMPORTANT (see above)
int getVersion() throws RemoteEx eption;
// Just returning the version of this Shape

Graphi alObje t getAllState() throws RemoteEx eption;

// This method returns an instan e Graphi alObje t

Server lasses

Here we set up the server lasses implementing the two interfa es presented
above. The rst lass is ShapeServant.java and implements the methods of
the interfa e Shape.java, i.e. ShapeServant.java implements the methods of the
shapes drawn on the board.
// *********************************************************
// * ShapeServant.java, page 195
*
// * Comments follow the ommented line.
*
// * This is the implementation of Shape.java
*
// *********************************************************
import java.rmi.*;
// IMPORTANT (see above)
import java.rmi.server.Uni astRemoteObje t;
// ShapeServant extends Uni astRemoteObje t, whi h
// provides remotes obje ts that live only as long
// as the pro ess in whi h they are reated (p.198).
publi lass ShapeServant extends Uni astRemoteObje t implements Shape {
// De laring the lass. NOTICE! It implements the Shapen interfa e.
int myVersion;
Graphi alObje t theG;
// ea h shape has a version, and a Graphi alObje t.
publi ShapeServant(Graphi alObje t g, int version)
throws RemoteEx eption{
// The onstru tor. NOTICE that it throws a RemoteEx eption
// The onstru tor is alled by ShapeListServant.java
theG = g;
myVersion = version;
System.out.println("Created Shape with ID "+version);
// just setting up the lo al variables
}
publi int getVersion() throws RemoteEx eption {
return myVersion;
// just returning the version
}

publi Graphi alObje t getAllState() throws RemoteEx eption{

return theG;
// returning the Graphi alObje t
}

The following is the lass for the whiteboard, ShapeListServant.java. ShapeListServant.java implements the interfa e ShapeList.java.
// *********************************************************
// * ShapeListServant.java
*
// * Comments follow the ommented line.
*
// * This ode implements the interfa e
*
// * ShapeList.java
*
// *********************************************************
import java.rmi.*;
import java.rmi.server.Uni astRemoteObje t;
// See omments above for these pa kages
import java.util.Ve tor;
// This is a Ve tor data stru ture (an Array)
publi lass ShapeListServant extends Uni astRemoteObje t
implements ShapeList{
// See omments for ShapeServant.java; this lass implements
// the ShapeList interfa e.
private Ve tor theList;
// The shapes on the whiteboard are stored in this Ve tor
// alled theList.
private int version;
// a number (in reasing)
publi ShapeListServant()throws RemoteEx eption{
// Constru tor: at the beginning, no shapes and version=0
theList = new Ve tor();
version = 0;
}
publi
//
//
//

Shape newShape(Graphi alObje t g) throws RemoteEx eption{

this method is used to add a shape to the list, passing
a graphi al obje t (remember that Graphi alObje t is
Serializable!

version++;
// First, in rease the version by one.
Shape s = new ShapeServant( g, version);
// Then, reate a new Shape obje t. NOTICE: Shape is
// a remote obje t, see ShapeServant.java.

theList.addElement(s);
// Now adding the the Shape obje t to the Ve tor

return s;
// Returning a referen e to the remote obje t (Shape)

publi Ve tor allShapes()throws RemoteEx eption{

// This method is used to retrive the whole list
return theList;
}
publi int getVersion() throws RemoteEx eption{
// Just returning the urrent version.
return version;
}

The exe utable server.

The following is the implementation for the exe utable Server, Whiteboard.java.
// *********************************************************
// * Whiteboard.java
*
// * Comments follow the ommented line.
*
// * This ode implements the Server.
*
// *********************************************************
import java.rmi.*;
// Obviously...
publi lass Whiteboard {
publi stati void main(String args[){
// Just the main method here.
System.setSe urityManager(new RMISe urityManager());
// First, set up a se urity manager. It prote ts the lo al
// resour es to ensure that the lasses that are loaded
// from remote sites annot have any effe t on resour es
// su h as files (see p.199)
System.out.println("Main running");
try{
ShapeList aShapelist = new ShapeListServant();
// First, reate an instan e of ShapeListServant, i.e.
// reate an empty board...
System.out.println("Whiteboard reated");
Naming.rebind("ShapeList", aShapelist);
// This is used to bind the the instan e of ShapeListServant
// reated above (aShapelist) to the RMIregistry (p.197).
// RMIregistry is the binder for Java RMI (see p.180).

System.out.println("Whiteboard ready");
}
at h(Ex eption e) {
System.out.println("ShapeList server main " +
e.getMessage());
}

Compiling and running the server

To ompile and run a JAVA RMI ode some preliminary operations are required.
1. Compile the server: verb+java Whiteboard.java+
2. Compile the remote obje ts. For this, you need the rmi ompiler (RMI
ompiler). You have to ompile ShapeServant and ShapeListServant:
 rmi ShapeServant
 rmi ShapeListServant

This reates the lasses for proxies, dispat hers and skeletons (see p.179
and g. 5.6 p. 177).
3. Laun h the JAVA RMI binder, alled rmiregistry: rmiregistry & (NOTICE: THIS CAN BE DIFFERENT UNDER WINDOWS XP).
4. Create a permission le, all it mypoli y, whose ontent is:
grant {
permission java.se urity.AllPermission;
};

5. Now you an run the server:

java -Djava.se urity.poli y=mypoli y Whiteboard
6. The server is now waiting for onne tions. When a graphi al obje t is
reated, you should see a message on the server terminal.

A lient for Whiteboard.java

The following is the implementation for a lient of Witheboard. The name of the
lient is ShapeListClient.java. It is a very basi version, just to understand how
to invoke remote methods and pass obje ts. See below for possible extensions
of this.
// *********************************************************
// * Whiteboard.java
*
// * Comments follow the ommented line.
*
// * This ode implements the Server.
*
// *********************************************************
import java.rmi.*;
// Obviously...
import java.util.Ve tor;
publi lass ShapeListClient{
publi stati void main(String args[){
if (args.length < 2) {
// Che king the orre t number of arguments.
// This he k ould be improved.

System.out.println(
"ERROR. Usage: java " +
" ShapeListClient ServerName " +
"{Read|Write} Shape");
System.exit(1);

String option = args[1;

if(System.getSe urityManager() == null){
System.setSe urityManager(new RMISe urityManager());
// See omments for Whiteboard.java
}
else
System.out.println("Already has a se urity manager");
ShapeList aShapeList = null;
// This is a ShapeList obje t, initially it is not
// referen ing any obje t
try{

10

String onne tion = "//"+args[0+"/ShapeList";

System.out.println( onne tion);
aShapeList = (ShapeList) Naming.lookup( onne tion);
// IMPORTANT! Here we are trying to obtain a remote
// referen e for the Whiteboard.
System.out.println("Found server");
Ve tor sList = aShapeList.allShapes();
// IMPORTANT!!! This method is exe uted on the server!
System.out.println("Got ve tor");
if(option.equals("Read")){
// Just printing the list of Shapes
for(int i=0; i<sList.size(); i++){
Graphi alObje t g =
((Shape)sList.elementAt(i)).getAllState();
// A Graphi alObje t is reated here using
// .getAllState() on the server!
g.print();
System.out.println("");
}
} else {
// Writing a new obje t on the server
String shapeType = args[2;
Graphi alObje t g = new Graphi alObje t(shapeType);
System.out.println("Created graphi al obje t");
aShapeList.newShape(g);
// Adding the shape to the list
// i.e.: g is passed to the method newShape on the Server
}

System.out.println("Stored shape");

}
at h(RemoteEx eption e) {
System.out.println("allShapes: " + e.getMessage());
}
at h(Ex eption e) {
System.out.println("Lookup: " + e.getMessage());
}

11

Compiling and running the lient

To ompile and running the lient you need some preliminary operations. First
of all, the ompilation pro ess depends on whether or not you are running the
lient on the same ma hine where the Whiteboard server is running. If this is
not the ase, you have to start rmiregistry (see step 3 above). Then, prepare a
dire tory where you will store all the required les.
1. Copy in this dire tory ShapeListClient.java, Graphi alObje t.java, Shape.java
and ShapeList.java (i.e. the two interfa es), ShapeServant.java and ShapeListServant.java . Also, you will need the le mypoli y (see above).
2. Compile the lient: verb+java ShapeListClient.java+
3. Compile ShapeServant.java and ShapeListServant.java (using java ).
4. Create the skeletons et . for ShapeServant and ShapeListServant: rmi
ShapeServant and rmi ShapeListServant (see above).
Now you are ready to run the lient. Examples:

java -Djava.se urity.poli y=mypoli y ShapeListClient hostname Write Re tangle

java -Djava.se urity.poli y=mypoli y ShapeListClient hostname Read

You should see something on the s reen of the server when a shape is reated.

12

Exer ises
This part is for the interested students ;-). You are not required to
do these exer ises, and you are not supposed to know all the details
below.

The distributed appli ation presented here ould be extended in a number

of ways.
For the Server:

 Shapes an be added to the board, but annot be removed. Add a

.remove(int) method to ShapeList.java. The argument is the version of

the Shape you want to remove. Hint: add the method to ShapeList.java,
and its implementation to ShapeListServant.java. In the implementation,
you may nd useful the following methods of Ve tor: IndexOf(Obje t), removeElementAt(int), equals(Obje t). Also, you need to hange the lient
to a ept a new request.

For the Client:

 Add a ontrol for deleting a shape. Maybe you want to hange the Read

ommand, in a way that you an a ess shape id's.

 (This is not easy) Ideally, a lient should be ontinuously running, and

making onne tions to the whiteboard server on e every T se onds (see

p.46, problems related to a hing and repli ation). You an obtain this
behaviours by extending Thread, and using the method sleep(T) in a loop
that ontinuously query the server.

 (This is not easy) If you import the relevant graphi al pa kages, you

an hange Graphi alObje t.java and ShapeListClient.java to implement

a proper whiteboard.

13