com.db4o.internal

Class ObjectContainerSession

java.lang.Object

com.db4o.internal.ObjectContainerSession

All Implemented Interfaces:

ExtObjectContainer, InternalObjectContainer, ObjectContainerSpec, ObjectContainer, TransientClass

public class ObjectContainerSession
extends java.lang.Object
implements InternalObjectContainer, TransientClass, ObjectContainerSpec

Field Summary

Fields

Modifier and Type	Field and Description
protected ObjectContainerBase	_server
protected Transaction	_transaction

Constructor Summary

Constructors

Constructor and Description
ObjectContainerSession(ObjectContainerBase server)
ObjectContainerSession(ObjectContainerBase server, Transaction trans)

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.
void	backup(Storage storage, 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.
Callbacks	callbacks()
void	callbacks(Callbacks cb)
ClassMetadata	classMetadataForID(int id)
ClassMetadata	classMetadataForName(java.lang.String name)
ClassMetadata	classMetadataForReflectClass(ReflectClass reflectClass)
boolean	close() closes the ObjectContainer.
void	commit() commits the running transaction.
Config4Impl	configImpl()
Configuration	configure() returns the Configuration context for this ObjectContainer.
ObjectContainerBase	container()
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 obj) 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.
<T> QLin<T>	from(java.lang.Class<T> clazz)
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.
NativeQueryHandler	getNativeQueryHandler()
ObjectInfo	getObjectInfo(java.lang.Object obj) returns the ObjectInfo for a stored object.
HandlerRegistry	handlers()
Db4oDatabase	identity() returns the Db4oDatabase object for this ObjectContainer.
int	instanceCount(ClassMetadata clazz, Transaction trans)
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	isClient()
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.
EventRegistryImpl	newEventRegistry()
ObjectContainer	openSession() opens a new ObjectContainer on top of this ObjectContainer.
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.
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.
<T> ObjectSet<T>	query(Predicate<T> predicate, QueryComparator<T> comparator) Native Query Interface.
ObjectSet	query(Predicate predicate, java.util.Comparator comparator) Native Query Interface.
ObjectSet	queryByExample(java.lang.Object template) Query-By-Example interface to retrieve objects.
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.
void	rollback() rolls back the running transaction.
boolean	setSemaphore(java.lang.String name, int waitForAvailability) attempts to set a semaphore.
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.
void	storeAll(Transaction transaction, Iterator4 objects)
StoredClass	storedClass(java.lang.Object clazz) returns a StoredClass meta information object.
StoredClass[]	storedClasses() returns an array of all StoredClass meta information objects.
java.lang.Object	syncExec(Closure4 block)
SystemInfo	systemInfo() returns the SystemInfo for this ObjectContainer.
Transaction	transaction()
UpdateDepthProvider	updateDepthProvider()
long	version() returns the current transaction serial number.

Methods inherited from class java.lang.Object

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

Field Detail

_server

protected final ObjectContainerBase _server

_transaction

protected final Transaction _transaction

Constructor Detail

ObjectContainerSession

public ObjectContainerSession(ObjectContainerBase server,
                      Transaction trans)

ObjectContainerSession

public ObjectContainerSession(ObjectContainerBase server)

Method Detail

backup

