Guide Reference Contents Previous Next Index
This chapter describes how to use Objectivity for Java to perform autonomous-partition administration tasks. You may perform these tasks only if you have purchased and installed Objectivity/DB Fault Tolerant Option (Objectivity/FTO). For a conceptual discussion of autonomous partitions, see the Objectivity/FTO and Objectivity/DRO book.
The description of each task indicates which partitions must be available to perform the task. If a task can be performed through an Objectivity/DB or Objectivity/FTO tool as an alternative to using the programming interface, the task description identifies that tool.
Unless otherwise indicated, autonomous-partition tasks are also valid in an Objectivity/DB Data Replication Option (Objectivity/DRO) environment (see Chapter 17, "Database Images").
An autonomous partition is an independent piece of a federated database. Each autonomous partition is self-sufficient in case a network or system failure occurs in another partition. Although data physically resides in database files, each autonomous partition controls access to particular databases (or database images) and containers.
Each autonomous partition can perform most database functions independently of other autonomous partitions, because each partition has all the system resources necessary to run an Objectivity/DB application, including a boot file, a lock server, and a system database file. The system database file contains schema information and a global catalog of all autonomous partitions, their locations, and the databases they contain. When you create, modify, or delete a partition, however, Objectivity/DB needs access to all partitions in the federated database so that it can update each partition's global catalog.
Must have access to: The desired boot partition
To open a connection to a federated database with a particular autonomous partition as the boot autonomous partition for your application, pass the pathname of that partition's boot file to the Connection.open static method.
By default, applications enforce the offline status of partitions. If you want a session to be able to access offline partitions other than your application's boot autonomous partition, call the setOfflineMode method of the session to set the offline mode for your application. Specify the offline mode IGNORE to ignore the offline status of partitions.
If you later want to return to enforcing the offline status of partitions, call the session's setOfflineMode method again, specifying the offline mode ENFORCE.
To check whether the application is enforcing or ignoring the offline status of partitions, call the getOfflineMode method of the session.
Must have access to: All autonomous partitions
Tool alternative: oonewap (see the Objectivity/FTO and Objectivity/DRO book)
The first autonomous partition in a federated database is created implicitly when you create the federated database. You must create any additional partitions explicitly.
To create a new autonomous partition, call one of the newAP methods of the federated database. These methods create:
The simpler newAP method requires you to specify the system name of the partition, the name of the lock server host for the partition, and the host and directory path where the partition's system database file is to be located. It creates the partition's boot file and the journal file in the same directory, on the same host as the partition's system database file.
The second newAP method additionally requires you to specify the host and directory path for the partition's boot file and for its journal file.
When you commit or checkpoint the transaction in which you create a partition, the partition is created in the federated database. If you instead abort the transaction, the partition becomes a dead object and no physical partition is created.
ExampleThis code fragment creates a session and retrieves its associated federated database. It then calls the federated database's hasAP method to check whether an autonomous partition named VehiclesPartition exists and if so, retrieves it from the federated database. You should check whether the partition exists before doing the lookup, because the lookup operation will throw an exception if a partition with the name VehiclesPartition does not exist in the federated database. If the partition does not exist, the example creates a new partition in the federated database.
Session session = new Session();
session.begin();
ooFDObj vrcFD = session.getFD();
if (vrcFD.hasAP("VehiclesPartition"))
ooAPObj vehiclesPartition =
vrcFD.lookupAP("VehiclesPartition");
else {
vehiclesPartition = vrcFD.newAP("VehiclesAP");
System.out.println("Created partition \"VehiclesAP\".");
}
session.commit();
You can retrieve a partition from the federated database that contains the partition, from a database that the partition contains, or from a container that the partition controls.
Must have access to: The boot autonomous partition
Call the getBootAP method of the federated database to retrieve the autonomous partition whose boot file was used to open a connection to the federated database. This autonomous partition is the boot autonomous partition for the application.
Must have access to: The desired autonomous partition
Call the lookupAP method of the federated database to retrieve the autonomous partition with a specified system name. This method throws an exception if the federated database does not have a partition with the specified name. You can call the hasAP method of the federated database to check whether the partition exists.
Must have access to: All autonomous partitions
To obtain an iterator that finds all partitions in the federated database, call the containedAPs method of the federated database.
Must have access to: The containing partition
If a single image of a database exists, you can find the autonomous partition that contains the database by calling the getContainingPartition method of the database.
Must have access to: The controlling partition
To find the autonomous partition that controls a container, call the container's getControlledBy method.
The following attributes of a partition are set when the partition is created:
You can get any of these attributes and you can change the offline status.
Must have access to: The partition of interest
Tool alternative: oochange with the oochange tool with the -ap or -id flag and no other parameters (see the the Objectivity/DB administration book)
You can use the following methods of an autonomous partition to get its attributes:
| Member Function | Gets Attribute |
|---|---|
| getName | System name |
| getLockServerHost | Lock server host |
| getSystemDBFileHost | Host for system database file |
| getSystemDBFilePath | Path for directory of system database file |
| getBootFileHost | Host for boot file |
| getBootFilePath | Path for directory of boot file |
| getJournalDirHost | Host for journal file |
| getJournalDirPath | Path for directory of journal file |
| isOnline | Offline status |
Must have access to: The autonomous partition of interest
Tool alternative: oochange with the -ap or -id option (see the Objectivity/DB administration book)
To change the offline status of a partition, call its setOnline method. Pass false as the parameter to make the partition offline; pass true as the parameter to make the partition online.
An autonomous partition controls access to:
Objectivity for Java creates all databases in the initial autonomous partition of the federated database. You can:
Must have access to: All autonomous partitions
Tool alternative: oochangedb with the -movetoap option (see the Objectivity/DB administration book)
You can move a database to a different partition unless there is more than one image of the database. To move a database to a different partition, call the changePartition method of the database. This method creates a new image of the database in the destination autonomous partition and deletes the database from its current partition. If there are multiple images of the database, or if the database has been updated during the partition-changing transaction, an exception is thrown.
This method changes logical containment and updates the global catalog in all autonomous partitions. If you also want to change the physical location of a database file, you must do so using the Objectivity/DB oochangedb tool with the -host and/or -filepath flags.
Must have access to: The partition of interest
To obtain an iterator that finds all databases in an autonomous partition, call the imagesContainedIn method of the partition.
A newly created container comes under the control of its database's containing partition. You can use Objectivity for Java to:
Transferring control of a container causes the container to be moved physically to the system database file of the destination partition. Returning control causes the container to be moved physically to the database file of its database. Changing control of a container does not affect the container's logical containment relationships.
Tool alternative: oochangecont (see the Objectivity/FTO and Objectivity/DRO book)
To transfer control of a container, call the transferControl method of the container. The destination partition can be any partition, even one that does not contain an image of the container's database.
Tool alternative: oochangecont (see the Objectivity/FTO and Objectivity/DRO book)
To return control of a container to the autonomous partition that contains the container's database, call the returnControl method of the container.
Tool alternative: ooclearap (see the Objectivity/FTO and Objectivity/DRO book)
Clearing an autonomous partition releases the partition's control of all containers whose control has been transferred to the partition. The control of each such container is returned to the autonomous partition of that container's database.
To clear a partition, call the returnAll method of the partition.
Must have access to: The partition of interest
To obtain an iterator that finds all containers controlled by an autonomous partition, call the containersControlledBy method of the partition. Indirectly controlled containers, which the partition controls by virtue of containing their databases, are not included.
An autonomous partition may serve as a scope object. See "Scope Names" for information on how scope naming works. A scope object uses the hashing mechanism of a hashed container to associate each name in the name scope with the appropriate object. An autonomous partition uses the roots container of the default database of its federated database to store names.
When you name a transient object in the scope of an autonomous partition, the object is made persistent. If the transient object is a container, it is clustered in the default database of its federated database; if the object is a basic object, it is clustered in the roots container of the default database of its federated database. See Chapter 12, "Clustering Objects," for more information about clustering.
The following methods of an autonomous partition are used to manage its scope:
Must have access to: All autonomous partitions
Tool alternative: oodeleteap (see the Objectivity/FTO and Objectivity/DRO book)
To delete an autonomous partition, call its delete method.
Deleting an autonomous partition:
You cannot delete an autonomous partition if it contains any databases (or the last image of any database); you must first move such databases to another partition.
Until the current transaction is committed, the local representation of the partition continues to exist in your application's memory. When you commit or checkpoint the transaction in which you delete a partition, the physical partition is deleted from the federated database. If the partition controls the last image of a database, an exception will be thrown and the partition is left unchanged.
Guide Reference Contents Previous Next Index