com.db4o.ext

Interface ExtObjectContainer

All Superinterfaces:

ObjectContainer

All Known Subinterfaces:

ExtClient, InternalObjectContainer, ObjectContainerSpec

All Known Implementing Classes:

ExternalObjectContainer, IoAdaptedObjectContainer, LocalObjectContainer, ObjectContainerBase, ObjectContainerSession, TransportObjectContainer

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

Methods

Modifier and Type	Method and Description
void	activate(java.lang.Object obj) activates an object with the current activation strategy.
void	backup(Storage targetStorage, java.lang.String path) backs up a database file of an open ObjectContainer.
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.
Configuration	configure() returns the Configuration context for this ObjectContainer.
void	deactivate(java.lang.Object obj) deactivates an object.
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 synchronization lock.
ObjectContainer	openSession() opens a new ObjectContainer on top of this ObjectContainer.
<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.
boolean	setSemaphore(java.lang.String name, int waitForAvailability) attempts to set a semaphore.
void	store(java.lang.Object obj, int depth) deep update interface to store or update objects.
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, query, query, query, query, query, queryByExample, rollback, store

Method Detail

activate

void activate(java.lang.Object obj)
              throws Db4oIOException,
                     DatabaseClosedException

activates an object with the current activation strategy. In regular activation mode the object will be activated to the global activation depth, ( see Configuration.activationDepth() ) and all configured settings for ObjectClass.maximumActivationDepth(int) and ObjectClass.maximumActivationDepth(int) will be respected.

In Transparent Activation Mode ( see TransparentActivationSupport ) the parameter object will only be activated, if it does not implement Activatable. All referenced members that do not implement Activatable will also be activated. Any Activatable objects along the referenced graph will break cascading activation.

Throws:

Db4oIOException

DatabaseClosedException

deactivate

void deactivate(java.lang.Object obj)

deactivates an object. Only the passed object will be deactivated, i.e, no object referenced by this object will be deactivated.

Parameters:

obj - the object to be deactivated.

backup

void backup(java.lang.String path)
            throws Db4oIOException,
                   DatabaseClosedException,
                   NotSupportedException

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.

The Storage used for backup is the one configured for this container.

Parameters:

path - a fully qualified path

Throws:

DatabaseClosedException - db4o database file was closed or failed to open.

NotSupportedException - is thrown when the operation is not supported in current configuration/environment

Db4oIOException - I/O operation failed or was unexpectedly interrupted.

backup

void backup(Storage targetStorage,
          java.lang.String path)
            throws Db4oIOException,
                   DatabaseClosedException,
                   NotSupportedException

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.

This method is intended for cross-storage backups, i.e. backup from an in-memory database to a file.

Parameters:

targetStorage - the Storage to be used for backup

path - a fully qualified path

Throws:

DatabaseClosedException - db4o database file was closed or failed to open.

NotSupportedException - is thrown when the operation is not supported in current configuration/environment

Db4oIOException - I/O operation failed or was unexpectedly interrupted.

bind

void bind(java.lang.Object obj,
        long id)
          throws InvalidIDException,
                 DatabaseClosedException

binds an object to an internal object ID.

This method uses the ID parameter to load the corresponding 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

Throws:

DatabaseClosedException - db4o database file was closed or failed to open.

InvalidIDException - when the provided id is outside the scope of the database IDs.

See Also:

getID(java.lang.Object)

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)
          throws DatabaseClosedException,
                 InvalidIDException

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.

Passing invalid id values to this method may result in all kinds of exceptions being thrown. OutOfMemoryError and arithmetic exceptions may occur. If an application is known to use invalid IDs, it is recommended to call this method within a catch-all block.

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.

Throws:

DatabaseClosedException - db4o database file was closed or failed to open.

InvalidIDException - when the provided id is outside the scope of the file length.

See Also:

Why activation?

getByUUID

<T> T getByUUID(Db4oUUID uuid)
            throws DatabaseClosedException,
                   Db4oIOException

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

Throws:

Db4oIOException - I/O operation failed or was unexpectedly interrupted.

DatabaseClosedException - db4o database file was closed or failed to open.

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:

the Db4oDatabase identity object for this ObjectContainer.

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)
                 throws DatabaseClosedException

tests if an object is stored in this ObjectContainer.

Parameters:

obj - to be tested

Returns:

true if the passed object is stored.

Throws:

DatabaseClosedException - db4o database file was closed or failed to open.

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 synchronization 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

openSession

ObjectContainer openSession()

opens a new ObjectContainer on top of this ObjectContainer. The ObjectContainer will have it's own transaction and it's own reference system.

Returns:

the new ObjectContainer session.

Since:

8.0

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.store(java.lang.Object).

A possible use case 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.

store

void store(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:

com.db4o.ObjectContainer#set

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 occurrence 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 use cases 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 class name.
- 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.