db4o 2.5

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 bind(java.lang.Object obj, long id)
          binds an object to an internal object ID.
 Configuration configure()
          returns the Configuration context for this ObjectContainer.
 java.lang.Object getByID(long ID)
          returns the stored object for an internal ID.
 long getID(java.lang.Object obj)
          returns the internal unique object ID.
 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.
 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.
 StoredClass storedClass(java.lang.String forName)
          returns the stored class for a fully qualified class name.
 StoredClass[] storedClasses()
          returns an array of all stored classes.
 
Methods inherited from interface com.db4o.ObjectContainer
activate, close, commit, deactivate, delete, ext, get, query, rollback, set
 

Method Detail

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

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.

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?

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.

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

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.

Parameters:
object - to be tested

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.

Parameters:
object - to be tested

Returns:
true if the passed object is stored.

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. The JDK2 versions "community edition" and "professional edition" use weak references for this task. db4o "mobile edition" uses hard references.

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 JDK2 versions ("professional" and "community"), since 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:
Object - the object to be removed from the reference mechanism.

storedClass

public StoredClass storedClass(java.lang.String forName)
returns the stored class for a fully qualified class name.
Parameters:
name - the name of the class. The package name needs to be supplied.

storedClasses

public StoredClass[] storedClasses()
returns an array of all stored classes.

db4o 2.5