Contents

Preface

• What Is PSE/PSE Pro?
• What Does PSE/PSE Pro Do?
• What Are the Benefits of Using PSE/PSE Pro?
• Definitions of PSE/PSE Pro Terms
  • Session
  • Persistence-Capable
  • Persistent Object
  • Persistence-Aware
  • Transient Object
  • Transitive Persistence
  • Annotations
  • Database Roots
• Prerequisites for Using PSE/PSE Pro Java Interface

• Overview of Required Components
• Sample Code
• Before You Run the Program
  • Adding Entries to CLASSPATH
  • Compiling the Program
  • Running the Postprocessor
• Running the Program

• Relationship Between Threads and Sessions
  • Cooperating Threads
  • Noncooperating Threads
  • Multiple Sessions in PSE
• Which Threads Can Access Which Persistent Objects?
  • Effects of Committing a Transaction
  • Multiple Representations of the Same Object
  • Application Responsibility
  • Description of Allowable Simultaneous Actions
  • Metaobjects and Sessions
• Allowing Threads to Use PSE/PSE Pro
  • Initializing a Session
  • Adding Threads to a Session
  • Threads and Applets
• Understanding Concurrency
  • Turning On Database Locking
  • How Database Locking Works

• Creating a Database
  • Method Signature
  • Example
  • Result
  • Specifying a Database Name
  • Database Already Exists
  • Segments
• Opening and Closing a Database
  • Opening a Database
  • Possible Open Types
  • Closing a Database
• Moving or Copying a Database
• Destroying a Database
• Obtaining Information About a Database
  • Is a Database Open?
  • Is a Database Open for Update or ReadOnly?
  • What Is the Path Name of a Database?
  • What Is the Size of a Database?
  • Displaying Information About a Database
  • Checking References in a Database
• Database Operations and Transactions
• Restrictions

• Starting a Transaction
  • Calling the begin() Method
  • Modifying Objects in a Transaction
  • Update and Read-Only Transactions
  • Transactions and Sessions
  • Transaction Already in Progress
• Ending a Transaction
  • Committing Transactions
  • What Can Cause a Transaction Commit to Fail?
  • Aborting Transactions
• Determining If a Transaction Is in Progress
• Determining Transaction Boundaries
  • Inconsistent Database State
  • Multiple Cooperating Threads

• Storing Objects
• Creating Database Roots
  • Calling Database.createRoot()
  • How Many Roots Are Needed in a Database?
  • Roots with Null Values
  • Using Primitive Values as Roots
  • Changing the Object Referred to by a Database Root
  • Destroying a Database Root
• Retrieving Persistent Objects
  • Steps for Retrieving Persistent Objects
  • Calling the getRoot() Method
• Updating Objects in the Database
  • Background for Specifying Object State
  • About the Object Table
• Committing Transactions to Save Modifications and Set Object State
  • Making Persistent Objects Stale
  • Making Persistent Objects Hollow
  • Retaining Persistent Objects as Readable
  • Retaining Persistent Objects as Writable
• Evicting Objects to Save Modifications and Set Object State
  • Setting the Evicted Object to be Stale
  • Setting the Evicted Object to be Hollow
  • Setting the Evicted Object to Remain Active
  • Evicting All Persistent Objects
  • Evicting Objects Outside a Transaction
  • Evicting Objects When There Are Cooperating Threads
  • Committing Transactions After Evicting Objects
  • If You Do Not Plan to Run the Postprocessor
• Aborting Transactions to Cancel Changes
  • Setting Persistent Objects to the Default State
  • Setting the Default Abort Retain State
  • Specifying a Particular State for Persistent Objects
• Destroying Objects in the Database
  • Calling ObjectStore.destroy()
  • Destroying Objects That Are Referred to by Other Objects
• Default Effects of Various Methods on Object State

• Requirements for Hash Code Methods
• Providing an Appropriate Persistent Hash Code Method
• Storing Built-in Types in Persistent Collections

• Obtaining PSE/PSE Pro Version Information
• Which Java-Supplied Classes Are Persistence-Capable?
  • Description of Java-Supplied Persistence-Capable Classes
  • Can Other Java-Supplied Classes Be Persistence-Capable?
• Serializing Persistent Objects

• Overview of the Class File Postprocessor
  • Description of the Annotations
  • Description of the Process
  • Postprocessing a Batch of Files Is Important
  • Manual Annotation
• Running the Postprocessor
  • Preparations
  • Requirements
  • Example
  • About the Destination Directory
  • How the Postprocessor Interprets File Names
  • Order of Processing
  • How the Postprocessor Handles Duplicate File Specifications
  • Files Not Found
  • Zip Files
  • Previously Annotated Classes
  • Troubleshooting OutOFMemory Error
• Managing Annotated Class Files
  • Ensuring That the Compiler Finds Unannotated Class Files
  • Ensuring That PSE/PSE Pro Finds Annotated Class Files
  • Using the Right Class Files in Complex Applications
  • Alternatives for Finding the Right Files
  • How the Postprocessor Determines Whether or Not to Generate an Annotated Class File
• Creating Persistence-Aware Classes
  • Specifying the Postprocessor Command Line
  • No Changes to Superclasses
• How the Postprocessor Works
  • Ensuring Consistent Class Files
  • Modifications to Superclasses
  • Modifications to Inheritance
  • Location of Annotated Class Files
  • Postprocessor Errors and Warnings
  • Handling of Final Fields
  • Handling of Static Fields That Can Hold Persistent Values
  • Which Java Executable to Use
  • Using a Debugger
  • Line-Number and Local-Variable Information
• Including Nonpersistence-Capable and Already Annotated Classes
• Putting Processed Classes in a New Package
  • Using the -translatepackage Option
  • How the Postprocessor Applies the Option
  • Updating References to New Package Name
  • References to Transient and Persistent Versions of a Class
• Creating Persistence-Capable Classes with Transient Fields
• Customizing Updated Classes
  • Implementing Customized Methods and Hook Methods
  • Creating a Hollow Object Constructor
• Optimizing Operations That Retrieve Persistent Objects
• Specifying the Number of Array Dimensions in Persistence-Capable Classes
• Generating Persistence-Capable Interfaces
• Performing a Test Run of the Postprocessor
• Using an Input File for the Postprocessor Command Line
• Annotations You Must Add
  • Interfacing with Nonpersistent Methods
  • Interfacing with Native Classes
  • Annotating Subclasses
  • Implementing the Hollow Object Constructor for Some Instance Fields
  • Passing Arrays
  • Using the Java Reflection API with Persistence-Capable Objects
• Class File Postprocessor Limitations
• Reference Information for Running the Postprocessor

• Explicitly Defining Persistence-Capable Classes
  • Choosing Whether to Inherit From Persistent or HashPersistent
  • Defining Required Methods in the Class Definition
  • Making Object Contents Accessible
  • Defining a ClassInfo Subclass
  • Example of a Manually Annotated Persistence-Capable Class
• Additional Information About Manual Annotation
  • Working with Transient-Only and Persistent-Only Fields
  • Allowing Arrays of Interfaces to Be Persistence-Capable
  • Defining Persistence-Aware Classes
  • Following Postprocessor Conventions
  • Annotating Abstract Classes
• Creating and Accessing Fields in Annotations
  • Making Persistent Objects Accessible
  • Creating Fields
  • Getting and Setting Generic Object Field Values
  • Methods for Creating Fields and Accessing Them in Generic Objects

Updated: 05/13/97 12:16:17