In the beginning, we plug our patented "Jini'fied Morse code printer" into the network and switch it on. At first, it is unaware that anything else on the network exists. Luckily, Jini has a protocol for getting in touch with other Djinn; it's called Discovery. In our example, Discovery takes the form of a message broadcast to our entire local network asking for any available JLUSs to identify themselves. Each JLUS that hears this broadcast responds by giving our network printer a representative of the JLUS. This representative takes the form of a ServiceRegistrar object. The ServiceRegistrar object works as a proxy to the JLUS. Any work that we want to do with the JLUS we can do by invoking methods on the registrar object.

Figure 10-2 illustrates the concept of Jini Discovery. Here the service finds the local JLUS and obtains an object that functions as an interface.

Figure 10-2. Jini Discovery.

To simplify things, only one JLUS responds to our printer's discovery effort. In reality there could be multiple JLUSs out there, or none at all! (In the last case, we could include in our service implementation code that would create its own JLUS. For now, we just assume that there will be at least one.)

Next we want to tell JLUS all about the great service our Jini'fied Morse code printer offers so that others can take advantage of our printer's availability. This process is referred to as the Join protocol.

In order to join a Djinn, our service has to do two things. First, it must create and provide a proxy object. A proxy, in general, is an agent through which someone or something interacts with another, a go-between. Here, the proxy object is exactly its namesake. It provides the mechanism through which an interested client will communicate with our printer.

The proxy can be any Java object! It could be a full-blown Java GUI application using TCP/IP sockets to "talk" to its server, or it could be an object implementing a simple Java RMI interface. The actual protocol used between the service and the client depends upon the particular implementation of Jini. The interface is defined by whatever the proxy object is. In our example, our printer will use Java RMI to communicate with any interested clients, so the proxy object will be something that implements PrintServiceInterface.

The second thing we should do as part of the Join process is define the set of attributes that our service possesses. These could be anything from defining the name of the printer, or the location of the printer, to expressing all the classes that our proxy implements. Why do this? Well, by providing more information about our service, prospective clients have more information from which to say why our service may or may not be the best for them.

Both pieces of information are packaged up and sent to the JLUS by providing them as arguments in one of the ServiceRegistrar's methods. The JLUS receives these items and stores them for later. This is shown in Figure 10-3.

Figure 10-3. Jini Join.

In Jini Join, as shown in Figure 10-3, our service first constructs a service item describing itself as JLUS and then gives that service item to the JLUS, thus officially joining the local DJinn.

This is all well and good, but what happens if our Jini'fied Morse code printer gets "accidentally" kicked across the room by a frustrated red–green color-blind user? Well, in its battered, disconnected state it certainly isn't available to print messages anymore. How does the JLUS know that our printer isn't available?

One possible methodology would be for the JLUS to continuously poll the service to see if it's still alive. The greater the frequency of polling, the smaller the period of uncertainty about the status of a service and the quicker the response of the Djinn as a whole in dealing with the loss of a service. This approach, however, puts a great deal of burden on the JLUS and also creates quite a lot of network traffic.

As Figure 10-4 shows, the Jini Service continually tracks time elapsed on its lease and renews each lease cycle before the expiration of the lease.

Figure 10-4. Jini Lease Renewal.

Jini actually deals with this by assigning a "lease time" to a service. In an abstract sense, a Jini lease is an agreement between the JLUS and the Jini Service that guarantees that the Jini Service will be up and available throughout the duration of the lease. Jini puts the burden of renewing the lease squarely on the Jini Service, not on the central JLUS. When the lease time period expires, the JLUS will simply remove the information it has about the subject service from availability to the Djinn. It will not, of its own accord, inform the subject Jini Service that the lease has expired. It is up to the Jini Service to enquire about the lease time granted to it by the JLUS. It is also the responsibility of the Jini Service to track the amount of time transpired and to renew its lease when appropriate.. This is sort of a feed forward system. The Jini Server pushes the lease renewal effort. This is illustrated in Figure 10-4.

Now that our printer is plugged in and participating in the Djinn, let's look at Jini from a service consumer's perspective. Remember that right now, in our example, a service item describing our Jini'fied Morse code printer exists on the JLUS. Also remember that the service item contains a proxy object for our Jini-enabled printer.

For the purposes of demonstrating Jini, we have a client whose only job is to find the Jini'fied Morse code printer and send messages to it. The client doesn't have to be a stand-alone Java program, however. It could just as easily be part of an operating system. Such integration would provide our plug-and-work Jini printing capabilities to every application running on that operating system. For the purposes of our example, we will just consider the stand-alone application case.

