| com.db4o.ext.ExtObjectContainer
| Method Summary | |
| public void | backup(String path)
backs up a database file of an open ObjectContainer.
While the backup is running, the ObjectContainer can continue to be
used. | | public void | bind(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. | | public Db4oCollections | collections()
| | public Configuration | configure()
returns the Configuration context for this ObjectContainer.
Upon opening an ObjectContainer with any of the factory methods in the
com.db4o.Db4o Db4o class , the global
com.db4o.config.Configuration Configuration context
is copied into the ObjectContainer. | | public Object | descend(Object obj, 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. | | public T | getByID(long ID)
returns the stored object for an internal ID.
This is the fastest method for direct access to objects. | | public T | getByUUID(Db4oUUID uuid)
returns a stored object for a
Db4oUUID .
This method is intended for replication and for long-term
external references to objects. | | public long | getID(Object obj)
returns the internal unique object ID.
db4o assigns an internal ID to every object that is stored. | | public ObjectInfo | getObjectInfo(Object obj)
returns the
ObjectInfo for a stored object. | | public Db4oDatabase | identity()
returns the Db4oDatabase object for this ObjectContainer. | | public boolean | isActive(Object obj)
tests if an object is activated. | | public boolean | isCached(long ID)
tests if an object with this ID is currently cached. | | public boolean | isClosed()
tests if this ObjectContainer is closed. | | public boolean | isStored(Object obj)
tests if an object is stored in this ObjectContainer. | | public ReflectClass[] | knownClasses()
returns all class representations that are known to this
ObjectContainer because they have been used or stored.
all class representations that are known to thisObjectContainer because they have been used or stored. | | public Object | lock()
returns the main synchronisation lock. | | public void | migrateFrom(ObjectContainer objectContainer)
aids migration of objects between ObjectContainers. | | public 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. | | public void | purge()
unloads all clean indices from memory and frees unused objects.
Call commit() and purge() consecutively to achieve the best
result possible. | | public void | purge(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. | | public GenericReflector | reflector()
Return the reflector currently being used by db4objects. | | public void | refresh(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. | | public void | releaseSemaphore(String name)
releases a semaphore, if the calling transaction is the owner. | | public ReplicationProcess | replicationBegin(ObjectContainer peerB, ReplicationConflictHandler conflictHandler)
ObjectContainerObjectContainerObjectContainerReplicationProcess
Parameters:
peerB - the ObjectContainer to replicate with.
Parameters:
conflictHandler - the conflict handler for this ReplicationProcess. | | public void | set(Object obj, int depth)
deep update interface to store or update objects. | | public boolean | setSemaphore(String name, int waitForAvailability)
attempts to set a semaphore.
Semaphores are transient multi-purpose named flags for
ObjectContainer ObjectContainers .
A transaction that successfully sets a semaphore becomes
the owner of the semaphore. | | public StoredClass | storedClass(Object clazz)
returns a
StoredClass meta information object. | | public StoredClass[] | storedClasses()
returns an array of all
StoredClass meta information objects. | | public SystemInfo | systemInfo()
returns the
SystemInfo for this ObjectContainer.
The
SystemInfo supplies methods that provide
information about system state and system settings of this
ObjectContainer. | | public long | version()
returns the current transaction serial number. |
| backup | | public void backup(String path) throws Db4oIOException, DatabaseClosedException, NotSupportedException(Code) | | backs up a database file of an open ObjectContainer.
While the backup is running, the ObjectContainer can continue to be
used. Changes that are made while the backup is in progress, will be applied to
the open ObjectContainer and to the backup.
While the backup is running, the ObjectContainer should not be closed.
If a file already exists at the specified path, it will be overwritten.
Parameters:
path - a fully qualified path
throws:
DatabaseClosedException - db4o database file was closed or failed to open.
throws:
NotSupportedException - is thrown when the operation is not supported in current configuration/environment
throws:
Db4oIOException - I/O operation failed or was unexpectedly interrupted. |
| bind | | public void bind(Object obj, long id) throws InvalidIDException, DatabaseClosedException(Code) | | 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
com.db4o.ObjectContainer.set set(Object) is
necessary to update the stored object.
Requirements:
- The ID needs to be a valid internal object ID,
previously retrieved with
ExtObjectContainer.getID getID(Object) .
- The object parameter needs to be of the same class as the stored object.
See Also: ExtObjectContainer.getID(java.lang.Object)
Parameters:
obj - the object that is to be bound
Parameters:
id - the internal id the object is to be bound to
throws:
DatabaseClosedException - db4o database file was closed or failed to open.
throws:
InvalidIDException - when the provided id is outside the scope of the database IDs. |
| descend | | public Object descend(Object obj, String[] path)(Code) | | 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.
Parameters:
path - an array of field names to navigate by the object at the specified path or null if no object is found |
| getByID | | public T getByID(long ID) throws DatabaseClosedException, InvalidIDException(Code) | | returns the stored object for an internal ID.
This is the fastest method for direct access to objects. Internal
IDs can be obtained with
ExtObjectContainer.getID getID(Object) .
Objects will not be activated by this method. They will be returned in the
activation state they are currently in, in the local cache.
Parameters:
ID - the internal ID the object associated with the passed ID or null, if no object is associated with this ID in this ObjectContainer.
See Also: com.db4o.config.Configuration.activationDepth
See Also: Why activation?
throws:
DatabaseClosedException - db4o database file was closed or failed to open.
throws:
InvalidIDException - when the provided id is outside the scope of the |
| getID | | public long getID(Object obj)(Code) | | 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
ExtObjectContainer.getByID 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 the associated internal ID or 0, if the passedobject is not stored in this ObjectContainer. |
| getObjectInfo | | public ObjectInfo getObjectInfo(Object obj)(Code) | | 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 the ObjectInfo |
| identity | | public Db4oDatabase identity()(Code) | | returns the Db4oDatabase object for this ObjectContainer.
the Db4oDatabase identity object for this ObjectContainer. |
| isActive | | public boolean isActive(Object obj)(Code) | | tests if an object is activated.
isActive returns false if an object is not
stored within the ObjectContainer.
Parameters:
obj - to be tested
true if the passed object is active. |
| isCached | | public boolean isCached(long ID)(Code) | | tests if an object with this ID is currently cached.
Parameters:
ID - the internal ID |
| isClosed | | public boolean isClosed()(Code) | | tests if this ObjectContainer is closed.
true if this ObjectContainer is closed. |
| knownClasses | | public ReflectClass[] knownClasses()(Code) | | returns all class representations that are known to this
ObjectContainer because they have been used or stored.
all class representations that are known to thisObjectContainer because they have been used or stored. |
| lock | | public Object lock()(Code) | | returns the main synchronisation lock.
Synchronize over this object to ensure exclusive access to
the ObjectContainer.
Handle the use of this functionality with extreme care,
since deadlocks can be produced with just two lines of code.
Object the ObjectContainer lock object |
| migrateFrom | | public void migrateFrom(ObjectContainer objectContainer)(Code) | | aids migration of objects between ObjectContainers.
When objects are migrated from one ObjectContainer to another, it is
desirable to preserve virtual object attributes such as the object version number
or the UUID. Use this method to signal to an ObjectContainer that it should read
existing version numbers and UUIDs from another ObjectContainer. This method should
also be used during the
com.db4o.tools.Defragment Defragment operation. It is included in the default
implementation supplied in Defragment.java/Defragment.cs.
Parameters:
objectContainer - the ObjectContainer objects are to be migratedfrom or null to denote that migration is completed. |
| peekPersisted | | public T peekPersisted(T object, int depth, boolean committed)(Code) | | returns a transient copy of a persistent object with all members set
to the values that are currently stored to the database.
The returned objects have no connection to the database.
With the committed parameter it is possible to specify,
whether the desired object should contain the committed values or the
values that were set by the running transaction with
ObjectContainer.set(java.lang.Object) .
A possible usecase for this feature:
An application might want to check all changes applied to an object
by the running transaction.
Parameters:
object - the object that is to be cloned
Parameters:
depth - the member depth to which the object is to be instantiated
Parameters:
committed - whether committed or set values are to be returned the object |
| purge | | public void purge()(Code) | | 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(Object obj)(Code) | | 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 | | public GenericReflector reflector()(Code) | | Return the reflector currently being used by db4objects.
the current Reflector. |
| refresh | | public void refresh(Object obj, int depth)(Code) | | 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.
Parameters:
depth - the member Configuration.activationDepth(int) depthto which refresh is to cascade. |
| releaseSemaphore | | public void releaseSemaphore(String name)(Code) | | releases a semaphore, if the calling transaction is the owner.
Parameters:
name - the name of the semaphore to be released. |
| set | | public void set(Object obj, int depth)(Code) | | deep update interface to store or update objects.
In addition to the normal storage interface,
com.db4o.ObjectContainer.set 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.
Parameters:
depth - the depth to which the object is to be updated
See Also: com.db4o.ObjectContainer.set |
| setSemaphore | | public boolean setSemaphore(String name, int waitForAvailability)(Code) | | attempts to set a semaphore.
Semaphores are transient multi-purpose named flags for
ObjectContainer ObjectContainers .
A transaction that successfully sets a semaphore becomes
the owner of the semaphore. Semaphores can only be owned
by a single transaction at one point in time.
This method returns true, if the transaction already owned
the semaphore before the method call or if it successfully
acquires ownership of the semaphore.
The waitForAvailability parameter allows to specify a time
in milliseconds to wait for other transactions to release
the semaphore, in case the semaphore is already owned by
another transaction.
Semaphores are released by the first occurence of one of the
following:
- the transaction releases the semaphore with
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 usecases
for semaphores:
- prevent other clients from inserting a singleton at the same time.
A suggested name for the semaphore: "SINGLETON_" + Object#getClass().getName().
- lock
objects. A suggested name: "LOCK_" +
ExtObjectContainer.getID(java.lang.Object) getID(Object)
-
generate a unique client ID. A suggested name: "CLIENT_" +
System.currentTimeMillis().
Parameters:
name - the name of the semaphore to be set
Parameters:
waitForAvailability - the time in milliseconds to wait for othertransactions to release the semaphore. The parameter may be zero, ifthe method is to return immediately. 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 anothertransaction. |
| storedClass | | public StoredClass storedClass(Object clazz)(Code) | | returns a
StoredClass meta information object.
There are three options how to use this method.
Any of the following parameters are possible:
- a fully qualified classname.
- a Class object.
- any object to be used as a template.
Parameters:
clazz - class name, Class object, or example object.
an instance of an StoredClass meta information object. |
| systemInfo | | public SystemInfo systemInfo()(Code) | | returns the
SystemInfo for this ObjectContainer.
The
SystemInfo supplies methods that provide
information about system state and system settings of this
ObjectContainer.
the SystemInfo for this ObjectContainer. |
| version | | public long version()(Code) | | returns the current transaction serial number.
This serial number can be used to query for modified objects
and for replication purposes.
the current transaction serial number. |
|
|