ObJectRelationalBridge
BRIDGING JAVA OBJECTS AND RELATIONAL DATABASES


Getting started with the OJB C/S architecture:

Author: Thomas Mahler, august 2001

Abstract

This document presents an introduction into the Client/Server architecture of OJB. It starts with a general overview of this architecture. Then it shows how to run the demo applications. In a final section I give some hints how to use OJB in real world environments.

Architecture

In it's early days OJB was a simple classlibrary for mapping objects to relational databases. It did not cover the handling conflicts between concurrently operating multiple clients. It was also not scalable if it was used within an application server.
Today OJB comes with a PersistenceBrokerServer that covers those problems.

This new architecture splits OJB into two parts: a client consisting of the ODMG implementation (optional) and a PersistenceBrokerClient. And on the other Side a PersistenceBrokerServer. The PersistenceBrokerClient implements the PersistenceBroker interface as the original PersistenceBrokerImpl. But is does no persistence operations at all. It rather works as a Proxy that delegates all calls to the PersistenceBrokerServer. User Applications using OJB always work against the PersistenceBroker Interface. They use a Factory (PersistenceBrokerFactory) to obtain their PersistenceBroker objects. The usage of factory and interface allow to keep the operating mode (with a local PersistenceBrokerImpl or with a remote PersistenceBrokerServer) complety transparent for the user-applications. The factory is configured by a properties-file. The PersistenceBrokerServer is a TCP/IP based multithreaded Server. The Server maintains a pool of PersistenceBrokerImpl's that do the real database work.

The PersistenceBrokerClient and the PersistenceBrokerServer use a simple protocol for communication. The client sends a ojb.broker.server.Request object to the server. The Request object encapsulates the method call with all parameters and the index of the PersistenceBrokerImpl to be used by the server. The marshalling is done with Java Serialization using an ObjectOutputStream over a socket connection.
The Server delegates all work to threaded RequestProcessors. The RequestProcessor unmarshals the incoming request (reading from an ObjectInputStream). Then it determines the PersistenceBrokerImpl object to be used by the received index. This PersistenceBrokerImpl object then performs the request a specified by the client. The resulting Object (whether a resulting collection, a single object, a null value or an exception) is then sent back to the client. The PersistenceBrokerClient unmarshals the incoming object and returns to the calling application.

The server's gross layout of dispatching incoming requests to worker threads has been adopted from a simple HTTP server implementation. It is a proven design for servers handling a large number of clients.

The architecture described above allows to run many clients against a single server. But the new OJB architecture even allows to run several PersistenceBrokerServers in parallel. This can be helpful if OJB is to be used within a heavy duty application server scenario.
The PersistenceBrokerClients can be configured to use all available OJB servers in a roundrobin sequence. This results in a loadbalancing between the servers.

Temporary remark:
Currently distributed lock handling is not yet supported by the OJB Client/Server architecture. It will be finished in one of the next releases.

Running the examples

  1. To see if OJB is installed properly run build.sh junit (or build junit under windows).

  2. To start the OJB server execute the server.sh (or server.bat under windows). By default the server operates on port 2001. If you must use a different port you can edit the script file (see file server2.sh for an example). The server will start up with a screen like this:
    OJB Descriptor Repository: file:/home/tom/objectbridge/build/test/ojb/repository.xml
    ..........
    OJB PersistenceBrokerServer accepting connections on port 2001
    Serving Mapping Repository: /home/tom/objectbridge/build/test/ojb/repository.xml

  3. OJB is shipped with a configuration that disables the server mode (thus you were able to run the junit test in step 1). Now we have to change this configuration to enable the server mode. Edit the file build/test/ojb/PersistenceBrokerFactoryConfiguration.properties and change the line useServer=false to useServer=true.
    If you are running the server not on port 2001 you also have to change the line BrokerServers=localhost\:2001 accordingly.

  4. Now again run the Junit tests by build.sh junit from new terminal window (or dos box). You will notice that all database messages go to the server terminal and all result messages to the junit terminal. Currently the junit run terminates with two failures. I guess they are due to the fact that instantDB has problems with multiple connections commiting indepentently into the database.

Usage in real world environments

To run OJB in client/server mode with multiple clients and multiple servers you first have to install OJB on all machines (see above). You then have to edit the file PersistenceBrokerFactoryConfiguration.properties on all machines.

Say you have to servers luna and stella with the repository.xml residing in /usr/local/ojb. The properties file on all machines will look like this:

#OJB Configuration
#Tue Jun 26 20:31:43 CEST 2001
BrokerServers=stella\:2001,luna\:2001
useServer=true
repositoryFile=/usr/local/ojb/repository.xml

This configuration will allow a loadbalancing of all client requests between luna and stella.


$FOOTER$