db4o 6.1

com.db4o.ext
Interface ExtObjectContainer

All Superinterfaces:
ObjectContainer
All Known Subinterfaces:
ExtClient

public interface ExtObjectContainer
extends ObjectContainer

extended functionality for the ObjectContainer interface.

Every db4o ObjectContainer always is an ExtObjectContainer so a cast is possible.

ObjectContainer.ext() is a convenient method to perform the cast.

The ObjectContainer functionality is split to two interfaces to allow newcomers to focus on the essential methods.


Method Summary
 void backup(java.lang.String path)
          backs up a database file of an open ObjectContainer.
 void bind(java.lang.Object obj, long id)
          binds an object to an internal object ID.
 Db4oCollections collections()
          returns the Db4oCollections interface to create or modify database-aware collections for this ObjectContainer.

 Configuration configure()
          returns the Configuration context for this ObjectContainer.
 java.lang.Object descend(java.lang.Object obj, java.lang.String[] path)
          returns a member at the specific path without activating intermediate objects.
<T> T
getByID(long ID)
          returns the stored object for an internal ID.
<T> T
getByUUID(Db4oUUID uuid)
          returns a stored object for a Db4oUUID.
 long getID(java.lang.Object obj)
          returns the internal unique object ID.
 ObjectInfo getObjectInfo(java.lang.Object obj)
          returns the ObjectInfo for a stored object.
 Db4oDatabase identity()
          returns the Db4oDatabase object for this ObjectContainer.
 boolean isActive(java.lang.Object obj)
          tests if an object is activated.
 boolean isCached(long ID)
          tests if an object with this ID is currently cached.
 boolean isClosed()
          tests if this ObjectContainer is closed.
 boolean isStored(java.lang.Object obj)
          tests if an object is stored in this ObjectContainer.
 ReflectClass[] knownClasses()
          returns all class representations that are known to this ObjectContainer because they have been used or stored.
 java.lang.Object lock()
          returns the main synchronisation lock.
 void migrateFrom(ObjectContainer objectContainer)
          aids migration of objects between ObjectContainers.
<T> T
peekPersisted(T object, int depth, boolean committed)
          returns a transient copy of a persistent object with all members set to the values that are currently stored to the database.
 void purge()
          unloads all clean indices from memory and frees unused objects.
 void purge(java.lang.Object obj)
          unloads a specific object from the db4o reference mechanism.
 GenericReflector reflector()
          Return the reflector currently being used by db4objects.
 void refresh(java.lang.Object obj, int depth)
          refreshs all members on a stored object to the specified depth.
 void releaseSemaphore(java.lang.String name)
          releases a semaphore, if the calling transaction is the owner.
 ReplicationProcess replicationBegin(ObjectContainer peerB, ReplicationConflictHandler conflictHandler)
          prepares for replication with another ObjectContainer.
 void set(java.lang.Object obj, int depth)
          deep update interface to store or update objects.
 boolean setSemaphore(java.lang.String name, int waitForAvailability)
          attempts to set a semaphore.
 StoredClass storedClass(java.lang.Object clazz)
          returns a StoredClass meta information object.
 StoredClass[] storedClasses()
          returns an array of all StoredClass meta information objects.
 SystemInfo systemInfo()
          returns the SystemInfo for this ObjectContainer.
 long version()
          returns the current transaction serial number.
 
Methods inherited from interface com.db4o.ObjectContainer
activate, close, commit, deactivate, delete, ext, get, query, query, query, query, query, rollback, set
 

Method Detail

backup

void backup(java.lang.String path)
            throws java.io.IOException
backs up a database file of an open ObjectContainer.

While the backup is running, the ObjectContainer can continue to be used. Changes that are made while the backup is in progress, will be applied to the open ObjectContainer and to the backup.

While the backup is running, the ObjectContainer should not be closed.

If a file already exists at the specified path, it will be overwritten.

Parameters:
path - a fully qualified path
Throws:
java.io.IOException

bind

void bind(java.lang.Object obj,
          long id)
binds an object to an internal object ID.

This method uses the ID parameter to load the correspondig stored object into memory and replaces this memory reference with the object parameter. The method may be used to replace objects or to reassociate an object with it's stored instance after closing and opening a database file. A subsequent call to set(Object) is necessary to update the stored object.

Requirements:
- The ID needs to be a valid internal object ID, previously retrieved with getID(Object).
- The object parameter needs to be of the same class as the stored object.

Parameters:
obj - the object that is to be bound
id - the internal id the object is to be bound to
See Also:
getID(java.lang.Object)

collections

Db4oCollections collections()
returns the Db4oCollections interface to create or modify database-aware collections for this ObjectContainer.

Returns:
the Db4oCollections interface for this ObjectContainer.

configure

Configuration configure()
returns the Configuration context for this ObjectContainer.

Upon opening an ObjectContainer with any of the factory methods in the Db4o class, the global Configuration context is copied into the ObjectContainer. The Configuration can be modified individually for each ObjectContainer without any effects on the global settings.

