org.ozoneDB

Package Specification

Several implementations of OzoneInterface

{@link Database} is the implementation of {@link OzoneInterface} that database objects obtain from their {@link org.ozoneDB.OzoneCompatible#database} method. The programmer should never need to create instances of this class.

All other implementations of {@link OzoneInterface} are derived from {@link org.ozoneDB.ExternalDatabase}. They can be used by the programmer to access a database from the client. The different classes provide different access modes to a database server but implement exactly the same interface. So in most cases the same code (except for the initialization of the database object) runs with different types of database.

{@link org.ozoneDB.RemoteDatabase} is used to access a remote database server over a socket connection. The server may reside on the same or a remote host.

{@link org.ozoneDB.LocalDatabase} is used to access a database server that resides in the same JVM as the client. Of course this does not allow multiple clients to access the server but it is faster and smaller.

{@link org.ozoneDB.ClientCacheDatabase} Maybe a cool thing that is not yet ready to be used and not yet documented.

Proxy objects

Proxy classes are generated out of the database classes. Database objects are persistent objects that run inside the server. All database classes implements the {@link org.ozoneDB.OzoneCompatible} interface. Database classes are by convention named *Impl. An external interface which extends {@link org.ozoneDB.OzoneRemote} describes the public interface of each database object. The Ozone Post Processor (OPP) tool generates the proxies out of the database classes. Proxy classes are named *Impl_Proxy.

Both database objects and proxies implement the public interface of the database object. All ozone API methods return proxies for the actual database object inside the database. So the client only deals with proxies. However the proxies provide the same interface and can be used as if they were the actual database objects.

Server side logic

Of course, this is a time consuming operation. But in most cases this has to be done only once per 'business method' or 'business transaction'. An example: There are two business objects: UserManager and User which we want to make persistent. The UserManager holds the Users in a hashmap with the usernames as keys. Both classes, UserManager and User, have to be database objects. UserManager provides a method addUser(Name, Age, whatever) which creates a new user, fills the new object with the specified data and put it in the hashmap. Filling the User object with the data may result in many method calls. Since the User is a database object the UserManager only deals with proxies of the User database objects. So the method calls are handled via proxy objects. However, the UserManager itself is a database object and invoking a proxy from another database object (from inside the server) is much (around 1000 times) faster than invoking a database object from outside the server. Therefore it is very important to keep the ozone architecture in mind when designing and implementing an ozone application!

Transactions

This means, if possible, do not use explicit transaction demarcation. This will force you to put the code that should run inside one transaction, inside one database object method, which leads to good performance!

In contrast to LocalDatabase and RemoteDatabase which produce the exactly same results for the same code, this implementation of ExternalDatabase is not guaranteed to do so.

Note: The method parameters of type OzoneRemote are supposed to by proxy objects (of type OzoneProxy ).

Note: The method parameters of type OzoneRemote are supposed to by proxy objects (of type OzoneProxy ).

Each thread is associated with a server connection.

When programming ozone applications explicite transaction demarcation is needed under rare circumstances only (for example: processing of binary large objects - BLOBs).