|
Objectivity for Java Reference | |||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||
java.lang.Object
|
+--com.objy.db.app.ooAbstractObj
|
+--com.objy.db.app.ooDBObj
Represents an Objectivity/DB database.
| API Summary |
A database is the second highest level in the Objectivity/DB storage hierarchy. It contains one or more containers which, in turn, contain fundamental units of persistent data called basic objects.
A database is physically maintained in a database file. This file contains the database and all of its containers and basic objects. Each database is attached to exactly one federated database and is listed in that federated database's catalog. A database has a system name, which is its logical name within the federated database.
To create a new database, call one of the newDB methods on an instance of ooFDObj. These methods create a new database file, a database in the federated database, a default container in the database, an instance of ooDBObj in your application, and lock the database in write mode.
You can get an object representing an existing database in any one of the following ways:
Note: A database object belongs to the session that is in a transaction when the database is created or retrieved. Objectivity for Java does not allow a database to interact with objects that belong to different sessions; see Object Isolation.
Once you have a database object, you can:
The session that owns the database object must be in a transaction when you call methods defined in this class.
In collaboration with autonomous partitions, databases can also manage images or replicas of the database file. Each replica has an integer-valued weight. If the sum of the weights of the images available to an application is greater than half of the total weight of the images, that set of images constitutes a quorum. To guarantee database consistency, a quorum must be available to an application in order for database access operations to succeed.
In some circumstances, it may be desirable to have access to data even in the absence of a quorum. An alternative configuration allowing this access makes use of a tie-breaker autonomous partition. The tie-breaker is a partition that has its own lock server and functions like a pseudo-image. It contains no data, but participates as a member of the database quorum.
For additional information about using databases in your application, see Databases.
| Constructor Summary | |
ooDBObj(PooDBObj persistor)
Reserved for internal use; to create a database object, call one of the newDB methods of a federated database. |
|
| Method Summary | |
void |
addContainer(ooContObj container,
String name,
long hash,
long initialPages,
long growthFactor)
Adds the specified container with the specified system name, hash value, number of initial pages, and percent growth to this database. |
void |
addIndex(String name,
String className,
String fieldList)
Adds an index to this database. |
void |
addUniqueIndex(String name,
String className,
String fieldList)
Adds a unique index to this database. |
void |
bind(Object object,
String name)
Names the specified object with the specified root name in this database. |
void |
changePartition(ooAPObj partition)
(FTO) Changes the autonomous partition that contains this database. |
void |
cluster(Object object)
Makes the specified object persistent, clustering it in this database. |
long |
connectionId()
Reserved for internal use; you should not call this method. |
Iterator |
containingImage()
(DRO) Initializes an iterator to find all the autonomous partitions in which this database has images. |
Iterator |
contains()
Initializes an iterator to find all the containers in this database. |
Iterator |
contains(int filter)
(DRO) Initializes an iterator to find the containers contained in this database that satisfy the specified filter. |
void |
convertObjects()
Converts all basic objects in this database to be consistent with their current Java class definitions. |
void |
delete()
Deletes this database. |
void |
deleteImage(ooAPObj partition)
(DRO) Deletes the image of this database contained in the specified autonomous partition. |
void |
deleteImage(ooAPObj partition,
boolean deleteDBifLast)
(DRO) Deletes the image of this database in the specified autonomous partition, possibly deleting the last image of this database. |
void |
dropIndex(String name)
Drops the specified index from this database. |
void |
flush()
Transfers the data of all modified objects to this database cache. |
long |
getContainerCount()
Gets the number of containers in this database. |
ooAPObj |
getContainingPartition()
(FTO) Gets the autonomous partition which contains this database. |
ooDefaultContObj |
getDefaultContainer()
Gets the default container of this database. |
ooFDObj |
getFD()
Gets the federated database that contains this database. |
String |
getFileName()
Gets the full pathname of this database's file. |
String |
getHostName()
Gets the name of the host on which this database's file is located. |
long |
getImageCount()
(DRO) Gets the number of images of this database. |
String |
getImageFileName(ooAPObj partition)
(DRO) Gets the filename of this database's image contained in the specified autonomous partition. |
String |
getImageHostName(ooAPObj partition)
(DRO) Gets the host location of this database's image file contained in the specified autonomous partition. |
String |
getImagePathName(ooAPObj partition)
(DRO) Gets the directory location of this database's image file contained in the specified autonomous partition. |
long |
getImageWeight(ooAPObj partition)
(DRO) Gets the weight of the image of this database contained in the specified autonomous partition. |
String |
getName()
Gets the system name of this database. |
ooId |
getOid()
Gets the object identifier of this database. |
String |
getPathName()
Gets the full pathname of the directory where the database file is located. |
Session |
getSession()
Gets the session in which this database was created or retrieved. |
ooAPObj |
getTieBreaker()
(DRO) Gets the tie-breaker autonomous partition of this database. |
boolean |
hasContainer(String name)
Tests whether the container with the specified system name exists in this database. |
boolean |
hasImageIn(ooAPObj partition)
(DRO) Tests whether an image of this database exists in the specified autonomous partition. |
boolean |
hasIndex(String name)
Tests whether this database has an index with the specified name. |
boolean |
isAvailable()
(FTO/DRO) Tests whether this database is accessible by the current process. |
boolean |
isDead()
Tests whether this database is dead. |
boolean |
isImageAvailable(ooAPObj partition)
(DRO) Tests whether an image of this database in the specified autonomous partition is accessible by the current process. |
boolean |
isNonQuorumRead()
(DRO) Tests whether the application is currently reading this database without having access to a quorum of images. |
boolean |
isNonQuorumReadAllowed()
(DRO) Tests whether this application can read this database even if a quorum of images is not available. |
boolean |
isReadOnly()
Tests whether this database is read only. |
boolean |
isReplicated()
(DRO) Tests whether there is more than one image of this database. |
void |
lock(int mode)
Locks this database and everything contained in it with the specified lock mode. |
Object |
lookup(String name)
Retrieves the object with the specified root name in this database. |
ooContObj |
lookupContainer(String name)
Retrieves the container with the specified system name in this database. |
Object |
lookupObj(String scopeName)
Retrieves the object with the specified scope name in the scope defined by this database. |
Object |
lookupObj(String scopeName,
int lockMode)
Retrieves the object with the specified scope name in the scope defined by this database, locking the retrieved object as specified. |
String |
lookupObjName(Object object)
Looks up the name of the specified object in the scope defined by this database. |
void |
nameObj(Object object,
String scopeName)
Names the specified object in the scope of this database. |
void |
negotiateQuorum(int lockMode)
(DRO) Forces recalculation of the quorum for this database. |
void |
replicate(ooAPObj partition,
String hostName,
String pathName,
long weight)
(DRO) Creates an image of this database in the specified autonomous partition with the given weight. |
Iterator |
rootNames()
Initializes an iterator to find the root names maintained by this database. |
Iterator |
scan(String className)
Initializes an iterator to scan this database for objects of the specified class. |
Iterator |
scan(String className,
String predicate)
Initializes an iterator to scan this database for objects of the specified class that satisfy the specified predicate. |
Iterator |
scan(String className,
String predicate,
int access)
Deprecated. Use scan(String, String). |
void |
setImageWeight(ooAPObj partition,
long weight)
(DRO) Sets the weight of this database's image in the specified autonomous partition. |
void |
setNonQuorumReadAllowed(boolean allowed)
(DRO) Specifies whether this application can read this database if a quorum of images is not available. |
void |
setPersistor(PooDBObj persistor)
Reserved for internal use; you should not call this method. |
void |
setReadOnly(boolean value)
Set the access status of this database so that is is either read-only or read-write. |
void |
setTieBreaker(ooAPObj partition)
(DRO) Sets the tie-breaker autonomous partition of this database. |
void |
unbind(String name)
Removes a root name from this database. |
void |
unnameObj(Object object)
Removes the specified object's name from the name scope of this database. |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
public ooDBObj(PooDBObj persistor)
You should not use this constructor directly.
| Method Detail |
public Session getSession()
public ooDefaultContObj getDefaultContainer()
public String getFileName()
public String getHostName()
public String getName()
public long getContainerCount()
public ooId getOid()
public String getPathName()
public ooFDObj getFD()
public boolean isDead()
A database is made dead when you delete it, abort the transaction in which the database was created, or terminate the session to which it belongs.
public void delete()
When you delete a database, all of its containers and basic objects will be deleted. Until the current transaction is committed, this database continues to exist in your application's memory, but it and all of its contained objects are marked dead.
Warning: This operation cannot be undone by aborting the transaction.
ObjectIsDeadException - If an attempt is made
to perform delete on a dead object.public void lock(int mode)
mode - The mode in which to lock this database; one
of the following constants defined in the oo interface:
The lock mode is limited by the open mode of this database object's session. A session open mode of openReadWrite permits lock modes of WRITE or READ; a session open mode of openReadOnly only permits the lock mode READ.
If this database is already locked, you can call this method to upgrade a read lock to a write lock, but not to downgrade a write lock to a read lock.
public void flush()
After the successful execution of this method, the objects are no longer marked as modified.
This method makes the data of modified objects available to the process that calls the method, but does not make the changes permanent and available to other processes. When you commit or checkpoint the transaction, the changes become permanent.
public void cluster(Object object)
object - The transient object to be made
persistent. The object to be clustered must be an instance of a
persistence-capable class.
addContainer(com.objy.db.app.ooContObj, java.lang.String, long, long, long)
public void nameObj(Object object,
String scopeName)
If the specified object is transient, this method makes it persistent. If the specified object is already persistent, this method locks it for write.
This method locks this database for write.
object - The object to be named.scopeName - The name for the specified
object in the scope of this database.
This string must consist of only ASCII characters and must be unique
within the name scope of this database.lookupObj(java.lang.String),
unnameObj(java.lang.Object)public void unnameObj(Object object)
This method locks both this database and object for write.
object - The object whose name is to be
removed.ObjyRuntimeException - If
object has no name
in the scope of this database.lookupObj(java.lang.String),
nameObj(java.lang.Object, java.lang.String)public Object lookupObj(String scopeName)
scopeName - The scope name to look up.ObjyRuntimeException - If there is no
object named scopeName in the scope of this
database.lookupObjName(java.lang.Object)
public Object lookupObj(String scopeName,
int lockMode)
scopeName - The scope name to look
up.lockMode - The type of lock to obtain for the object;
one of the following constants defined in the oo interface:
ObjyRuntimeException - If there is no
object named scopeName in the scope of this
database.lookupObjName(java.lang.Object)public String lookupObjName(Object object)
object - The object whose name is to be
looked up.ObjyRuntimeException - If object has no
name in the scope of this database.lookupObj(java.lang.String)public boolean isAvailable()
(FTO) If the database is not replicated, it is accessible if the process can access its containing partition.
(DRO) If the database is replicated, it is accessible if the process can access a quorum of its images.
public boolean isReplicated()
public long getImageCount()
public ooAPObj getTieBreaker()
setTieBreaker(com.objy.db.app.ooAPObj)public void setTieBreaker(ooAPObj partition)
partition - The tie-breaker
autonomous partition. Any existing
tie breaker for this database is eliminated if
partition is null.ObjyRuntimeException - If
partition already contains an
image of this database.getTieBreaker()public void changePartition(ooAPObj partition)
The database is assigned to the partition partition and is removed from the current containing partition.
This method updates logical containment information in the catalogs of the 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.
You may not combine this operation with other updates to the database in the same transaction. You should consider executing changePartition in a separate transaction.
If the referenced database is read-only, you must use the
setReadOnly method to change it
back to read-write before you can change its partition.
(DRO) If multiple images of this database exist, the current containing partition will be left unchanged.
partition - The autonomous partition that
is to contain the database.public long getImageWeight(ooAPObj partition)
partition - The partition containing this
database's image.setImageWeight(com.objy.db.app.ooAPObj, long)public String getImagePathName(ooAPObj partition)
partition - The autonomous partition
containing this database's image.public String getImageFileName(ooAPObj partition)
partition - The autonomous partition
containing this database's image.public String getImageHostName(ooAPObj partition)
partition - The autonomous partition
containing this database's image.
public void setImageWeight(ooAPObj partition,
long weight)
You cannot change the weight of an image of a read-only database.
If this database is read-only, you must call the
setReadOnly method to change it
back to read-write before you can change the weight of an individual
image.
partition - The partition containing
the database image.weight - The weight to assign to the image; the weight
must be greater than 0.getImageWeight(com.objy.db.app.ooAPObj)public boolean isImageAvailable(ooAPObj partition)
partition - The autonomous partition to be
checked for a database image.public boolean hasImageIn(ooAPObj partition)
partition - The specified autonomous
partition.public void deleteImage(ooAPObj partition)
If the specified partition contains the last image of this database, that image will not be deleted.
You cannot delete an image of a read-only database. If this
database is read-only, you must call the
setReadOnly method to change it
back to read-write before you can delete an individual
image.
partition - The autonomous partition containing the image.
public void deleteImage(ooAPObj partition,
boolean deleteDBifLast)
If the specified partition contains the last image of this database and deleteDBifLast is true, that image and the database itself are deleted. If deleteDBifLast is false, the last image is not deleted.
You cannot delete an image of a read-only database. If this
database is read-only, you must call the
setReadOnly method to change it
back to read-write before you can delete an individual
image.
partition - The autonomous partition
containing the image.deleteDBifLast - True to delete the
specified image even if it is the last image of this database;
otherwise, false.
public void replicate(ooAPObj partition,
String hostName,
String pathName,
long weight)
You cannot create an image of a read-only database. If this
database is read-only, you must call the
setReadOnly method to change it
back to read-write before you can create a new
image.
partition - The partition in which this
database's image will be created.hostName - The host machine for the new image. If an
empty string is provided, the host will be the same as that hosting
the partition's system database file. The host machine must be
running AMS.pathName - The local directory path and name
of the new image's file. If an empty string is provided, the image's
file is created with a name based on this database's system name
and is placed in the same directory as the partition's system
database file.weight - The weight of the new database image.
The default is 1; the weight must be greater than 0.ObjyRuntimeException - If
partition already contains an
image of this database.public ooAPObj getContainingPartition()
public Iterator containingImage()
public void setNonQuorumReadAllowed(boolean allowed)
allowed - True to allow this application to read this database
even if a quorum of images is not available; false to prevent this
application from reading this database when a quorum is not available.
By default, nonquorum reading is disabled for all databases. You must call this method explicitly to permit nonquorum reading for a particular database during a particular transaction. Nonquorum reading is automatically disabled at the end of the transaction in which this method is called.
Warning: If you enable nonquorum reading, your application may read stale data from this database.
isNonQuorumReadAllowed(),
isNonQuorumRead()public boolean isNonQuorumReadAllowed()
setNonQuorumReadAllowed(boolean),
isNonQuorumRead()public void negotiateQuorum(int lockMode)
If this database has any images in previously unavailable partitions, this method adds those images back into the quorum for this database. The reacquired images are resynchronized--that is, they are updated to be consistent with the images in the quorum.
If your application includes a reinitialization procedure that is executed when an autonomous partition that was down is brought back up, that procedure should call this method for every database with an image in the restored autonomous partition.
This method performs no action if any of the following conditions is true:
You may not recalculate a quorum if nonquorum reading has been
enabled for this database
(see setNonQuorumReadAllowed).
To recalculate a quorum in that case, you must end the current
transaction (to disable nonquorum reading) and then call
negotiateQuorum from within a new transaction.
lockMode - The type of lock to obtain for
this database;
one of the following constants defined in the oo interface:
public boolean isNonQuorumRead()
Nonquorum reading of a database is possible only after an
application has called this database's
setNonQuorumReadAllowed
method during the current transaction.
Warning: If this method returns true, your application may be reading stale data from this database.
public void addContainer(ooContObj container,
String name,
long hash,
long initialPages,
long growthFactor)
This method makes the specified container persistent and locks it and this database in write mode.
container - The container to be added to
this database.name - The system name of the container.
A valid system name follows the same rules as for naming files within the operating system.
You can specify an empty string or null to create an unnamed
container.hash - Indicates whether the
container being added should be a hashed container.
If hash = 0, then a nonhashed container is added.
Neither this container or any basic object it contains may be
used as a scope when naming an object.
If hash > 0, then a hashed container is added.
The value of hash is used as a clustering factor
(number of sequentially indexed objects to place into a page)
when you add scope names to this container.
If you do not care about the clustering factor, you should set the
value of hash to 1.initialPages - The initial number of pages
allocated for the container.growthFactor - The percentage by which the
container should grow when needed to accommodate more basic objects.ObjyRuntimeException - If this database already has a container
named name. You can call
hasContainer to test whether
a container with the name name exists in this
database.public boolean hasContainer(String name)
name - The system name of the
container.public ooContObj lookupContainer(String name)
name - The system name of the
container.ObjectNotFoundException - If this database
does not have a container with the specified system name.LockNotGrantedException - If a lock for the
container with the specified system name could not be obtained.public Iterator scan(String className)
className - The package-qualified name
of the class of the desired objects.
public Iterator scan(String className,
String predicate)
If predicate-scan autoflush is enabled for the connection object, this method will flush any modified objects to the federated database before performing the scan. Otherwise, the result of the scan may contain out-of-date information.
className - The package-qualified name
of the class of the desired objects.predicate - The condition that each retrieved object
must satisfy, expressed in the Objectivity/DB
predicate query language.Connection.setPredicateScanAutoFlush(boolean),
Connection.isPredicateScanAutoFlush()
public Iterator scan(String className,
String predicate,
int access)
public Iterator contains()
public Iterator contains(int filter)
filter - Specifies which containers should be
accessed through the iterator. One of the following constants defined in
the oo interface:
public void bind(Object object,
String name)
throws ObjectNameNotUniqueException
Giving an object a root name makes the object persistent. The named object is made persistent immediately; all transient objects reachable from the named object are made persistent on transaction commit.
object - The object being named.name - The root name for the object.
This string must consist of only ASCII characters and must be unique
within the root dictionary of this database.ObjectNameNotUniqueException - If the name already exists in the root
dictionary.unbind(java.lang.String)
public Object lookup(String name)
throws ObjectNameNotFoundException
name - The root name of the object.ObjectNameNotFoundException - If the name doesn't exist in the root
dictionary.public Iterator rootNames()
public void unbind(String name)
throws ObjectNameNotFoundException
name - The root name to be removed.ObjectNameNotFoundException - If the name doesn't exist in the root
dictionary.bind(java.lang.Object, java.lang.String)
public void addIndex(String name,
String className,
String fieldList)
name - The name of the index to be added; must be different from
the names of existing indexes in this database. You can call
hasIndex to test whether an index with the
specified name exists.fieldList - The key fields for the index, separated by commas.
Each key field must be the name of a valid persistent field
of className whose type is one of the Java types
supported by indexes.ObjyRuntimeException - If Objectivity/DB is unable to
create the index.addUniqueIndex(java.lang.String, java.lang.String, java.lang.String),
dropIndex(java.lang.String)
public void addUniqueIndex(String name,
String className,
String fieldList)
The application is responsible for ensuring that every object indexed by a unique index has a unique combination of values in its key fields. If two or more objects have a given combination of key values, the index will contain only the first such object that is encountered when the index is created or updated.
name - The name of the index to be added; must be different from
the names of existing indexes in this database. You can call
hasIndex to test whether an index with the
specified name exists.className - The package-qualified
name of the class whose instances are to be indexed.fieldList - The key fields for the index, separated by commas.
Each key field must be the name of a valid persistent field
of className whose type is one of the Java types
supported by indexes.ObjyRuntimeException - If Objectivity/DB is unable to
create the index.addIndex(java.lang.String, java.lang.String, java.lang.String),
dropIndex(java.lang.String)public void dropIndex(String name)
name - The name of the index to be
dropped.ObjyRuntimeException - If this database does not have an index named
name. You can call
hasIndex to test whether an index with the
specified name exists.addIndex(java.lang.String, java.lang.String, java.lang.String),
addUniqueIndex(java.lang.String, java.lang.String, java.lang.String),
hasIndex(java.lang.String)public boolean hasIndex(String name)
name - The name of the index.addIndex(java.lang.String, java.lang.String, java.lang.String),
addUniqueIndex(java.lang.String, java.lang.String, java.lang.String),
dropIndex(java.lang.String)public void convertObjects()
You can call this method if the definitions of some Java classes are not consistent with the corresponding descriptions in the schema. Certain changes to a class definition affect how instances of a class should be laid out in storage. After you make such a change, existing persistent objects of the changed classes are rendered out-of-date until they are converted to their new representations.
In general, you can allow each affected object to be converted automatically the first time it is accessed after the class description in the schema is changed. Such automatic conversion may distribute the performance impact of conversion across many transactions. Alternatively, you can concentrate the performance impact of conversion into fewer transactions by converting all the affected objects in a container, a database, or the federated database on demand. You call this method in an update transaction to convert the affected objects in this database on demand. This method takes no action if the affected objects in the database have already been converted.
The convertObjects method automatically drops any index that is invalidated by a schema evolution change. Specifically, if you changed the type or deleted a field that is a key field of an index that index is dropped.
If the referenced database is read-only, you must call the
setReadOnly method
to change it back to read-write before you can convert objects in it.
public boolean isReadOnly()
A read-only database can be opened only for read; any attempt to open the database for write (implicitly or explicitly) will fail as if there were a lock conflict.
setReadOnly(boolean)public void setReadOnly(boolean value)
A read-only database can be opened only for read; any attempt to open the database for write (implicitly or explicitly) will fail as if there were a lock conflict. Using a read-only database can improve performance by allowing the application to grant read locks and deny update locks without consulting the lock server.
You can change a read-only database back to read-write only if no application or tool is currently reading either that database or any other read-only database in the same federated database. You must change the database back to read-write before you can perform any other operation on it.
(DRO) If one image of a database is made read-only, all images are automatically made read-only. Similarly, if one image is changed back to read-write, all images are changed back to read-write.
value - True to mark this database as
read-only; false to change the database back to read-write.isReadOnly()public void setPersistor(PooDBObj persistor)
public long connectionId()
|
Objectivity for Java Reference | |||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||
Copyright © 2000 Objectivity, Inc. All rights reserved.