When the client is run, it has to find the JLUS, just like the service did. It goes through exactly the same Discovery process the service did, eventually obtaining a ServiceRegistrar object for each JLUS that responds. Again, in our example, only one JLUS exists and responds.

Next, the client has the task of using the JLUS to find the desired service. To do this, the client describes the desired service in any one of several ways. The general method is shown in Figure 10-5. The client provides a template against which the JLUS can stack up potential services and find the one that's a match. This template describes desired server characteristics including attributes that services may have defined, such as their name or location, and interfaces that services must match. Our client could try to look up the service by the "well-understood" PrintServiceInterface it should implement. In our example, however, the client actually looks for a match by name. It fills out the appropriate attribute in the template, and gives it to the JLUS by invoking a method on the ServiceRegistrar object. Again, the service registrar is the interface to the JLUS for the client as well as the service.

Figure 10-5. The Jini Client constructs a template identifying the desired service, and the JLUS matches this template against all registered service items and returns the proxy object from the matching service item.

The JLUS then uses the template to find potential matches, which it does in our example. It then takes the proxy object from the matching service item and returns that as the search result to the client. Had the search been unsuccessful, it would have returned a null instead.

The client receives the proxy and then uses it to communicate directly with the service, leaving the JLUS entirely out of the picture at this point. All future communication between the client and service can now happen directly. In our example, the proxy object given to the client simply uses Java RMI to remotely invoke the print method on our service. We could have chosen as our proxy to have a little program that would simply have streamed data to our print service through a TCP/IP socket.

The user makes the client send the message "SOS" and watches as the dots and dashes get flashed out on the Jini'fied Morse code printer.

It is interesting to note, however, that the JLUS itself follows a similar protocol. Both the client and the service received a ServiceRegistrar object through which they communicated with the JLUS. The ServiceRegistrar object is the JLUS's proxy!

One of the first stipulations we made about our Jini'fied Morse code printer was that it implemented an agreed-upon well-known interface. In practice, this is currently the most difficult part of Jini's promise. There have been ads showing Jini-enabling digital watches to communicate with toasters and other currently brainless home appliances. The problem here (besides understanding why you would want to do such a thing in the first place) is that this means all the people who make digital watches and all the people who make toasters have all agreed on what their equipment's interface will be. At the time of this writing, there are efforts underway to define such well-known interfaces for printers and what not, but they have not come to a conclusion, so for our purposes, we will assert that such a well-known interface already exists and looks like this:

import java.rmi.*;
import java.io.*;

public interface PrintServiceInterface extends Remote  {
    public boolean print(String printString) throws RemoteException;
}

This code is standard Java RMI. It defines an interface called PrintServiceInterface that defines the relationship between the client and the service. The client can invoke the method print on any object implementing this interface and pass to that object a string. The object is allowed to pass back to it a boolean or throw a remote exception, that is, the whole interface. The idea, of course, behind this interface is that the object implementing this interface will be the proxy from our printer and that it will take the string passed to it and flash it out in Morse code. If it is unable to do so, for some reason, our printer should inform the client that there was an error by passing a false back as the return value from the method. Hopefully, however, it will be successful and pass a true value as the return value from the method call.

Let's look at the Service code:

/*----------------------Imports-------------------------------------*/
import java.io.*;
import java.rmi.*;
import java.rmi.server.*;
import com.sun.jini.lookup.*;
import net.jini.core.entry.*;
import net.jini.core.lookup.*;
import net.jini.core.discovery.*;
import net.jini.lookup.entry.*;
import com.sun.jini.lease.*;
/*------------------------------------------------------------------*/

public class PrintService extends UnicastRemoteObject
   implements PrintServiceInterface, ServiceIDListener, Serializable
{
   LightDriver      ld;
   MorseTranslator  mp;
             // Print Service Constructor
             public PrintService() throws RemoteException
             {
                super();
                try
                {
                   ld = new LightDriver();       // create light driver
                   mp = new MorseTranslator(ld); // connect translator to driver
                }
                catch (Exception pse) { pse.printStackTrace();
                   System.exit(0);
                }
             }

             // This method is what satisfies the PrintServiceInterface ,
             // requirement it is through RMI that the client remotely calls
             // this method to deliver a string to the server.
             public boolean print(String printString) throws RemoteException
             {
                try
                {
                   System.out.print("PRINT SERVICE, Printing: " +
                                printString + " Length= " + printString.length());
                   mp.doTranslation(printString);  // morse print message
                   return true;                    // return success
                }
                catch (Exception pe) {pe.printStackTrace();
                         return false;             // return failure
                }
             }

             // This satisfies the ServiceIDListner interface
             public void serviceIDNotify (ServiceID id)
             {
             }

             public static void main(String[] args)
             {
                // this will define our service to the JLUS
                Entry[] serviceAttributes;
                // this object handles discovery & join
                JoinManager joinManager;
                // this becomes our server proxy
                PrintService printService;
                // holds the ID given to us by an JLUS
                ServiceID myID;
                try
                {
                   // This creates a security manager, allowing our service to go
                   // to tp remote sources for code.  This is the same as in Java
                   // RMI. We need this to download the JLUS ServiceRegistrar
                   // Object.
                   System.setSecurityManager(new RMISecurityManager());

                   //Setup to perform the Jini Discovery and Join Process
                   printService = new PrintService();
                   serviceAttributes = new Entry[1];
                   serviceAttributes[0] = new Name("Jinified Morse Code Printer");

                   //Create the JoinManager object, which automatically Discovers
                   // and Joins Jini Look Up Services.
                   joinManager = new JoinManager(
                   printService,             // proxy object
                   serviceAttributes,
                   printService,             // ServiceIDListner
                   new LeaseRenewalManager() // auto-renews leases
                   );
        }
        catch (Exception me)
        {
           System.out.println("PrintService main(): Exception ");
           me.printStackTrace();
        }
    }        // EndMainMethod
}         // End PrintService Class

