[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[ANNOUNCE] ozone documentation online

Hi all,

I'm just about to upload the new ozone-db.org site. It contains now a
Documentation button and some documentation behind ;) It's not complete but
should help to get started with ozone. It covers more the user documentation.
I need to make another picture to describe also the internal architecture.
Hints, comments and any help is always welcome.

Johann, do you think my first try to make some ozone documentation is of any
use?

Also, I've attached a new package.html file for the org.ozoneDB package. Just
copy it into the org/ozoneDB directory and build the docs (ant javadoc-api) to
see the changes in your ozone API specification.


Falko
-- 
______________________________________________________________________
Falko Braeutigam                         mailto:falko@softwarebuero.de
softwarebuero m&b (SMB)                    http://www.softwarebuero.de
Provides classes and interfaces of the native ozone API. The most important interfaces/classes are {@link org.ozoneDB.OzoneInterface}, which is the basic ozone API; and {@link org.ozoneDB.OzoneCompatible} / {@link org.ozoneDB.OzoneObject}, which are the base interface and a base class of all database objects.

Package Specification

Several implementations of OzoneInterface

Several classes implement the {@link OzoneInterface} interface. Basically there are two situations when the programmer has to deal with them. First, in the client to directly access database function such as {@link org.ozoneDB.OzoneInterface#createObject}. Second, inside the code of database classes (classes that are derived from {@link org.ozoneDB.OzoneCompatible}).

{@link Database} is the implementation of {@link OzoneInterface} that database object get out of their {@link org.ozoneDB.OzoneCompatible#database} method. The programmer never needs 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 the 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 database types.

{@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 to access the server from multiple clients but 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 object represent the actual database object - inside the client applications and inside other database object. 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 {@link org.ozoneDB.OzoneCompatible} interface. Database classes are often 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 deals with proxies only. However, the proxies provide the same interface and can be used as 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 methods of the database object. After invoking a method of a proxy the parameters are marshalled and sent to the server where the corresponding method of the actual database objects 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. Of course we have to make them persistent. The UserManager holds the Users in a hasmap with the usernames as keys. So both, UserManager and the Users, 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 hasmap. 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 handles via proxy objects. However, the UserManger 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 invokation 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 in the hashmap should run in one transaction. So the example runs as fast as possible and is transactional correct. Or better: it runs fast because it is transactional correct!

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