ozone API

Package org.ozoneDB

Provides the classes and interfaces of the native ozone API.

See:
          Description

Interface Summary
OzoneCompatible All objects that are stored in ozone have to implement this interface.
OzoneCompatibleOrProxy This interface marks classes which represent objects which represent #OzoneObjects, either locally or remote.
OzoneInterface Together with ExternalTransaction and OzoneCompatible this interface represents the basic API of the ozone database system.
OzoneRemote This interface is implemented by database classes (OzoneCompatible) and proxies (OzoneProxy).
 

Class Summary
AbstractTransaction Abstract base class of all external transaction classes.
CacheObjectContainer An implementation of ObjectContainer that works together with ClientCacheDatabase to provide an client site cache.
ClientCacheDatabase This is an ExternalDatabase that implements a client side cache on top of another ExternalDatabase.
Database This class represents the database for OzoneObjects within the server.
ExternalDatabase Base class for implementations of the OzoneInterface which are used from a client application to access an ozone.
ExternalTransaction ExternalTransaction allows an application to explicitly manage transaction boundaries.
LocalDatabase This class represents a local database server that runs inside the same JVM as the client.
OzoneObject This class can be extended to build actual database objects.
OzoneProxy Proxy of an OzoneRemote object.
RemoteDatabase This class represents a remote database server that is connected via a network connection.
Setup Setup holds all static configuration properties plus all dynamic runtime properties of an ozone environment.
 

Exception Summary
ClassNotFoundExc This exception is thrown, if ozone is unable to load a specified class.
DbNotOpenExc  
DeadlockExc This exception is thrown in the client, if the current transaction was aborted because of a deadlock in the server.
ExceptionInOzoneObjectException represents an exception which was thrown within a method of an OzoneObject.
ObjectNotFoundExc This exception is thrown, if a database object, which is referenced by a proxy, cannot be found in the database.
OzoneInternalExc This exception signals an internal server exception.
OzoneRemoteExc Base class of all exceptions that may be thrown by ozone API methods.
PermissionDeniedExc This exception is thrown, if the owner of a transaction does not have proper permissions for a requested operation.
TransactionExc This exception is thrown, if...
UnexpectedException This Exception is thrown, if a method of a database object has thrown an exception that is not in its throws clause or to signal an general unexpected error condition.
 

Error Summary
MethodNotFoundExc This error is thrown, if the RMI system is unable to find or unable to invoke a given method.
 

Package org.ozoneDB Description

Provides the classes and interfaces of the native ozone API. The most important interfaces and classes are OzoneInterface, which is the basic ozone API; and OzoneCompatible / OzoneObject, which are the base interface and a base class of all database objects.

Package Specification

Several implementations of OzoneInterface

Several classes implement the OzoneInterface interface. There are two situations where the programmer has to use this interface. Firstly, in the client to directly access database function such as OzoneInterface.createObject(java.lang.String). Secondly, inside the code of database classes (classes that are derived from OzoneCompatible).

Database is the implementation of OzoneInterface that database objects obtain from their OzoneCompatible.database() method. The programmer should never need to create instances of this class.

All other implementations of OzoneInterface are derived from 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.

RemoteDatabase is used to access a remote database server over a socket connection. The server may reside on the same or a remote host.

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.

ClientCacheDatabase Maybe a cool thing that is not yet ready to be used and not yet documented.

Proxy objects

A Proxy object represents an actual database object inside client applications and inside other database objects. A proxy object can be seen as a persistent reference.

Proxy classes are generated out of the database classes. Database objects are persistent objects that run inside the server. All database classes implements the OzoneCompatible interface. Database classes are by convention named *Impl. An external interface which extends 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

ozone follows the OO paradigm that data and the corresponding operations together are objects. ozone does not only store the data of the objects but also provides an runtime environment to actually execute the methods of the database object. After invoking a method on a proxy object the parameters are marshalled and sent to the server where the corresponding method of the actual database object is invoked.

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

By default, each client side invocation of a proxy method creates a new transaction. This transaction is implicitely aborted if the method throws an exception and commited otherwise. In the above UserManager example this is exactly what we need. Creating the new User object, filling it with data and storing it in the hashmap should run in one transaction. So the example runs as fast as possible and is transactionally correct. Or better: it runs fast because it is transactionally correct!

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!


ozone API

Copyright (C) The Ozone Database Project - www.ozone-db.org. All rights reserved.