Our Jini Client is a simple stand-alone Java application that finds our Jini'fied Morse code printer service and prints out "Hello World." Somewhere in this code, we will have to create a template to identify the service we're looking for, perform Discovery to find a JLUS, do a lookup on that JLUS to actually find our service, and finally use that service through its proxy.

/*------------------------ PrintClientImports -------------------*/
import java.io.*;
import java.net.*;
import java.rmi.*;
import com.sun.jini.lookup.*;
import net.jini.core.entry.*;
import net.jini.core.lookup.*;
import net.jini.core.discovery.*;
import net.jini.lookup.entry.*;
import net.jini.discovery.*;
/*-------------------------------------------------------------*/

public class PrintClient implements DiscoveryListener
{
   public ServiceRegistrar[] registrars; // holds list of JLUSs'
                                         // registrars
   public boolean JLUSfound = false;     // will trigger lookup
                                         // process

   // This method is required to implement DiscoveryListener.
   // This is how our client will be notified when a
   //   ServiceRegistrar object is received from a JLUS
   public void discovered(DiscoveryEvent ev)
   {
      // Obtain the array of registrar objects from all available
      // LUSs'
      registrars   = ev.getRegistrars();
      JLUSfound = true;
   }
   // Used to deal with the situation when a JLUS is discarded by
   // our discovery object.  We don't use it here, but more
   // robust code would.
   public void discarded(DiscoveryEvent ev)
   {
      //just satisfying DiscoveryListener interface
   }

