PSE/PSE Pro for Java API User Guide
This chapter introduces PSE/PSE Pro.
ObjectStore support for Java includes three products:
PSE and PSE Pro are persistent storage engines for Java. They provide persistent storage for Java objects. Persistent data is available to programmers in such a way that it appears as familiar, normal Java objects. Persistent Java objects and regular Java objects are manipulated in the same way and behave in the same way.
PSE is designed for applications that require persistent Java support for as much as 100 MB of data accessed by one user. PSE is written entirely in Java, uses approximately 300 KB of disk space, and runs entirely within the application process. It supports transactions and provides access to objects without reading the entire database.
PSE Pro builds on PSE. In addition to providing all features provided by PSE, PSE Pro
Special Notice to ObjectStore PSE for Java Users!
Visit the ObjectStore PSE Pro for Java Web page (http://www.odi.com/products/pse/psepj.htm) for the latest information on how to purchase PSE Pro electronically. Act quickly to obtain special discount prices.
The Java interface to ObjectStore Development Client (referred to as ObjectStore) is for Java and C++ applications that require multi-user high-performance persistent storage for large databases with full database features such as failover, online backup, fine-grained concurrency, and security.
ObjectStore is not constrained by the number of objects being managed. It can work well for distributed databases of virtually unlimited size. The ObjectStore API is a superset of the PSE Pro API. In addition to providing all features provided by PSE Pro, ObjectStore supports
What Does PSE/PSE Pro Do?
PSE and PSE Pro provide an application programming interface (API) that allows a program to
PSE Pro can recover from an application failure or system crash. If an application fails during a transaction, when you restart the application the database is as it was before the transaction started.
A PSE application cannot recover from a transaction that aborts because of an abnormal application termination while PSE is writing to the database (a system failure). Automatic recovery is only supported in PSE Pro and ObjectStore. If your application requires dependable storage, consider using PSE Pro or ObjectStore.
PSE and PSE Pro do not have facilities for protection against media failure.
PSE/PSE Pro provides a convenient and complete API for maintaining persistent data. After you define persistence-capable classes (classes whose instances can be stored in a database), writing an PSE/PSE Pro application is just like writing any other Java application.
PSE/PSE Pro 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.
When you access persistent data inside a transaction, PSE/PSE Pro ensures that your results are not compromised by other users sharing the data. If something goes wrong, or if you determine that you do not want to keep changes, you can abort the transaction. In that case, PSE/PSE Pro restores the database to its state before the transaction started. This makes it straightforward to recover from exceptions or failures.
Here are some terms you must be familiar with to use PSE/PSE Pro:
Session
A session is the software component that allows the use of the PSE/PSE Pro API. For a thread to use the PSE/PSE Pro API, it must issue a call that associates it with a session. Any number of threads can be serviced by a session.
An active session is a session that has been initialized by a call to ObjectStore.initialize(host, properties) and not yet shut down. A Java virtual machine that is running a PSE Pro application can have multiple active sessions at the same time. A Java virtual machine that is running a PSE application can have one active session at a time.
A session defines an isolated namespace. The namespace defines unique names (and consequently identities) for databases, segments, transactions, and persistent objects. A session can oversee
Persistence-Capable
Persistence-capable is the capacity 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.
The definition of a persistence-capable class includes specific annotations required by PSE/PSE Pro. After you compile class definitions, you run the PSE/PSE Pro class file postprocessor on the compiled classes to add the annotations that make the classes persistence-capable. In unusual circumstances, you might choose to explicitly add the annotations.
A persistent object is a representation of an object that is stored in a database.
After an application retrieves an object from the database, the application works with the persistent object in the Java environment. A persistent object always exists in one of three states:
Methods you call can change the state of a persistent object.
A hollow persistent object contains fields that are identical to the fields of the object in the database that the persistent object represents, but the fields have default values.
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 access the object.
When your application reads or updates a hollow object, PSE/PSE Pro turns it into an active persistent object. PSE/PSE Pro retrieves the contents of the object from the database and stores them in the hollow object, which makes it an active persistent object.
A persistent object is hollow the first time it is referenced in a transaction. For example, a persistent object is hollow the first time an application uses a database root to obtain it. Also, after an application accesses the contents of a persistent object, the objects that the persistent object references are hollow objects, unless of course their contents were previously accessed.
An active persistent object starts as an exact copy of the object that it represents in the database. The contents of an active object are available to be read by the application and might be available to be modified. If an active object is updated by the application, it is no longer identical to the object in the database that it represents.
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.
PSE/PSE Pro initializes a hollow object so that it becomes an active object. In most applications, this happens automatically because the postprocessor inserts the required calls.
In the rare circumstances that you are manually annotating for persistence, you must insert calls to the Persistent.fetch() or Persistent.dirty() method to perform the initialization. If an application calls the Persistent.dirty() method (as opposed to the Persistent.fetch() method) on a hollow object, the resulting active object can be modified.
A stale persistent object is no longer valid. Its fields have default values and should not be used. An object becomes stale when an application calls
- Transaction.commit() on the transaction in which the object could be read or modified and the call does not specify a retain argument or it specifies ObjectStore.RETAIN_STALE
- Transaction.abort() on the transaction in which the persistent object could be read or modified and the call does not specify a retain argument or it specifies ObjectStore.RETAIN_STALE
- ObjectStore.evict() on the object and the call does not specify a retain argument or it specifies ObjectStore.RETAIN_STALE
- ObjectStore.destroy() on the object
If an application tries to read or update a stale object, PSE/PSE Pro throws ObjectException. An application must not invoke any PSE/PSE Pro operation on a stale object.
If the methods of a class can operate on persistent objects but instances of the class itself are not persistence-capable, the class is persistence-aware. Typically, if you want a class to be persistence-aware, you run the postprocessor on it to put in the required annotations. Occasionally, you might choose to manually annotate the class to make it persistence-aware.
A transient object is an object that is not already in a database.
When an application commits a transaction, PSE/PSE Pro stores in the database any transient objects that can be reached transitively from any persistent object. This is the process of transitive persistence.
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, places them in a directory you specify (a directory other than the source directory), and adds lines of code (annotations) that are required for persistence. Complete information about annotations is in Chapter 9, Automatically Generating Persistence-Capable Classes.
A database root is an object that has a name and an assigned object. Each database root is associated with one segment in one database. Your application creates a database root to establish transitive persistence for the first object your application stores. Your application uses a database root to locate the first object in the database within a session. Information about database roots is in Creating Database Roots.
To use PSE or PSE Pro you must
[previous] [next]
doc@odi.com
Copyright © 1997 Object Design, Inc. All rights
reserved.
Updated: 05/13/97 12:16:53