Returns:
Configuration the Configuration context for this ObjectContainer
See Also:
Db4o.configure()

descend

java.lang.Object descend(java.lang.Object obj,
                         java.lang.String[] path)
returns a member at the specific path without activating intermediate objects.

This method allows navigating from a persistent object to it's members in a performant way without activating or instantiating intermediate objects.

Parameters:
obj - the parent object that is to be used as the starting point.
path - an array of field names to navigate by
Returns:
the object at the specified path or null if no object is found

getByID

<T> T getByID(long ID)
returns the stored object for an internal ID.

This is the fastest method for direct access to objects. Internal IDs can be obtained with getID(Object). Objects will not be activated by this method. They will be returned in the activation state they are currently in, in the local cache.

Parameters:
ID - the internal ID
Returns:
the object associated with the passed ID or null, if no object is associated with this ID in this ObjectContainer.
See Also:
Why activation?

getByUUID

<T> T getByUUID(Db4oUUID uuid)
returns a stored object for a Db4oUUID.

This method is intended for replication and for long-term external references to objects. To get a Db4oUUID for an object use getObjectInfo(Object) and ObjectInfo.getUUID().

Objects will not be activated by this method. They will be returned in the activation state they are currently in, in the local cache.

Parameters:
uuid - the UUID
Returns:
the object for the UUID
See Also:
Why activation?

getID

long getID(java.lang.Object obj)
returns the internal unique object ID.

db4o assigns an internal ID to every object that is stored. IDs are guaranteed to be unique within one ObjectContainer. An object carries the same ID in every db4o session. Internal IDs can be used to look up objects with the very fast getByID method.

Internal IDs will change when a database is defragmented. Use getObjectInfo(Object), ObjectInfo.getUUID() and getByUUID(Db4oUUID) for long-term external references to objects.

Parameters:
obj - any object
Returns:
the associated internal ID or 0, if the passed object is not stored in this ObjectContainer.

getObjectInfo

ObjectInfo getObjectInfo(java.lang.Object obj)
returns the ObjectInfo for a stored object.

This method will return null, if the passed object is not stored to this ObjectContainer.

Parameters:
obj - the stored object
Returns:
the ObjectInfo

identity

Db4oDatabase identity()
returns the Db4oDatabase object for this ObjectContainer.

Returns:

isActive

boolean isActive(java.lang.Object obj)
tests if an object is activated.

isActive returns false if an object is not stored within the ObjectContainer.

Parameters:
obj - to be tested

Returns:
true if the passed object is active.

isCached

boolean isCached(long ID)
tests if an object with this ID is currently cached.

Parameters:
ID - the internal ID

isClosed

boolean isClosed()
tests if this ObjectContainer is closed.

Returns:
true if this ObjectContainer is closed.

isStored

boolean isStored(java.lang.Object obj)
tests if an object is stored in this ObjectContainer.

Parameters:
obj - to be tested

Returns:
true if the passed object is stored.

knownClasses

ReflectClass[] knownClasses()
returns all class representations that are known to this ObjectContainer because they have been used or stored.

Returns:
all class representations that are known to this ObjectContainer because they have been used or stored.

lock

java.lang.Object lock()
returns the main synchronisation lock.

Synchronize over this object to ensure exclusive access to the ObjectContainer.

Handle the use of this functionality with extreme care, since deadlocks can be produced with just two lines of code.

Returns:
Object the ObjectContainer lock object

migrateFrom

void migrateFrom(ObjectContainer objectContainer)
aids migration of objects between ObjectContainers.

When objects are migrated from one ObjectContainer to another, it is desirable to preserve virtual object attributes such as the object version number or the UUID. Use this method to signal to an ObjectContainer that it should read existing version numbers and UUIDs from another ObjectContainer. This method should also be used during the Defragment operation. It is included in the default implementation supplied in Defragment.java/Defragment.cs.

Parameters:
objectContainer - the ObjectContainer objects are to be migrated from or null to denote that migration is completed.

peekPersisted

<T> T peekPersisted(T object,
                    int depth,
                    boolean committed)
returns a transient copy of a persistent object with all members set to the values that are currently stored to the database.

The returned objects have no connection to the database.

With the committed parameter it is possible to specify, whether the desired object should contain the committed values or the values that were set by the running transaction with ObjectContainer.set(java.lang.Object).

A possible usecase for this feature:
An application might want to check all changes applied to an object by the running transaction.

Parameters:
object - the object that is to be cloned
depth - the member depth to which the object is to be instantiated
committed - whether committed or set values are to be returned
Returns:
the object

purge

void purge()
unloads all clean indices from memory and frees unused objects.

Call commit() and purge() consecutively to achieve the best result possible. This method can have a negative impact on performance since indices will have to be reread before further inserts, updates or queries can take place.


purge

void purge(java.lang.Object obj)
unloads a specific object from the db4o reference mechanism.