   public static void main(String[] args)
   {
       LookupDiscovery discovery;   // discovers available LUS
       ServiceRegistrar ourreg;     // holds the test registrar
       LookupLocator lookup;        // used to lookup service
       Entry[] desiredattribs;      // attributes desired in service
       // a template the service must fill
       ServiceTemplate desiredtemplate;

       Object serviceobject;           //result of the search
       PrintServiceInterface printer;  //handle to hold found service
       PrintClient    printclient;     //This holds the instantiation
                                       //of our client

       try
       {
           // Set the security manager for handling downloaded code:
           // needed to obtain the ServiceRegistrars and the servers
           // proxy object
           System.setSecurityManager( newRMISecurityManager() );

           // Perform Discovery Process for all JLUS containing the
           // public group
           discovery = newLookupDiscovery(new String[] {""});

           // add a DiscoveryListener to recieve the ServiceRegistrar
           // objects our LookupDiscovery finds.
           printclient = new PrintClient();
           discovery.addDiscoveryListener(printclient);

           // create a description for the service we are looking for
           // must have the name PrintService…
           desiredattribs = new Entry[1];
           desiredattribs[0] = new Name("Jini'fied Morse Code
                               Printer");
           Class[] clArray = new Class {PrintServiceInterface};
           desiredtemplate = new ServiceTemplate(null, clArray,
                             desiredattribs);
           while (true)
           {                                        // begin while
              if (printclient.JLUSfound)
              {                                     // begin if found
                 printclient.JLUSfound = false;     // reset flag
                 System.out.println("PrintClient: " +
                                    printclient.registrars.length +
                                    "Jini Lookup Service(s) Found.");

                 // Go through the complete array of registrar objects
                 // lookup on each one to find the PrintService
                 // if found print out "Hello World!"
                 for (int i=0; i<printclient.registrars.length; i++)
                 {  //begin for
                    lookup = printclient.registrars[i].getLocator();
                    System.out.println(
                    "PrintClient: LUS found at " +
                    lookup.getHost() + " on port " +
                    lookup.getPort());

                    //perform the actual Jini lookup
                    serviceobject = printclient.registrars[i].lookup
                                    (desiredtemplate);

                    if (serviceobject instanceof PrintServiceInterface)
                    {
                      System.out.println("Found a match!
" +
                      "Calling print method: Hello World!
");
                      printer = (PrintServiceInterface) serviceobject;
                      if (!printer.print("Hello World!
"))
                      {
                        System.out.println("PrintClient: Print Failed!");
                      }
                      else System.out.println("PrintClient: Print
                        Successful!");
                    }
                    else System.out.println("No match Found. :-<");
               }    //end for
            }  //end if
         }  //end while
      }
      catch (Exception me)
      {
          me.printStackTrace();
      }
   }  // end main
}  // end client

Because standard RMI stubs and skeletons are being utilized, this service requires a Web server running to distribute the stub file to anyone who needs it. Don't forget to set the RMI codebase parameter to point to the URL where the stubs are served from. If this is confusing, it may be helpful to go back and refresh your knowledge of Java RMI. In effect, the PrintService_Stub.class file is the PrintServices proxy object.

As an additional note, we will need a security policy file that allows the service enough privilege to be able to download and run code given to it by the JLUS.

Required Files in Service Directory for running:

Required Files to be served by the service's webserver:

To run the server, you must have at least one JLUS running already on your local network, such as Reggie the JLUS that comes with the Jini SDK.

The following commands will start up the Web server to serve the Stub file and run the service.

In a UNIX environment:

echo Starting Server Codebase Webserver
java -jar /path_to_Jini/jini1_0/lib/tools.jar -dir
/path_to_service_codebase_directory/service-codebase -verbose
-port 8001 &

echo Starting Service
java -Djava.security.policy=policy.all
-Djava.rmi.server.codebase=http://192.168.1.4:8001/ PrintService

You would replace the text in italics with the appropriate path for your system.

In a Windows environment:

echo Starting Server Codebase Webserver
java-jar Drive:path_to_Jinijini1_0lib	ools. jar -dir
path_to_server_codebase_directoryservice-codebase -verbose
-port 8001 &

echo Starting Service
java -Djava.security.policy=policy.all
-Djava.rmi.server.codebase=http://192.168.1.4:8001/ PrintService

You would replace the text in italics with the appropriate path for your system.

Assuming the appropriate classpath setup, the server should then run. As it is written, the server will execute and remain silent. It would be an easy task to include some code to inform the user that it is up and running. Because the serviceIDNotify method gets called when the JLUS first assigns an ID to the service, a statement could be placed here indicating to the user that a successful join had occurred.

Running the client is a little simpler. Again, we assume that there is a JLUS already running on our local network. Here also, a policy file that allows the client enough privilege to download and execute code from both the service and the JLUS is needed.

Required Files in Service Directory for running:

The following commands will run the client.

In a UNIX or Windows environment:

echo Starting the Client
java -Djava.security.policy=policy.all PrintClient

Again, this assumes that your classpaths are set up properly for your Java and Jini installations.

As mentioned earlier, this chapter is really only an introduction to Jini. I highly recommend purchasing Core Jini by W. Keith Edwards, as both an excellent introduction and a comprehensive text on this technology. In addition, several kind individuals have made tutorials and examples of their Jini efforts available online. Much of this is equally helpful in getting your own Jini projects up and running. Because the Web is ever changing, I don't include the URLs, but I do encourage people to use their favorite search engine to find and visit these resources:

Concerning the actual Jini'fied Morse code printer, an actual Morse code printer was built at Binghamton University in 1999. The prototype system utilized a simple plastic box containing two LEDs wired to a parallel cable. This parallel cable was connected to a Red Hat Linux box running on an old 486 class PC. The PC acted as the "embedded smarts" of the Jini device, implementing the full Java 2.0 SDK and Jini 1.0 SDK. Though the prototype system was quite large, and thus not "embedded" by any standard, its use as a model was still valid. The operating system, Java and Jini Runtimes, Ethernet, and parallel ports all could have easily been implemented on one of several credit-card-sized PC systems commonly available from embedded systems manufacturers.

It is worth mentioning that Linux was the operating system of choice for this application for a couple of reasons. Linux is a freely available, full-fledged UNIX clone. Linux has been used in a variety of embedded applications. Also, because of the security restraints and cross platform features of Java, it wasn't possible to access the printer hardware directly as an address in memory, as you might in C or C++. However, in Linux, as in other UNIX systems, hardware is accessible as simple files in the /dev file structure. In this way, Java code could easily be written to twiddle the output bits on the parallel port (/dev/lp1) in exactly the same manner as writing to a file! This made the entire task of writing a "device driver" in Java trivial.