db4o 4.0

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 getByID(long ID)
          returns the stored object for an internal ID.
 java.lang.Object 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.
 java.lang.Object lock()
          returns the main synchronisation lock.
 void migrateFrom(ObjectContainer objectContainer)
          aids migration of objects between ObjectContainers.
 java.lang.Object peekPersisted(java.lang.Object 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.
 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.
 Db4oReplication replicateTo(ObjectContainer destination)
          starts replication to 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.
 
Methods inherited from interface com.db4o.ObjectContainer
activate, close, commit, deactivate, delete, ext, get, query, rollback, set
 

Method Detail

backup

public 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

public 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:
id - the internal id the object is to be bound to
See Also:
getID(Object)

collections

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

Returns:
the Db4oCollections interface for this ObjectContainer.

configure

public 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()

getByID

public java.lang.Object 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

public java.lang.Object 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

public 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.

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

getObjectInfo

public 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

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

Returns:

isActive

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

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

Returns:
true if the passed object is active.

isCached

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

Parameters:
ID - the internal ID

isClosed

public boolean isClosed()
tests if this ObjectContainer is closed.

Returns:
true if this ObjectContainer is closed.

isStored

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

Returns:
true if the passed object is stored.

lock

public 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

public 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

public java.lang.Object peekPersisted(java.lang.Object 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

public 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

public 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.


refresh

public 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:
depth - the member depth to which refresh is to cascade.

releaseSemaphore

public 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.

replicateTo

public Db4oReplication replicateTo(ObjectContainer destination)
starts replication to another ObjectContainer.

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

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

It also allows to register a conflicthandler, in case objects have been modified in both ObjectContainers, since the two ObjectContainers were last replicated with eachother.

Parameters:
destination - the ObjectContainer to replicate to.
Returns:
the Db4oReplication interface for this replication process.

set

public 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.

See Also:

ObjectContainer#set(Object)

setSemaphore

public 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

public 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.

Returns:
an instance of an StoredClass meta information object.

storedClasses

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


db4o 4.0