Package com.db4o.internal

Class ObjectContainerSession

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

        Note that this is designed to run as a background process: To avoid harming performance of concurrently active database operations, it tries to leave room for other threads as much as possible and thus will be orders of magnitude slower than a regular file copy. If you are looking for a faster backup (that will block all other database operations), use ExtObjectContainer.backupSync(Storage, String) instead.

        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.

        Note that this is designed to run as a background process: To avoid harming performance of concurrently active database operations, it tries to leave room for other threads as much as possible and thus will be orders of magnitude slower than a regular file copy. If you are looking for a faster backup (that will block all other database operations), use ExtObjectContainer.backupSync(Storage, String) instead.

        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

      • backupSync

        public void backupSync​(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 should not be closed.

        Note that this blocks all other concurrently active database operations for the full duration of the backup. If you intend to run a backup as a less intrusive background process concurrently with other database operations, use ExtObjectContainer.backup(Storage, String) instead.

        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:
        backupSync in interface ExtObjectContainer
        Parameters:
        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

      • backupSync

        public void backupSync​(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 should not be closed.

        Note that this blocks all other concurrently active database operations for the full duration of the backup. If you intend to run a backup as a less intrusive background process concurrently with other database operations, use ExtObjectContainer.backup(Storage, String) instead.

        If a file already exists at the specified path, it will be overwritten.

        This method can be used for cross-storage backups, i.e. backup from an in-memory database to a file.
        Specified by:
        backupSync 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 store(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)

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

        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 an invalid id is passed
        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.

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

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

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

      • 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#store(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:
        ObjectContainer.store(java.lang.Object)

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

      • 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,
                     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.

        Calling this 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. When called it starts from the given object, traverses all member objects and activates them up to the given depth. 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 not populated with data. Its fields will be null. The activation depth of individual classes can be overruled with the methods maximumActivationDepth() and minimumActivationDepth() in the ObjectClass interface.

        Specified by:
        activate in interface ObjectContainer
        Parameters:
        obj - the objects to be activated.
        depth - the object-graph depth up to which object are activated
        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.

        Calling close() automatically performs a commit().
        Specified by:
        close in interface ObjectContainer
        Returns:
        success - true denotes that the object container was closed, false if it was already closed
        Throws:
        Db4oIOException - I/O operation failed or was unexpectedly interrupted.

      • 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. The method has no effect, if the passed object is not stored in the object container.

        Be aware that calling may have side effects, which assume that a object is filled with data.

        In general you should not deactivate objects, since it makes you application more complex and confusing. To control the scope of objects you should use session containers for your unit of work. Use ObjectContainer.ext()openSession() to create a new session.
        Specified by:
        deactivate in interface ObjectContainer
        Parameters:
        obj - the object to be deactivated.
        depth - the object-graph depth up to which object are deactivated
        Throws:
        DatabaseClosedException - db4o database file was closed or failed to open.
        See Also:
        Using callbacks, Why activation?

      • 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 database that match the passed template object.

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

        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 collections are evaluated for containment. Differences in length/size() are ignored.
        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?

      • query

        public ObjectSet query​(Predicate predicate)
                throws Db4oIOException,
                       DatabaseClosedException
        Description copied from interface: ObjectContainer
        Native Query Interface.

        Make sure that you include the db4o-nqopt-java.jar and bloat.jar in your classpath when using native queries. Unless you are using the db4o-all-java5.jar

        Native Queries allows typesafe, compile-time checked and refactorable queries, following object-oriented principles. A Native Query expression should return true to include that object in the result and false otherwise.

        db4o will attempt to optimize native query expressions and execute them against indexes and without instantiating actual objects. Otherwise db4o falls back and instantiates objects to run them against the given predicate. That is an order of magnitude slower than a optimized native query.

        
 List<Cat> cats = db.query(new Predicate<Cat>() {
     public boolean match(Cat cat) {
         return cat.getName().equals("Occam");
     }
 });
        Summing up the above:
        In order to execute a Native Query, you can extend the Predicate class

        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.
        - The query expression should return true to include a object. False otherwise.

        Specified by:
        query in interface ObjectContainer
        Parameters:
        predicate - the Predicate containing the native query expression.
        Returns:
        the query result
        Throws:
        Db4oIOException - I/O operation failed or was unexpectedly interrupted.
        DatabaseClosedException - db4o database file was closed or failed to open.

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

      • from

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