public void backup(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.

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

Specified by:

backup in interface ExtObjectContainer

Parameters:

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

backup

public void backup(Storage storage,
          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.

Specified by:

backup in interface ExtObjectContainer

Parameters:

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

bind

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

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.

Specified by:

bind in interface ExtObjectContainer

Parameters:

obj - the object that is to be bound

id - the internal id the object is to be bound to

Throws:

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

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

See Also:

ExtObjectContainer.getID(java.lang.Object)

configImpl

public Config4Impl configImpl()

Specified by:

configImpl in interface InternalObjectContainer

configure

public Configuration configure()

Description copied from interface: ExtObjectContainer

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.

Specified by:

configure in interface ExtObjectContainer

Returns:

Configuration the Configuration context for this ObjectContainer

See Also:

Db4o.configure()

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.

Specified by:

descend in interface ExtObjectContainer

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

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

Specified by:

getByID in interface ExtObjectContainer

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 java.lang.Object getByUUID(Db4oUUID uuid)
                           throws DatabaseClosedException,
                                  Db4oIOException

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.

Specified by:

getByUUID in interface ExtObjectContainer

Parameters:

uuid - the UUID

Returns:

the object for the UUID

Throws:

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

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

See Also:

Why activation?

getID

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

Specified by:

getID in interface ExtObjectContainer

Parameters:

obj - any object

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)

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.

Specified by:

getObjectInfo in interface ExtObjectContainer

Parameters:

obj - the stored object

Returns:

the ObjectInfo

identity

public Db4oDatabase identity()

Description copied from interface: ExtObjectContainer

returns the Db4oDatabase object for this ObjectContainer.

Specified by:

identity in interface ExtObjectContainer

Returns:

the Db4oDatabase identity object for this ObjectContainer.

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.

Specified by:

isActive in interface ExtObjectContainer

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.

Specified by:

isCached in interface ExtObjectContainer

Parameters:

id - the internal ID

isClosed

public boolean isClosed()

Description copied from interface: ExtObjectContainer

tests if this ObjectContainer is closed.

Specified by:

isClosed in interface ExtObjectContainer

Returns:

true if this ObjectContainer is closed.

isStored

public boolean isStored(java.lang.Object obj)
                 throws DatabaseClosedException

Description copied from interface: ExtObjectContainer

tests if an object is stored in this ObjectContainer.

Specified by:

isStored in interface ExtObjectContainer

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

public ReflectClass[] knownClasses()

Description copied from interface: ExtObjectContainer

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

Specified by:

knownClasses in interface ExtObjectContainer

Returns:

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

lock

public java.lang.Object lock()

Description copied from interface: ExtObjectContainer

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.

Specified by:

lock in interface ExtObjectContainer

Returns:

Object the ObjectContainer lock object

peekPersisted

public java.lang.Object peekPersisted(java.lang.Object object,
                             int depth,
                             boolean committed)

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.

Specified by:

peekPersisted in interface ExtObjectContainer

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

Description copied from interface: ExtObjectContainer

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.

Specified by:

purge in interface ExtObjectContainer

purge

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

Specified by:

purge in interface ExtObjectContainer

Parameters:

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

reflector

public GenericReflector reflector()

Description copied from interface: ExtObjectContainer

Return the reflector currently being used by db4objects.

Specified by:

reflector in interface ExtObjectContainer

Returns:

the current Reflector.

refresh

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

Specified by:

refresh in interface ExtObjectContainer

Parameters:

obj - the object to be refreshed.

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

releaseSemaphore

public void releaseSemaphore(java.lang.String name)

Description copied from interface: ExtObjectContainer

releases a semaphore, if the calling transaction is the owner.

Specified by:

releaseSemaphore in interface ExtObjectContainer

Parameters:

name - the name of the semaphore to be released.

store

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

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.

Specified by:

store in interface ExtObjectContainer

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

public boolean setSemaphore(java.lang.String name,
                   int waitForAvailability)

Description copied from interface: ExtObjectContainer

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 ExtObjectContainer.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().

Specified by:

setSemaphore in interface ExtObjectContainer

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)

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.

Specified by:

storedClass in interface ExtObjectContainer

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.

Specified by:

storedClasses in interface ExtObjectContainer

systemInfo

public SystemInfo systemInfo()

Description copied from interface: ExtObjectContainer

returns the SystemInfo for this ObjectContainer.

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

Specified by:

systemInfo in interface ExtObjectContainer

Returns:

the SystemInfo for this ObjectContainer.

version

public long version()

Description copied from interface: ExtObjectContainer

returns the current transaction serial number.

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

Specified by:

version in interface ExtObjectContainer

Returns:

the current transaction serial number.

activate

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

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.

Specified by:

activate in interface ExtObjectContainer

Throws:

Db4oIOException

DatabaseClosedException

activate

public void activate(java.lang.Object obj,
            int depth)
              throws Db4oIOException,
                     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.

Specified by:

activate in interface ObjectContainer

Parameters:

obj - the object to be activated.

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

Throws:

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

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

See Also:

Why activation?, Using callbacks

close

public boolean close()
              throws Db4oIOException

Description copied from interface: ObjectContainer

closes the ObjectContainer.

A call to close() automatically performs a commit().

Note that every session opened with Db4o.openFile() requires one close()call, even if the same filename was used multiple times.

Use while(!close()){} to kill all sessions using this container.

Specified by:

close in interface ObjectContainer

Returns:

success - true denotes that the last used instance of this container and the database file were closed.

Throws:

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

commit

public void commit()
            throws Db4oIOException,
                   DatabaseClosedException,
                   DatabaseReadOnlyException,
                   UniqueFieldValueConstraintViolationException

Description copied from interface: ObjectContainer

commits the running transaction.

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

Specified by:

commit in interface ObjectContainer

Throws:

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

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

DatabaseReadOnlyException - database was configured as read-only.

UniqueFieldValueConstraintViolationException

deactivate

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

Specified by:

deactivate in interface ObjectContainer

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?

deactivate

public void deactivate(java.lang.Object obj)
                throws DatabaseClosedException

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.

Specified by:

deactivate in interface ExtObjectContainer

Parameters:

obj - the object to be deactivated.

Throws:

