This document discusses an object persistence framework built using Java's JDBC and Remote Method Invocation (RMI). The framework was developed to fulfill the requirements for the final two projects for CS397C24. This document contains a scenario demonstrating the framework's use, links to the object model and javadoc documentation, and instructions for downloading and running the code.

The framework provides object persistence services to client programs that need to store and retrieve object instances. The objectives of the framework are to:

• Provide useful object management services
• Insulate the client program from the persistence implementation
• Minimize the effort required of a developer to utilize the framework for managing a new type of domain object

The framework also allows object persistence to be implemented using other mechanisms than JDBC, such as object databases and serialization-based persistence. The framework makes this implementation decision transparent to client programs that don't know or care how persistence is implemented.

A client program that wishes to store or retrieve domain objects of the type Classifier obtains a reference to a BrokerLocator from the RMI naming service, where a server program has registered it. The client program uses the BrokerLocator to retrieve a Broker for the domain class classifier. The BrokerLocator returns a reference to a remote ClassifierBrokerImpl that implements the Broker interface. The client program uses the remote broker to store and retrieve instances, passing Classifier objects to the server by value. The ClassifierBrokerImpl contains information for mapping Classifier instances to relational tables.

Follow these links to:

• The framework's object model
• Javadoc API documentation
• Java source code

There are two pieces of the framework. Some framework objects run on the server, others run on the client. The two components are contained within the file "persistence.zip". It contains three files within it, "exjava.zip", "persistence_client.zip" and "persistence_server.zip". Unzip the file "persistence.zip" in the directory of your choice.

It is important that you use the same classpath to start the RMI Registry and run either the client or server programs. I received errors if I started the RMI Registry without including the server zip file in the classpath for it. Here are the classpaths to use for the specified situations. These classpaths assume that you will issue the "java" commands from the directory into which you unzipped persistence.zip. It is assumed that your current classpath includes the java classes (e.g. $JAVA_HOME/lib/classes.zip).

The following instructions for running the server and client programs assume that the RMI registry is running on both the client and server machines. To start the RMI registry running, issue the command "start java -classpath XXX sun.rmi.registry.RegistryImpl" on a Windows machine, or "java -classpath XXX sun.rmi.registry.RegistryImpl &" on a Unix machine, where XXX is the classpath determined above. If you receive an error, verify that sun.rmi.registry is in your classpath.

For example, to run the RMI registry on a UNIX client, issue:

After starting the RMI registry, place the files "persistence_server.zip" and "exjava.zip" in the desired directory on the server machine. Run the server program by issuing the command "java -classpath XXX persistence.BrokerLocatorServer" on or Unix from the directory where you placed the files "persistence_server.zip" and "exjava.zip", where XXX is the classpath determined above. Run the program in the foreground to see the program's output on the console. To kill the server program after testing the client, type control-c in the server program's window.

For example, to run the server on a UNIX machine, issue:

After starting the RMI registry, place the file "persistence_client.zip" in the desired directory on the client machine. Run the client program by issuing the command "java -classpath XXX classifier.PersistenceClient server.name" on Windows or Unix, where XXX is the classpath determined above. Replace "server.name" in the command with the name of the host running the persistence server started in the previous step. If you are running the client and server on the same machine, you don't need to provide the hostname argument.

For example, to run the client on a UNIX machine and the server running on "www.yourmachine.com", issue:

You'll see the client program output "connecting to rmi://www.yourmachine.com/" and "defaultBrokerLocator", the name of the broker locator it connects to. You'll then see the server console display "returning broker for CAMClassifier". You'll see the client program output "saving classifier instance named: persistence test". The server program outputs "saving classifier named: test" and then lists the contents of the classifier table before and after inserting the row. The client program exits when this interaction completes - you don't need to kill it.

The server-side broker implementation drops the tables it creates after saving the instance. As such, there should never be more than one row in the classifier table at a given time.

The client functionality is also prototyped in my classifier application. The classifier editor contains a "Save to Database" item on its "Classifier" menu that saves the current classifier to the mysql database on noodle.