Guide  Reference  Contents  Previous  Next  Index

Programming Examples

This chapter contains programming examples used as illustrations in earlier chapters of this guide. The examples are organized according to the chapters in which they are discussed. The files for the examples are in the chapter name subdirectory of the programming samples directory. See Installation and Platform Notes for the location of the samples directory for your platform.

Some examples can be executed after creating a federated database and compiling the files. See the directions for particular examples for details.

In This Chapter

Getting Started

Application Objects

ODMG Application Objects

Storage Objects

Defining Persistence-Capable Classes

RentalFields Package

RentalMap Package

RentalRelations Package

PersistentInterface Package

Naming and Retrieving Persistent Objects

Sales Package

Traversal Package

Clustering Objects

Container-Pool Strategy

Cluster-By-Class Strategy

Getting Started

The example from Chapter 1, "Getting Started" is a complete application that uses all the elements introduced in "Objectivity for Java API". The example application is intended to be used by the agents and managers of a vehicle rental company. The operations supported are:

• Add a vehicle to the rental company's fleet of vehicles.

• Delete a vehicle from the fleet.

• List:
  • All the vehicles in the fleet.

  • Only the vehicles that satisfy a predicate.

• Rent a vehicle.

• Return a rented vehicle.

The application is implemented by four classes:

• Vehicle , which implements a vehicle that can be rented and returned.

• Fleet , which implements a fleet of vehicles.

• VrcInit , which initializes the rental company database.

• Vrc , which implements the interactive application for accessing the database of the vehicle rental company.

To execute this example, you need to:

1. Compile the files Vehicle.java, Fleet.java, VrcInit.java, and Vrc.java located in the GettingStarted subdirectory of the programming samples directory. See the Installation and Platform Notes for your operating system for the location of the samples directory for your platform.

2. Start an Objectivity/DB lock server.

3. Create a federated database called Vrc in the GettingStarted sample directory.

4. Execute VrcInit to initialize the federated database.

See the Objectivity/DB administration book for information on the tools used to create a federated database and start a lockserver.

Application Objects

The example discussed in Chapter 2, "Application Objects" illustrates how to use the application classes Connection and Session, in particular how to develop a multi-threaded application.

The MultipleThreadsSP programming example simulates a server application handling requests to look up or list root objects in a database. The server creates a new thread to handle each request. Instead of having each thread create a new session, the example shares a pool of sessions among the threads. Access to the pool of sessions is synchronized. The session pool is implemented in the SessionPool class . The example also illustrates the use of a restricted thread policy: before a thread uses a session that it retrieves from the pool, it executes a join operation.

This example can be executed after you compile the files and create a federated database named "Objects" in the Application subdirectory of the samples directory.

ODMG Application Objects

The example discussed in Chapter 3, "ODMG Application Objects" illustrates how to use the ODMG Application Classes: Database and Transaction, in particular how to develop a multi-threaded application.

The MultipleThreadsTP programming example simulates a server application handling requests to look up root objects in a database. The server creates a new thread to handle each request and each thread gets a transaction from a shared pool of transactions. The transaction pool is implemented in the TransactionPool class.

This example can be executed after you compile the files and create a federated database named "Objects" in the ODMGApplication subdirectory of the samples directory.

Storage Objects

The example discussed in Chapter 5, "Storage Objects" illustrates how to use multiple containers to improve scalability and concurrency. The example revisits the vehicle rental company example introduced in Chapter 1, "Getting Started". The implementation is changed as follows:

• The Fleet class uses a map instead of a fixed-size array to maintain its link with all its contained vehicles . Chapter 6, "Defining Persistence-Capable Classes," discusses trade-offs between various implementations of links to multiple objects. The fleet remains a named root in the vehicles database.

• The vehicles themselves are randomly distributed among a fixed-size container pool of garbage-collectible containers, instead of being stored in a single container. This allows one container to be updated without preventing other containers from being accessed. The container pool is also a named root in the vehicles database.

The vehicles are stored according to the container pool clustering strategy . This strategy is installed in the sessions used by the database initialization class VrcInit and the interactive application class Vrc .

The files for this example are in the Storage subdirectory of the programming samples directory.

To execute this example, you need to:

1. Compile the files Fleet.java, VrcInit.java, Vrc.java, and ContainerPool*.java in the Storage subdirectory of the programming samples directory.

2. Start an Objectivity/DB lock server.

3. Create a federated database called Vrc in the Storage directory.

4. Execute VrcInit to initialize the federated database.

Defining Persistence-Capable Classes

The example in Chapter 1, "Getting Started," described how to define a persistence capable class using inheritance and developed a simple application that accessed objects of that class. The examples discussed in Chapter 6, "Defining Persistence-Capable Classes," illustrate:

• How to define field access methods and relationship access methods for persistence-capable classes.

• Alternative ways to implement links between associated objects:
  • Classes in the RentalFields package use references in persistent fields to implement links between objects; an array of references in a persistent field implements a link from one object to many associated objects.

  • In the RentalMap package, a map in a persistent field implements a link from one object to many associated objects.

  • Classes in the RentalRelations package use relationships to implement links between objects.

• How to define a persistence-capable class by implementing the Persistent interface.

RentalFields Package

The RentalFields package contains three classes:

• The Vehicle class represents vehicles in a rental fleet. A reference in a vehicle's fleet field links the vehicle to its fleet. In addition to field access methods, this class has a method printInfo that illustrates how to obtain properties of a persistent object that are managed by Objectivity for Java; you should not define persistent fields corresponding to any of these properties.