DatabaseClosedException

delete

public void delete(java.lang.Object obj)
            throws Db4oIOException,
                   DatabaseClosedException,
                   DatabaseReadOnlyException

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.

Specified by:

delete in interface ObjectContainer

Parameters:

obj - the object to be deleted from the ObjectContainer.

Throws:

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

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

DatabaseReadOnlyException - database was configured as read-only.

See Also:

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

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.

Specified by:

ext in interface ObjectContainer

Returns:

this, casted to ExtObjectContainer

queryByExample

public ObjectSet queryByExample(java.lang.Object template)
                         throws Db4oIOException,
                                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.

Specified by:

queryByExample in interface ObjectContainer

Parameters:

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

Returns:

ObjectSet containing all found objects.

Throws:

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

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

See Also:

Why activation?, Using callbacks

query

public Query query()
            throws DatabaseClosedException

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.

Specified by:

query in interface ObjectContainer

Returns:

a new Query object

Throws:

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

query

public ObjectSet query(java.lang.Class clazz)
                throws Db4oIOException,
                       DatabaseClosedException

Description copied from interface: ObjectContainer

queries for all instances of a class.

Specified by:

query in interface ObjectContainer

Parameters:

clazz - the class to query for.

Returns:

the ObjectSet returned by the query.

Throws:

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

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

query

public ObjectSet query(Predicate predicate)
                throws Db4oIOException,
                       DatabaseClosedException

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.

Specified by:

query in interface ObjectContainer

Parameters:

predicate - the Predicate containing the native query expression.

Returns:

the ObjectSet returned by the query.

Throws:

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

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

query

public <T> ObjectSet<T> query(Predicate<T> predicate,
                     QueryComparator<T> comparator)
                   throws Db4oIOException,
                          DatabaseClosedException

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.

Specified by:

query in interface ObjectContainer

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.

Throws:

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

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

rollback

public void rollback()
              throws Db4oIOException,
                     DatabaseClosedException,
                     DatabaseReadOnlyException

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.

Specified by:

rollback in interface ObjectContainer

Throws:

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

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

DatabaseReadOnlyException - database was configured as read-only.

store

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

Specified by:

store in interface ObjectContainer

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

container

public ObjectContainerBase container()

Specified by:

container in interface InternalObjectContainer

transaction

public Transaction transaction()

Specified by:

transaction in interface InternalObjectContainer

callbacks

public void callbacks(Callbacks cb)

Specified by:

callbacks in interface InternalObjectContainer

callbacks

public Callbacks callbacks()

Specified by:

callbacks in interface InternalObjectContainer

getNativeQueryHandler

public final NativeQueryHandler getNativeQueryHandler()

Specified by:

getNativeQueryHandler in interface InternalObjectContainer

classMetadataForReflectClass

public ClassMetadata classMetadataForReflectClass(ReflectClass reflectClass)

Specified by:

classMetadataForReflectClass in interface InternalObjectContainer

classMetadataForName

public ClassMetadata classMetadataForName(java.lang.String name)

Specified by:

classMetadataForName in interface InternalObjectContainer

classMetadataForID

public ClassMetadata classMetadataForID(int id)

Specified by:

classMetadataForID in interface InternalObjectContainer

handlers

public HandlerRegistry handlers()

Specified by:

handlers in interface InternalObjectContainer

syncExec

public java.lang.Object syncExec(Closure4 block)

Specified by:

syncExec in interface InternalObjectContainer

instanceCount

public int instanceCount(ClassMetadata clazz,
                Transaction trans)

Specified by:

instanceCount in interface InternalObjectContainer

query

public ObjectSet query(Predicate predicate,
              java.util.Comparator comparator)
                throws Db4oIOException,
                       DatabaseClosedException

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

Specified by:

query in interface ObjectContainer

Parameters:

predicate - the Predicate containing the native query expression.

comparator - the java.util.Comparator specifying the sort order of the result

Returns:

the ObjectSet returned by the query.

Throws:

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

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

isClient

public boolean isClient()

Specified by:

isClient in interface InternalObjectContainer

storeAll

public void storeAll(Transaction transaction,
            Iterator4 objects)

Specified by:

storeAll in interface InternalObjectContainer

updateDepthProvider

public UpdateDepthProvider updateDepthProvider()

Specified by:

updateDepthProvider in interface InternalObjectContainer

openSession

public ObjectContainer openSession()

Description copied from interface: ExtObjectContainer

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

Specified by:

openSession in interface ExtObjectContainer

Returns:

the new ObjectContainer session.

newEventRegistry

public EventRegistryImpl newEventRegistry()

Specified by:

newEventRegistry in interface InternalObjectContainer

from

public <T> QLin<T> from(java.lang.Class<T> clazz)