This chapter discusses the following topics:
What Is ObjectStore?
Description of ObjectStore Process Architecture
Definitions of ObjectStore Terms
Prerequisites for Using the ObjectStore Java Interface
What Is ObjectStore?
ObjectStore is an object-oriented database management system. It allows you to
ObjectStore can work well for distributed databases of virtually unlimited sizes and unlimited numbers of objects. ObjectStore supports the following:
ObjectStore includes the COM.odi.odmg package, which provides an Object Data Management Group (ODMG) binding. This binding includes classes for Database and Transaction that closely follow the ODMG specification. The package also includes the COM.odi.odmg.Collection interface, persistence-capable classes that implement the Collection interface, and ODMG exception classes.
With ObjectStore's archive logging facility, you can protect against media failure.
ObjectStore allows you to quickly read or modify portions of your persistent data. You are not required to read in all persistent data when you just want to look at a subset. This reduces start-up and transaction commit times and allows you to run much larger Java applications without increasing the amount of memory or swap space on the system.
Description of ObjectStore Process Architecture
There are three kinds of processes in the ObjectStore environment:
In the Java interface to ObjectStore, the client is a single process that has several software components. These components call each other as needed:
Your application must create a session before it can use any of the ObjectStore API. After a session is created, it is an active session. A session remains active until your application or ObjectStore terminates it. After a session is terminated, it is never used again. You can, however, create a new session.
Persistence-Capable
The term persistence-capable refers to the capacity of an object to be stored in a database. If you can store an object in a database, the object is persistence-capable. If you can store the instances of a class in a database, the class is a persistence-capable class and the instances are persistence-capable objects.
Some Java-supplied classes are persistence-capable. Other classes are not and cannot be made persistence-capable. A third category of classes can be made persistence-capable, but there are important issues to consider when you do so. Be sure to read Java-Supplied Persistence-Capable Classes.
Persistent Object
A persistent object is a representation of an object that is stored in a database.
When your application acquires a reference to an object that has not yet been read in from the database, ObjectStore generates a hollow object as a placeholder for that object. ObjectStore does not actually read in the contents of the object until your application tries to read, write, or invoke a method on the object.
When your application accesses a hollow object, ObjectStore turns it into an active persistent object. ObjectStore retrieves the contents of the object from the database and stores them in the fields of the hollow object, which makes it an active persistent object. This process is referred to as initialization.
Obtaining an object from a database root always results in a hollow object. If you get the same root three times, the object it identifies is still hollow. You must access the object to make it active.
After an application accesses the contents of a persistent object, the objects that the persistent object references are hollow objects, unless their contents were previously accessed. For example, suppose you have the following class:
class A {
B b;
}
When you obtain a reference to an instance of A, ObjectStore creates a hollow A object to represent that instance. When you read or update the instance of A, ObjectStore turns it into an active object and creates a hollow B object to represent the referred to instance of B. If you then read or update the instance of B, ObjectStore makes that hollow object into an active object and creates hollow objects for any objects referred to by B.
An application can read or update an active persistent object; a persistent object must be active for an application to read or update it. The postprocessor takes care of this for classes that it annotates.
When ObjectStore changes a hollow object to an active object, it initializes the object. In most applications, this happens automatically, because the postprocessor inserts the required calls.
When a persistent object is active, ObjectStore internally flags it as either clean or dirty. An active object is initially marked as clean when its contents are read into memory. At this point, ObjectStore recognizes that the contents of the persistent object match the contents of the object in the database. An active object is dirty when it is a modified version of the stored object that the active object represents. When you modify an object, ObjectStore automatically changes the flag from clean to dirty. The class file postprocessor inserts the code that does this.
For example, suppose you have an instance of a Person object where the age field has the value 30. When you read this object, it is in the clean state. If you modify the value of age, even if the new value you assign is 30, the object is then in the dirty state.
If an application tries to read or update a stale object, ObjectStore throws ObjectException. An application must not invoke any instance method on a stale object.
When a method accesses fields in a persistent object, ObjectStore checks to ensure that the data has been read from the database. This checking is done by calls that the postprocessor inserts in your code. These are the annotations mentioned in the previous paragraph. The annotations are calls to the ObjectStore.fetch() or ObjectStore.dirty() method.
Every persistence-capable and persistence-aware class must have these annotations. Persistence-capable classes also include many other annotations.
Primary Object
A primary object is a persistence-capable Java object. A persistence-capable object is an object that can be stored in an ObjectStore database. You can use primary objects just as if they were ordinary Java objects. The database correctly records their identities, classes, and field values. Primary objects do not extend the CPlusPlus class. Peer Object
Peer objects provide a way for Java applications to use C++ objects. A peer object acts as a proxy for a particular C++ object. It has no data fields and so it does not hold any state that is represented by the data members of the corresponding C++ object. Transient Object
A transient object is an object that is not already in a database. Transitive Persistence
When an application commits a transaction, ObjectStore stores in the database any transient objects that can be reached transitively from any persistent object. This is the process of transitive persistence. Transient objects that are referenced by persistent objects become persistent when the transaction commits. For this to work, the transient objects must be persistence-capable. Annotations
The class file postprocessor annotates classes you define so that they are persistence-capable. This means that the postprocessor makes a copy of your class files, overwrites your original class files or places them in a directory you specify, and adds byte code instructions (annotations) that are required for persistence. Complete information about annotations is in Chapter 8, Automatically Generating Persistence-Capable Classes.
Occasionally, you might want to manually annotate your code. Information you need to do this is in Chapter 9, Manually Generating Persistence-Capable Classes.
Database Roots
A database root provides a way to associate a name with an object in a database. Applications use database roots to locate one or more persistent objects for performing queries or navigating to other persistent objects. When you make an object the value of a persistent database root, doing so establishes the object as persistent and makes the objects it refers to available for transitive persistence.
At any given time, a database root is either associated with one database or it is null. You can change the database with which a root is associated. Information about database roots is in Working with Database Roots.
Prerequisites for Using the ObjectStore Java Interface
To use the ObjectStore Java interface you must
Updated: 10/07/98 08:44:34