com.db4o.internal

Class ExternalObjectContainer

java.lang.Object

com.db4o.internal.ObjectContainerBase

com.db4o.internal.ExternalObjectContainer

All Implemented Interfaces:

ExtObjectContainer, InternalObjectContainer, ObjectContainerSpec, Internal4, ObjectContainer, TransientClass

Direct Known Subclasses:

LocalObjectContainer

public abstract class ExternalObjectContainer
extends ObjectContainerBase

Field Summary

Fields inherited from class com.db4o.internal.ObjectContainerBase

_blockConverter, _classCollection, _config, _handlers, _lock, _timeStampIdGenerator, _transaction

Constructor Summary

Constructors

Constructor and Description
ExternalObjectContainer(Configuration config)

Method Summary

Methods

Modifier and Type	Method and Description
void	activate(java.lang.Object obj) activates an object with the current activation strategy.
void	activate(java.lang.Object obj, int depth) activates all members on a stored object to the specified depth.
abstract void	backup(Storage targetStorage, 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.
void	commit() commits the running transaction.
void	deactivate(java.lang.Object obj) deactivates an object.
void	deactivate(java.lang.Object obj, int depth) deactivates a stored object by setting all members to NULL.
void	delete(java.lang.Object a_object) deletes a stored object permanently.
java.lang.Object	descend(java.lang.Object obj, java.lang.String[] path) returns a member at the specific path without activating intermediate objects.
ExtObjectContainer	ext() returns an ObjectContainer with extended functionality.
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.
abstract 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	isStored(java.lang.Object obj) tests if an object is stored in this ObjectContainer.
java.lang.Object	peekPersisted(java.lang.Object obj, 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(java.lang.Object obj) unloads a specific object from the db4o reference mechanism.
Query	query() creates a new S.O.D.A.
ObjectSet	query(java.lang.Class clazz) queries for all instances of a class.
ObjectSet	query(Predicate predicate) Native Query Interface.
ObjectSet	query(Predicate predicate, QueryComparator comparator) Native Query Interface.
ObjectSet	queryByExample(java.lang.Object template) Query-By-Example interface to retrieve objects.
void	refresh(java.lang.Object obj, int depth) refreshs all members on a stored object to the specified depth.
void	rollback() rolls back the running transaction.
void	store(java.lang.Object obj) newly stores objects or updates stored objects.
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.

Methods inherited from class com.db4o.internal.ObjectContainerBase

activate, activate, activationContextFor, activationDepthProvider, applyRenames, asTopLevelCall, backup, bind, bind2, blockConverter, blockSize, blockSize, callbacks, callbacks, checkClosed, checkReadOnly, checkStillToSet, checkTransaction, checkTransaction, classCollection, classMetadataForID, classMetadataForName, classMetadataForObject, classMetadataForReflectClass, classMetadataIdForName, classOnlyQuery, close, close2, closeIdSystem, closeSystemTransaction, closeTransaction, closeUserTransaction, commit, commit1, commitTimestampIndex, config, configImpl, configure, container, converterVersion, createBlockConverter, createClassMetadata, createReferenceSystem, createStatefulBuffer, createStringIO, currentVersion, db4oTypeStored, deactivate, deactivate, decryptedBufferByAddress, defaultActivationDepth, defaultToString, delete, delete1, delete2, delete4, deleteByID, detectSchemaChanges, dispatchsEvents, doFinalize, environment, executeQuery, fatalShutdown, fatalStorageShutdown, finalize, flagAsHandled, generateTimeStampId, generateTransactionTimestamp, getActivatedObjectFromCache, getByID, getByID2, getByUUID, getHardObjectReferenceById, getHardReferenceBySignature, getID, getIDsForClass, getNativeQueryHandler, getObjectInfo, handledInCurrentTopLevelCall, handleExceptionOnClose, handlers, hasShutDownHook, idForNewUserObject, initalizeWeakReferenceSupport, initialize1, initializeClassMetadataRepository, initializePostOpenExcludingTransportObjectContainer, initializeTransactions, isCached, isClient, isClosed, isDeleted, isStored, knownClasses, lock, logMsg, maintainsIndices, needsLockFileThread, needsUpdate, newQueryResult, newSystemTransaction, newTransaction, newUserTransaction, newWeakReference, open, openImpl, peekPersisted, peekPersisted, peekReference, produceClassMetadata, purge, purge, query, query, query, query, query, queryAllObjects, queryByExample, raiseCommitTimestamp, rawBufferByAddress, readActivatedObjectNotInCache, readBufferById, readBufferById, readBytes, readBytes, readSlotBuffers, readStatefulBufferById, readStatefulBufferById, readWriterByAddress, referenceSystemRegistry, reflector, refresh, refreshInternal, releaseSemaphore, releaseSemaphore, releaseSemaphores, replaceClassMetadataRepository, replicationCallState, reserve, rollback, rollback1, send, setDirtyInSystemTransaction, setSemaphore, setSemaphore, showInternalClasses, shutdown, shutdownDataStorage, shutdownObjectContainer, stackDepth, stackDepth, stillToActivate, stillToDeactivate, stopSession, store, store, store2, storeAfterReplication, storeAll, storeAll, storeByNewReplication, storedClass, storedClasses, storeInternal, storeInternal, stringIO, syncExec, systemInfo, systemTransaction, threadPool, topLevelCallId, topLevelCallId, toString, transaction, tryGetByID, typeHandlerForClass, typeHandlerForClassMetadataID, updateDepthProvider, useDefaultTransactionTimestamp, uUIDIndex, version, versionIndex, withEnvironment, withTransaction, writeDirtyClassMetadata, writeNew, writeUpdate

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.db4o.internal.InternalObjectContainer

instanceCount, newEventRegistry

Methods inherited from interface com.db4o.ext.ExtObjectContainer

openSession

Constructor Detail

ExternalObjectContainer

public ExternalObjectContainer(Configuration config)

Method Detail

activate

public final void activate(java.lang.Object obj)

Description copied from interface: ExtObjectContainer

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.

activate

public final void activate(java.lang.Object obj,
            int depth)
                    throws DatabaseClosedException

Description copied from interface: ObjectContainer

activates all members on a stored object to the specified depth.

See "Why activation" for an explanation why activation is necessary.

The activate method activates a graph of persistent objects in memory. Only deactivated objects in the graph will be touched: their fields will be loaded from the database. The activate methods starts from a root object and traverses all member objects to the depth specified by the depth parameter. The depth parameter is the distance in "field hops" (object.field.field) away from the root object. The nodes at 'depth' level away from the root (for a depth of 3: object.member.member) will be instantiated but deactivated, their fields will be null. The activation depth of individual classes can be overruled with the methods maximumActivationDepth() and minimumActivationDepth() in the ObjectClass interface.

A successful call to activate triggers Activating and Activated callbacks, which can be used for cascaded activation.

Parameters:

obj - the object to be activated.

depth - the member depth to which activate is to cascade.

Throws:

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

See Also:

Why activation?, Using callbacks

deactivate

public final void deactivate(java.lang.Object obj)

Description copied from interface: ExtObjectContainer

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.

bind

public final void bind(java.lang.Object obj,
        long id)
                throws ArgumentNullException,
                       java.lang.IllegalArgumentException

Description copied from interface: ExtObjectContainer

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:

ArgumentNullException

java.lang.IllegalArgumentException

See Also:

ExtObjectContainer.getID(java.lang.Object)

commit

public final void commit()
                  throws DatabaseReadOnlyException,
                         DatabaseClosedException

Description copied from interface: ObjectContainer

commits the running transaction.

Transactions are back-to-back. A call to commit will starts a new transaction immedidately.

Throws:

DatabaseReadOnlyException - database was configured as read-only.

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

deactivate

public final void deactivate(java.lang.Object obj,
              int depth)
                      throws DatabaseClosedException

Description copied from interface: ObjectContainer

deactivates a stored object by setting all members to NULL.
Primitive types will be set to their default values. Calls to this method save memory. The method has no effect, if the passed object is not stored in the ObjectContainer.

deactivate() triggers Deactivating and Deactivated callbacks.

Be aware that calling this method with a depth parameter greater than 1 sets members on member objects to null. This may have side effects in other places of the application.

Parameters:

obj - the object to be deactivated.

depth - the member depth to which deactivate is to cascade.

Throws:

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

See Also:

Using callbacks, Why activation?

delete

public final void delete(java.lang.Object a_object)

Description copied from interface: ObjectContainer

deletes a stored object permanently.

Note that this method has to be called for every single object individually. Delete does not recurse to object members. Simple and array member types are destroyed.

Object members of the passed object remain untouched, unless cascaded deletes are configured for the class or for one of the member fields.

The method has no effect, if the passed object is not stored in the ObjectContainer.

A subsequent call to set() with the same object newly stores the object to the ObjectContainer.

delete() triggers Deleting and Deleted callbacks, which can be also used for cascaded deletes.

Parameters:

a_object - the object to be deleted from the ObjectContainer.

See Also:

ObjectClass.cascadeOnDelete(boolean), ObjectField.cascadeOnDelete(boolean), Using callbacks

descend

public java.lang.Object descend(java.lang.Object obj,
                       java.lang.String[] path)

Description copied from interface: ExtObjectContainer

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

ext

public ExtObjectContainer ext()

Description copied from interface: ObjectContainer

returns an ObjectContainer with extended functionality.

Every ObjectContainer that db4o provides can be casted to an ExtObjectContainer. This method is supplied for your convenience to work without a cast.

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

Returns:

this, casted to ExtObjectContainer

queryByExample

public final ObjectSet queryByExample(java.lang.Object template)
                               throws DatabaseClosedException

Description copied from interface: ObjectContainer

Query-By-Example interface to retrieve objects.

queryByExample() creates an ObjectSet containing all objects in the ObjectContainer that match the passed template object.

Calling queryByExample(NULL) returns all objects stored in the ObjectContainer.


Query Evaluation
All non-null members of the template object are compared against all stored objects of the same class. Primitive type members are ignored if they are 0 or false respectively.

Arrays and all supported Collection classes are evaluated for containment. Differences in length/size() are ignored.

Consult the documentation of the Configuration package to configure class-specific behaviour.


Returned Objects
The objects returned in the ObjectSet are instantiated and activated to the preconfigured depth of 5. The activation depth may be configured globally or individually for classes.

db4o keeps track of all instantiatied objects. Queries will return references to these objects instead of instantiating them a second time.

Objects newly activated by queryByExample() can respond to the Activating callback method.

Parameters:

template - object to be used as an example to find all matching objects.

Returns:

ObjectSet containing all found objects.

Throws:

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

See Also:

Why activation?, Using callbacks

getByID

public final java.lang.Object getByID(long id)
                               throws DatabaseClosedException,
                                      InvalidIDException

Description copied from interface: ExtObjectContainer

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

public final java.lang.Object getByUUID(Db4oUUID uuid)

Description copied from interface: ExtObjectContainer

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 ExtObjectContainer.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 final long getID(java.lang.Object obj)

Description copied from interface: ExtObjectContainer

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 ExtObjectContainer.getObjectInfo(Object), ObjectInfo.getUUID() and ExtObjectContainer.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

public final ObjectInfo getObjectInfo(java.lang.Object obj)

Description copied from interface: ExtObjectContainer

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

isActive

public boolean isActive(java.lang.Object obj)

Description copied from interface: ExtObjectContainer

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

public boolean isCached(long id)

Description copied from interface: ExtObjectContainer

tests if an object with this ID is currently cached.

Parameters:

id - the internal ID

isStored

public boolean isStored(java.lang.Object obj)

Description copied from interface: ExtObjectContainer

tests if an object is stored in this ObjectContainer.

Parameters:

obj - to be tested

Returns:

true if the passed object is stored.

peekPersisted

public final java.lang.Object peekPersisted(java.lang.Object obj,
                             int depth,
                             boolean committed)
                                     throws DatabaseClosedException

Description copied from interface: ExtObjectContainer

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:

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

Throws:

DatabaseClosedException

purge

public final void purge(java.lang.Object obj)

Description copied from interface: ExtObjectContainer

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.

query

public Query query()

Description copied from interface: ObjectContainer

creates a new S.O.D.A. Query.

Use ObjectContainer.queryByExample(Object) for simple Query-By-Example.

Native queries are the recommended main db4o query interface.

Returns:

a new Query object

query

public final ObjectSet query(java.lang.Class clazz)

Description copied from interface: ObjectContainer

queries for all instances of a class.

Parameters:

clazz - the class to query for.

Returns:

the ObjectSet returned by the query.

query

public final ObjectSet query(Predicate predicate)

Description copied from interface: ObjectContainer

Native Query Interface.

Native Queries allow typesafe, compile-time checked and refactorable querying, following object-oriented principles. Native Queries expressions are written as if one or more lines of code would be run against all instances of a class. A Native Query expression should return true to mark specific instances as part of the result set. db4o will attempt to optimize native query expressions and execute them against indexes and without instantiating actual objects, where this is possible.

The syntax of the enclosing object for the native query expression varies, depending on the language version used. Here are some examples:

// Java JDK 5
List <Cat> cats = db.query(new Predicate<Cat>() {
public boolean match(Cat cat) {
return cat.getName().equals("Occam");
}
});


// Java JDK 1.2 to 1.4
List cats = db.query(new Predicate() {
public boolean match(Cat cat) {
return cat.getName().equals("Occam");
}
});


// Java JDK 1.1
ObjectSet cats = db.query(new CatOccam());

public static class CatOccam extends Predicate {
public boolean match(Cat cat) {
return cat.getName().equals("Occam");
}
});

Summing up the above:
In order to run a Native Query, you can extend the Predicate class for all other language dialects

A class that extends Predicate is required to implement the #match() method, following the native query conventions:
- The name of the method is "#match()".
- The method must be public.
- The method returns a boolean.
- The method takes one parameter.
- The Class (Java) of the parameter specifies the extent.
- For all instances of the extent that are to be included into the resultset of the query, the match method should return true. For all instances that are not to be included, the match method should return false.

Parameters:

predicate - the Predicate containing the native query expression.

Returns:

the ObjectSet returned by the query.

query

public final ObjectSet query(Predicate predicate,
              QueryComparator comparator)

Description copied from interface: ObjectContainer

Native Query Interface. Queries as with ObjectContainer.query(com.db4o.query.Predicate), but will sort the resulting ObjectSet according to the given QueryComparator.

Parameters:

predicate - the Predicate containing the native query expression.

comparator - the QueryComparator specifying the sort order of the result

Returns:

the ObjectSet returned by the query.

refresh

public final void refresh(java.lang.Object obj,
           int depth)

Description copied from interface: ExtObjectContainer

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.

rollback

public final void rollback()

Description copied from interface: ObjectContainer

rolls back the running transaction.

Modified application objects im memory are not restored. Use combined calls to deactivate() and activate() to reload an objects member values.

store

public final void store(java.lang.Object obj)
                 throws DatabaseClosedException,
                        DatabaseReadOnlyException

Description copied from interface: ObjectContainer

newly stores objects or updates stored objects.

An object not yet stored in the ObjectContainer will be stored when it is passed to store(). An object already stored in the ObjectContainer will be updated.

Updates
- will affect all simple type object members.
- links to object members that are already stored will be updated.
- new object members will be newly stored. The algorithm traverses down new members, as long as further new members are found.
- object members that are already stored will not be updated themselves.
Every object member needs to be updated individually with a call to store() unless a deep global or class-specific update depth was configured or cascaded updates were defined in the class or in one of the member fields. Depending if the passed object is newly stored or updated, Creating/Created or Updating/Updated callback method is triggered. Callbacks might also be used for cascaded updates.

Parameters:

obj - the object to be stored or updated.

Throws:

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

DatabaseReadOnlyException - database was configured as read-only.

See Also:

ExtObjectContainer#set(object, depth), Configuration.updateDepth(int), ObjectClass.updateDepth(int), ObjectClass.cascadeOnUpdate(boolean), ObjectField.cascadeOnUpdate(boolean), Using callbacks

store

public final void store(java.lang.Object obj,
         int depth)
                 throws DatabaseClosedException,
                        DatabaseReadOnlyException

Description copied from interface: ExtObjectContainer

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

Throws:

DatabaseClosedException

DatabaseReadOnlyException

See Also:

com.db4o.ObjectContainer#set

storedClass

public final StoredClass storedClass(java.lang.Object clazz)

Description copied from interface: ExtObjectContainer

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

public StoredClass[] storedClasses()

Description copied from interface: ExtObjectContainer

returns an array of all StoredClass meta information objects.

backup

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

Description copied from interface: ExtObjectContainer

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:

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

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

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

identity

public abstract Db4oDatabase identity()

Description copied from interface: ExtObjectContainer

returns the Db4oDatabase object for this ObjectContainer.

Returns:

the Db4oDatabase identity object for this ObjectContainer.