db4o keeps references to all newly stored and instantiated objects in memory, to be able to manage object identities.

With calls to this method it is possible to remove an object from the reference mechanism, to allow it to be garbage collected. You are not required to call this method in the .NET and JDK 1.2 versions, since objects are referred to by weak references and garbage collection happens automatically.

An object removed with purge(Object) is not "known" to the ObjectContainer afterwards, so this method may also be used to create multiple copies of objects.

purge(Object) has no influence on the persistence state of objects. "Purged" objects can be reretrieved with queries.

Parameters:
obj - the object to be removed from the reference mechanism.

reflector

GenericReflector reflector()
Return the reflector currently being used by db4objects.

Returns:
the current Reflector.

refresh

void refresh(java.lang.Object obj,
             int depth)
refreshs all members on a stored object to the specified depth.

If a member object is not activated, it will be activated by this method.

The isolation used is READ COMMITTED. This method will read all objects and values that have been committed by other transactions.

Parameters:
obj - the object to be refreshed.
depth - the member depth to which refresh is to cascade.

releaseSemaphore

void releaseSemaphore(java.lang.String name)
releases a semaphore, if the calling transaction is the owner.

Parameters:
name - the name of the semaphore to be released.

replicationBegin

ReplicationProcess replicationBegin(ObjectContainer peerB,
                                    ReplicationConflictHandler conflictHandler)
prepares for replication with another ObjectContainer.

An ObjectContainer can only be involved in a replication process with one other ObjectContainer at the same time.

The returned ReplicationProcess interface provides methods to commit and to cancel the replication process.

This ObjectContainer will be "peerA" for the returned ReplicationProcess. The other ObjectContainer will be "peerB".

Parameters:
peerB - the ObjectContainer to replicate with.
conflictHandler - the conflict handler for this ReplicationProcess. Conflicts occur whenever ReplicationProcess.replicate(Object) is called with an object that was modified in both ObjectContainers since the last replication run between the two. Upon a conflict the ReplicationConflictHandler.resolveConflict(ReplicationProcess, Object, Object) method will be called in the conflict handler.
Returns:
the ReplicationProcess interface for this replication process.

set

void set(java.lang.Object obj,
         int depth)
deep update interface to store or update objects.

In addition to the normal storage interface, ObjectContainer#set(Object), this method allows a manual specification of the depth, the passed object is to be updated.

Parameters:
obj - the object to be stored or updated.
depth - the depth to which the object is to be updated
See Also:
ObjectContainer.set(java.lang.Object)

setSemaphore

boolean setSemaphore(java.lang.String name,
                     int waitForAvailability)
attempts to set a semaphore.

Semaphores are transient multi-purpose named flags for ObjectContainers.

A transaction that successfully sets a semaphore becomes the owner of the semaphore. Semaphores can only be owned by a single transaction at one point in time.

This method returns true, if the transaction already owned the semaphore before the method call or if it successfully acquires ownership of the semaphore.

The waitForAvailability parameter allows to specify a time in milliseconds to wait for other transactions to release the semaphore, in case the semaphore is already owned by another transaction.

Semaphores are released by the first occurence of one of the following:
- the transaction releases the semaphore with releaseSemaphore(java.lang.String)
- the transaction is closed with ObjectContainer.close()
- C/S only: the corresponding ObjectServer is closed.
- C/S only: the client ObjectContainer looses the connection and is timed out.

Semaphores are set immediately. They are independant of calling ObjectContainer.commit() or ObjectContainer.rollback().

Possible usecases for semaphores:
- prevent other clients from inserting a singleton at the same time. A suggested name for the semaphore: "SINGLETON_" + Object#getClass().getName().
- lock objects. A suggested name: "LOCK_" + getID(Object)
- generate a unique client ID. A suggested name: "CLIENT_" + System.currentTimeMillis().

Parameters:
name - the name of the semaphore to be set
waitForAvailability - the time in milliseconds to wait for other transactions to release the semaphore. The parameter may be zero, if the method is to return immediately.
Returns:
boolean flag
true, if the semaphore could be set or if the calling transaction already owned the semaphore.
false, if the semaphore is owned by another transaction.

storedClass

StoredClass storedClass(java.lang.Object clazz)
returns a StoredClass meta information object.

There are three options how to use this method.
Any of the following parameters are possible:
- a fully qualified classname.
- a Class object.
- any object to be used as a template.

Parameters:
clazz - class name, Class object, or example object.

Returns:
an instance of an StoredClass meta information object.

storedClasses

StoredClass[] storedClasses()
returns an array of all StoredClass meta information objects.


systemInfo

SystemInfo systemInfo()
returns the SystemInfo for this ObjectContainer.

The SystemInfo supplies methods that provide information about system state and system settings of this ObjectContainer.

Returns:
the SystemInfo for this ObjectContainer.

version

long version()
returns the current transaction serial number.

This serial number can be used to query for modified objects and for replication purposes.

Returns:
the current transaction serial number.

db4o 6.1