• The SimpleFleet class represents rental fleets. An array of references in a fleet's vehicles field links the fleet to the vehicles it contains. The field access methods for the vehicles field get and set the vehicle at a given array index.

• The Fleet class is an alternative implementation of the SimpleFleet class. The field access methods for the vehicles field hide the array implementation.

RentalMap Package

The RentalMap package contains two classes:

• The Vehicle class is identical to the RentalFields.Vehicle class; a reference in a vehicle's fleet field links the vehicle to its fleet.

• The Fleet class is an alternative implementation of the RentalFields.Fleet class. A map referenced in a fleet's vehicles field links the fleet to the vehicles it contains. This class provides the same set of field access methods for the vehicles field as the RentalFields.Fleet class.

RentalRelations Package

The RentalRelations package contains two classes:

• The Vehicle class is an alternative implementation of the RentalFields.Vehicle class. A many-to-one relationship in a vehicle's fleet field links the vehicle to its fleet.

• The Fleet class is an alternative implementation of the RentalFields.Fleet and RentalMap.Fleet classes. A one-to-many relationship in a fleet's vehicles field links the fleet to the vehicles it contains. This class contains the same field access methods for the vehicles field as the RentalFields.Fleet and RentalMap.Vehicle classes.

PersistentInterface Package

The PersistentInterface package contains two classes:

• The Vehicle class introduced in Chapter 1, "Getting Started," is modified to implement the Persistent interface, instead of inheriting from ooObj. Because this class implements the Persistent interface, vehicle objects can participate in Objectivity for Java operations that require implicit persistence behavior (such as being made a named root).

• The Delegator class is a utility class whose static methods perform persistent operations by invoking the appropriate methods of a vehicle's persistor.

Naming and Retrieving Persistent Objects

The examples discussed in Chapter 10, "Naming Persistent Objects," and Chapter 11, "Retrieving Persistent Objects," illustrate how to name and retrieve a persistent object. The examples in those chapters come from two packages:

• The Sales package illustrates three alternative ways for naming an object and shows how to look up objects by each kind of name. It also illustrates how to find objects by following a to-many relationship from a retrieved object.

• The Traversal package illustrates how to retrieve objects by traversing the storage hierarchy.

Sales Package

The Sales package contains four classes:

• The Interact class contains static utility methods that are called to create and retrieve objects of the other three classes. Interact can be executed after you compile all the classes and create a federated database named "Sales" in the NamingAndRetrieving subdirectory of the samples directory.

• Every salesperson of the Salesperson class is a named root in the Sales database and can be looked up by its root name. Methods of this class allow you to retrieve the contacts related to a particular salesperson.

• Every contact of the Contact class is given a scope name in the scope of the ContactNames container in the Sales database. Contacts can be looked up by their scope names.

• Every client of the Client class is given a name in an application-specific name table. The name table itself is a named root in the Corporate federated database.

Traversal Package

The Traversal package contains three classes, but the only one with methods is Tester. Tester can be executed after you compile all the classes and create a federated database named "Traverse" in the NamingAndRetrieving subdirectory of the samples directory.

• The Tester.createObjects static method creates databases, containers, and basic objects of the classes Apple and Orange in the connected federated database.

• The Tester.traverse static method illustrates how to traverse the storage hierarchy, retrieving every object in the federated database.

• The Tester.retrieveAgain static method illustrates how to retrieve an object by its OID. This method is called from Tester.traverse to illustrate that each session can have its own local representation of an object.

• The Tester.main static method creates objects in the federated database by calling Tester.createObjects and traverses the storage hierarchy by calling Tester.traverse.

Clustering Objects

The examples discussed in Chapter 12, "Clustering Objects" illustrate two application-specific clustering strategies. Both clustering strategies use container pools associated with particular databases.

Container-Pool Strategy

A container pool is an object of the ContainerPool class. Each database has two container pools, one containing garbage-collectible containers and the other containing non-garbage-collectible containers. A database identifies its container pools with the scope names "GCContainerPool" and "Non-GCContainerPool", respectively. When a container pool is created, parameters to its constructor specify its database, the number of containers in the pool, and whether the containers are garbage collectible.

The ContainerPoolStrategy class implements a clustering strategy that performs as follows:

• Cluster a container in the database of the requesting object.

• Cluster a basic object being made a named root in a garbage-collectible container selected from the container pool of the database of the requesting object.

• Cluster a scope-named basic object in a non-garbage-collectible container selected from the container pool of the database of the requesting object.

• Cluster any other basic object with the requesting object.

Cluster-By-Class Strategy

ClusterByClassStrategy extends ContainerPoolStrategy to accept an application-specific clustering reason of the JustCreatedReason class. Such a clustering reason indicates that an object is being made persistent because it is a newly created object of a class whose objects are always persistent. The strategy decides where to cluster such an object based on its class:

• Cluster a newly created object of the Account class in a garbage-collectible container selected from the container pool of the database named "Accounting".

• Cluster a newly created object of the Employee class in a non-garbage-collectible container selected from the container pool of the database named "Staff".

Objects of these two classes are made persistent as soon as they are created.

• Every Account object has an associated branch office. When an account is created, it is made persistent with a direct call to the requestCluster method of the session that owns its associated branch office; the branch office is the object requesting clustering. Note that the session of the branch office might use the default clustering strategy, the container-pool strategy, or the cluster-by-class strategy.

• Every Employee object also has an associated branch office. When an employee is created, it is made persistent with a direct call to the requestCluster method of a newly created cluster-by-class strategy; the branch office is the object requesting clustering.

Guide  Reference  Contents  Previous  Next  Index