Ozone 1.1

Norman Walsh's Saxon Extensions Package for Saxon 6.*

This package implements Saxon extensions for XSLT.

Copyright (C) 2000 Norman Walsh

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Except as contained in this notice, the names of individuals credited with contribution to this software shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the individuals in question.

Anything derived from this Software that is publically distributed will be identified with a different name and the version strings in any derived Software will be changed so that no possibility of confusion between the derived package and this Software will exist.

Warranty

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL NORMAN WALSH OR ANY OTHER CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Norman Walsh's Xalan Extensions Package for Xalan2

This package implements Xalan extensions for XSLT.

Copyright (C) 2000 Norman Walsh

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Except as contained in this notice, the names of individuals credited with contribution to this software shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the individuals in question.

Anything derived from this Software that is publically distributed will be identified with a different name and the version strings in any derived Software will be changed so that no possibility of confusion between the derived package and this Software will exist.

Warranty

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL NORMAN WALSH OR ANY OTHER CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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 other words: It is not possible to use ozone as an out-of-the-box replacement for another ODMG database without code changes. (I'm in doubt if this is possible with any combination of different ODMG implementations) But you will find the ODMG object and programming model in the ozone ODMG interface, which makes it easier to start with ozone if you are familiar with ODMG.

If you really need to keep your client code independent of ozone, we suggest to make a wrapper that hides the actual ODMG implementation classes from the client code. This wrapper should provide an explicit notion for creating objects, like the {@link OzoneODMGDatabase}. The database dependent implementation of the wrapper can decide how to actual create objects and handle other database specific things.

See also the samples included in the ozone distribution to learn how to program against the ozone ODMG API.

ODMG collections

This package provide the JUnit test framework for Ozone. This version is compatible with JUnit 3.6.

Important Classes

OzoneTestCase

OzoneTestCase is the base for all Ozone TestCase. It includes access to the database setup by the TestRunner.

The following is an example for to write a OzoneTestCase.

packge com.foo;

import junit.framework.*;
import org.ozoneDB.test.OzoneTestCase;
import org.ozoneDB.test.simple.*;

package FooTestCase extends OzoneTestCase {

  public static Test suite() {
    TestSuite suite = new TestSuite();
    suite.addTestSuite(FooTestCase.class);
    return suite;
  }

  public void testCreate() {
    // db() provide the access to database setup by TestRunner
    Auto auto = (Auto)db().createObject(AutoImpl.class.getName()); 
    assertNotNull(auto);
    // Test away!!!
  }
}

OzoneTestRunner

Once you have the TestCase written, you will want to run the Test. OzoneTestRunner provides the environment to run Unit Test for Ozone.

Usage: ojvm org.ozoneDB.test.OzoneTestRunner {-local | -remote [-host=HOST] [-port=PORT]} [-debug]

• -local: use local database
• -remote: use remote database
  • -host=HOST: the database server host
  • -port=PORT: the database server port
• -debug: enable the debugging output

Note: The OzoneTestRunner's logging is control by Log4J. You can use the log4j in your TestCase.

Reference:

• Log4J: http://jakarta.apache.org/log4j/docs/index.html
• JUnit: http://www.junit.org

Package Specification