Guide Reference Contents Previous Next Index
This chapter describes how to use Objectivity for Java to perform database replication tasks. You may perform these tasks only if you have purchased and installed Objectivity/DB Data Replication Option (Objectivity/DRO). For a conceptual discussion of database images, see the Objectivity/FTO and Objectivity/DRO book.
Before you can install and use Objectivity/DRO, you must install both the Objectivity/DB Fault Tolerant Option (Objectivity/FTO) and the Advanced Multithreaded Server (AMS). You must have at least two autonomous partitions in your federated database. For information on installing AMS, see the Installation and Platform Notes for your operating system. For information on using AMS, see the Objectivity/DB administration 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/DRO tool as an alternative to using the programming interface, the task description identifies that tool.
Objectivity/DRO enables you to create and manage multiple replicas of a database, called database images. If an application's boot partition contains an image of the database, the application will use that image; otherwise, the application reads a single image in a different partition. If one image of a particular database becomes unavailable due to a network or machine failure, work may continue with an available image.
All images of a database share the same system name and database identifier, but each image is controlled by a different autonomous partition (see Chapter 16, "Autonomous Partitions," for information on autonomous partitions) and each image has a distinct weight, which is used to determine whether a quorum of images exists. In general, tasks affecting database images require that a quorum of the database images be available (an image is available if the containing partition is available).
All images of a database are either read-only or read-write (see "Making a Database Read-Only"). If you make one database image read-only, all images are automatically made read-only. While a database is read-only, you cannot add, delete, or change the properties of an individual image.
In general, Objectivity/DB tools and Objectivity for Java methods operate the same whether or not you have installed Objectivity/DRO and created multiple images of databases. Several methods of ooDBObj, however, can be used to return information if there is one image of a database, but throw an exception if the federated database contains multiple images of the target database. When this is the case, an alternative method is available for use with multiple images, as shown in the following table.
| Method for Single Image | Method for Multiple Images |
|---|---|
| getContainingPartition | containingImage |
| filename | getImageFileName |
| hostName | getImageHostNamegetImagePathName |
Must have access to: At least one partition containing an image of the database
By default, applications cannot read or write a replicated database unless they have access to a quorum of its images. An application can enable reading a database even when a quorum of images is not available.
To allow your application to read a database even if a quorum of images is not available, call the setNonQuorumReadAllowed method of the database, passing true as the parameter. Nonquorum reads will be disabled automatically at the end of the transaction.
To require a quorum before your application can read a database, call its setNonQuorumReadAllowed method, passing false as the parameter.
To test whether your application can read from the database if a quorum is not available, call the isNonQuorumReadAllowed method.
To test whether your application is currently reading from the database without a an available quorum, call the isNonQuorumRead method.
Must have access to: All autonomous partitions
Tool alternative: oonewdbimage (see the Objectivity/FTO and Objectivity/DRO book)
You can create an image of a particular database in any autonomous partition that does not already contain an image of that database. Before you create a database image in an autonomous partition on a new host machine, you must start an AMS server on that host. All images of all replicated databases must reside on host machines that are running AMS.
To replicate a database that has only one image, AMS must be running on both the host machine on which the original database file resides and the host machine that is to contain the new image.
To create a database image, call the replicate method of the database. The parameters identify the autonomous partition in which to create the new image, the host machine and directory path for the image's database file, and the quorum weight for the new image.
If the database is read-only, you must change it back to read-write before you can create a new image of it (see "Making a Database Read-Only").
ExampleThis example creates an image of a database named DB1 with a weight 3 in an autonomous partition named Partition2.
ooFDObj fd = session.getFD();
session.begin();
db = fd.lookupDB("DB1");
ap = fd.lookupAP("Partition2");
db.replicate(ap, "", "", 3);
session.commit();
The following attributes of a database image are set when the image is created:
You can get any of these attributes and you can change the weight of the image.
Must have access to: The partition containing the image
Tool alternative: oochangedb with the -db or -id flag, the -ap flag, and no other flags (see the Objectivity/DB administration book)
You can use the following methods of a database to get the attributes of a database image; the parameter specifies the autonomous partition containing the image of interest.
| Member Function | Gets Attribute |
|---|---|
| getImageHostName | Host where database file is located |
| getImagePathName | Pathname of directory where database file is located |
| getImageFileName | Fully qualified name of the database file |
| getImageWeight | Weight |
Must have access to: All autonomous partitions
Tool alternative: oochangedb (see the Objectivity/DB administration book)
To change the weight of a database image, call the setImageWeight method of a database. The parameters specify the autonomous partition containing the image and the new weight for that image. This method throws an exception if the specified partition does not contain an image of the database.
If the database is read-only, you must change it back to read-write before you can change its weight (see "Making a Database Read-Only").
Must have access to: At least one partition containing an image of the database
To test whether the federated database contains multiple images of a database, call the isReplicated method of the database.
To find out how many images of a database exist, call its getImageCount method.
Must have access to: At least one partition containing an image of the database
To test whether a database is available, call its isAvailable method. The result is true if a quorum of images is physically accessible.
To test whether a particular partition contains an image of a database, call the hasImageIn method of the database, passing the partition as the parameter.
To test whether the image of a database in a particular partition is available, call the isImageAvailable method, passing the partition as the parameter. The result is true if the specified partition has an image of the database and that partition is accessible to the current process.
You can add, remove, or retrieve the tie-breaker partition for a database.
Must have access to: All autonomous partitions
Tool alternative: oonewdbimage with the -tiebreaker flag (see the Objectivity/FTO and Objectivity/DRO book)
To add a tie-breaker partition for a database, or to change the tie-breaker to be a different partition, call the setTieBreaker method of the database. The parameter is the autonomous partition that is to serve as the tie breaker during quorum negotiation; it can be any partition that does not already contain an image of the database. The host for the tie-breaker partition must be running a lock server.
Must have access to: All autonomous partitions
Tool alternative: oodeletedbimage with the -tiebreaker flag (see the Objectivity/FTO and Objectivity/DRO book)
To remove the tie-breaker partition for a database, call the setTieBreaker method of the database, passing null as the parameter.
Must have access to: The tie-breaker partition
To retrieve the tie-breaker partition for a database, call the getTieBreaker method of the database.
Must have access to: All autonomous partitions that contain an image of the database
To obtain an iterator that finds all partitions that contain an image of a particular database, call the containingImage method of the database.
Must have access to: All autonomous partitions
Tool alternative: oodeletedbimage (see the Objectivity/FTO and Objectivity/DRO book)
To delete a particular image of a database, call the deleteImage method of the database; the parameter indicates the autonomous partition that contains the image to be deleted. This method allows you to specify whether the deletion should proceed if the specified partition contains the last remaining image of the database. If the given partition does not contain an image of the database, this method throws an exception.
If the database is read-only, you must change it back to read-write before you can delete an image of it (see "Making a Database Read-Only").
Must have access to: A quorum of images for any database to be resynchronized
After a hardware or network failure is corrected, the federated database must be restored to a consistent state. Your installation should have a recovery application that is run when autonomous partitions that were inaccessible become accessible again. The recovery procedure should resynchronize every database with an image in the restored partitions.
To resynchronize the images of a particular database, call the negotiateQuorum method of the database. The parameter is a lock mode indicating the type of lock to obtain for the database. This method forces recalculation of the quorum for the database, which causes Objectivity/DB to synchronize out-of-date images with images that were updated while one or more partitions were unavailable. If the application does not have access to a quorum, the images are not resynchronized.
The negotiateQuorum method should be used only after the federated database has been restored to a consistent state by the oocleanup administrative tool (see the Objectivity/DB administration book).
ExampleThis example first checks that all partitions are available. If so, it resynchronizes all databases in the federated database.
void resynch (ooFDObj fd) {
ooAPObj ap ;
ooDBObj db ;
// Initialize an iterator for all partitions
Iterator apItr = fd.containedAPs() ;
while(apItr.hasNext()) {
ap = (ooAPObj)apItr.next() ;
if (!ap.isAvailable()) {
System.out.println(ap.getName() +
" is not available");
return ;
}
}
// All partitions are available
// Initialize an iterator for all databases
Iterator dbItr = fd.containedDBs() ;
// Use the iterator to resynchronize each database
try {
while(dbItr.hasNext()) {
db = (ooDBObj)dbItr.next() ;
db.negotiateQuorum(oo.READ);
System.out.println(db.getName() +
" has been resynchronized ");
}
}
catch (ObjyRuntimeException e1) {
System.out.println("negotiateQuorum failed");
}
}
Guide Reference Contents Previous Next Index