Package com.db4o.internal

Class ExternalObjectContainer

    • Constructor Detail

      • ExternalObjectContainer

        public ExternalObjectContainer​(Configuration config)

    • Method Detail

      • activate

        public final void activate​(java.lang.Object obj,
                           int depth)
                    throws DatabaseClosedException
        Description copied from interface: ObjectContainer
        Activates all members on a stored object to the specified depth.

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

        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.

        Parameters:
        obj - the objects to be activated.
        depth - the object-graph depth up to which object are activated
        Throws:
        DatabaseClosedException - db4o database file was closed or failed to open.
        See Also:
        Why activation?, Using callbacks

      • deactivate

        public final void deactivate​(java.lang.Object obj)
        Description copied from interface: ExtObjectContainer
        deactivates an object. Only the passed object will be deactivated, i.e, no object referenced by this object will be deactivated.
        Parameters:
        obj - the object to be deactivated.

      • bind

        public final void bind​(java.lang.Object obj,
                       long id)
                throws ArgumentNullException,
                       java.lang.IllegalArgumentException
        Description copied from interface: ExtObjectContainer
        binds an object to an internal object ID.

        This method uses the ID parameter to load the corresponding stored object into memory and replaces this memory reference with the object parameter. The method may be used to replace objects or to reassociate an object with it's stored instance after closing and opening a database file. A subsequent call to 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.

        Parameters:
        obj - the object that is to be bound
        id - the internal id the object is to be bound to
        Throws:
        ArgumentNullException
        java.lang.IllegalArgumentException
        See Also:
        ExtObjectContainer.getID(java.lang.Object)

      • deactivate

        public final void deactivate​(java.lang.Object obj,
                             int depth)
                      throws DatabaseClosedException
        Description copied from interface: ObjectContainer
        Deactivates a stored object by setting all members to null.
        Primitive types will be set to their default values. 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.
        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?

      • descend

        public java.lang.Object descend​(java.lang.Object obj,
                                java.lang.String[] path)
        Description copied from interface: ExtObjectContainer
        returns a member at the specific path without activating intermediate objects.

        This method allows navigating from a persistent object to it's members in a performant way without activating or instantiating intermediate objects.
        Parameters:
        obj - the parent object that is to be used as the starting point.
        path - an array of field names to navigate by
        Returns:
        the object at the specified path or null if no object is found

      • ext

        public ExtObjectContainer ext()
        Description copied from interface: ObjectContainer
        Returns an ObjectContainer with extended functionality.

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

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

        Returns:
        this, casted to ExtObjectContainer

      • queryByExample

        public final ObjectSet queryByExample​(java.lang.Object template)
                               throws DatabaseClosedException
        Description copied from interface: ObjectContainer
        Query-By-Example interface to retrieve objects.

        queryByExample() creates an ObjectSet containing all objects in the 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.
        Parameters:
        template - object to be used as an example to find all matching objects.

        Returns:
        ObjectSet containing all found objects.

        Throws:
        DatabaseClosedException - db4o database file was closed or failed to open.
        See Also:
        Why activation?

      • getByID

        public final java.lang.Object getByID​(long id)
                               throws DatabaseClosedException,
                                      InvalidIDException
        Description copied from interface: ExtObjectContainer
        returns the stored object for an internal ID.

        This is the fastest method for direct access to objects. Internal IDs can be obtained with getID(Object). Objects will not be activated by this method. They will be returned in the activation state they are currently in, in the local cache.

        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 final long getID​(java.lang.Object obj)
        Description copied from interface: ExtObjectContainer
        returns the internal unique object ID.

        db4o assigns an internal ID to every object that is stored. IDs are guaranteed to be unique within one ObjectContainer. An object carries the same ID in every db4o session. Internal IDs can be used to look up objects with the very fast getByID method.

        Internal IDs will change when a database is defragmented. Use ExtObjectContainer.getObjectInfo(Object), ObjectInfo.getUUID() and ExtObjectContainer.getByUUID(Db4oUUID) for long-term external references to objects.

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

      • getObjectInfo

        public final ObjectInfo getObjectInfo​(java.lang.Object obj)
        Description copied from interface: ExtObjectContainer
        returns the ObjectInfo for a stored object.

        This method will return null, if the passed object is not stored to this ObjectContainer.

        Parameters:
        obj - the stored object
        Returns:
        the ObjectInfo

      • isActive

        public boolean isActive​(java.lang.Object obj)
        Description copied from interface: ExtObjectContainer
        tests if an object is activated.

        isActive returns false if an object is not stored within the ObjectContainer.

        Parameters:
        obj - to be tested

        Returns:
        true if the passed object is active.

      • isCached

        public boolean isCached​(long id)
        Description copied from interface: ExtObjectContainer
        tests if an object with this ID is currently cached.

        Parameters:
        id - the internal ID

      • isStored

        public boolean isStored​(java.lang.Object obj)
        Description copied from interface: ExtObjectContainer
        tests if an object is stored in this ObjectContainer.

        Parameters:
        obj - to be tested

        Returns:
        true if the passed object is stored.

      • peekPersisted

        public final java.lang.Object peekPersisted​(java.lang.Object obj,
                                            int depth,
                                            boolean committed)
                                     throws DatabaseClosedException
        Description copied from interface: ExtObjectContainer
        returns a transient copy of a persistent object with all members set to the values that are currently stored to the database.

        The returned objects have no connection to the database.

        With the committed parameter it is possible to specify, whether the desired object should contain the committed values or the values that were set by the running transaction with ObjectContainer.store(java.lang.Object).

        A possible use case for this feature:
        An application might want to check all changes applied to an object by the running transaction.

        Parameters:
        obj - the object that is to be cloned
        depth - the member depth to which the object is to be instantiated
        committed - whether committed or set values are to be returned
        Returns:
        the object
        Throws:
        DatabaseClosedException

      • purge

        public final void purge​(java.lang.Object obj)
        Description copied from interface: ExtObjectContainer
        unloads a specific object from the db4o reference mechanism.

        db4o keeps references to all newly stored and instantiated objects in memory, to be able to manage object identities.

        With calls to this method it is possible to remove an object from the reference mechanism.
        An object removed with purge(Object) is not "known" to the ObjectContainer afterwards, so this method may also be used to create multiple copies of objects.

        purge(Object) has no influence on the persistence state of objects. "Purged" objects can be reretrieved with queries.

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

      • query

        public Query query()
        Description copied from interface: ObjectContainer
        Creates a new S.O.D.A. Query. NOTE: Soda queries silently ignore invalid specified fields, constraints etc.

        Native queries are the recommended main db4o query interface.

        Returns:
        a new Query object

      • query

        public final ObjectSet query​(java.lang.Class clazz)
        Description copied from interface: ObjectContainer
        Queries for all instances of a class.
        Parameters:
        clazz - the class to query for.
        Returns:
        all instances of the given class

      • query

        public final ObjectSet query​(Predicate predicate)
        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.

        Parameters:
        predicate - the Predicate containing the native query expression.
        Returns:
        the query result

      • refresh

        public final void refresh​(java.lang.Object obj,
                          int depth)
        Description copied from interface: ExtObjectContainer
        refreshs all members on a stored object to the specified depth.

        If a member object is not activated, it will be activated by this method.

        The isolation used is READ COMMITTED. This method will read all objects and values that have been committed by other transactions.

        Parameters:
        obj - the object to be refreshed.
        depth - the member depth to which refresh is to cascade.

      • rollback

        public final void rollback()
        Description copied from interface: ObjectContainer
        Rolls back the running transaction. This only rolls back the changes in the database, but not the state of in memory objects.

        Dealing with stale state of in memory objects after a rollback:
        • Since in memory objects are not rolled back you probably want start with a clean state. The easiest way to do this is by creating a new object container: ObjectContainer.ext().openSession().
        • Alternatively you can deactivate objects or refresh them to get back to the state in the database.
        • In case you are using transparent persistence you can use a rollback strategy to rollback the in memory objects as well.

      • storedClass

        public final StoredClass storedClass​(java.lang.Object clazz)
        Description copied from interface: ExtObjectContainer
        returns a StoredClass meta information object.

        There are three options how to use this method.
        Any of the following parameters are possible:
        - a fully qualified class name.
        - a Class object.
        - any object to be used as a template.

        Parameters:
        clazz - class name, Class object, or example object.

        Returns:
        an instance of an StoredClass meta information object.

      • backup

        public abstract void backup​(Storage targetStorage,
                            java.lang.String path)
                     throws Db4oIOException,
                            DatabaseClosedException,
                            NotSupportedException
        Description copied from interface: ExtObjectContainer
        backs up a database file of an open ObjectContainer.

        While the backup is running, the ObjectContainer can continue to be used. Changes that are made while the backup is in progress, will be applied to the open ObjectContainer and to the backup.

        While the backup is running, the ObjectContainer should not be closed.

        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.
        Parameters:
        targetStorage - the Storage to be used for backup
        path - a fully qualified path
        Throws:
        Db4oIOException - I/O operation failed or was unexpectedly interrupted.
        DatabaseClosedException - db4o database file was closed or failed to open.
        NotSupportedException - is thrown when the operation is not supported in current configuration/environment

      • backupSync

        public abstract void backupSync​(Storage targetStorage,
                                java.lang.String path)
                         throws Db4oIOException,
                                DatabaseClosedException,
                                NotSupportedException
        Description copied from interface: ExtObjectContainer
        backs up a database file of an open ObjectContainer. While the backup is running, the ObjectContainer 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.
        Parameters:
        targetStorage - the Storage to be used for backup
        path - a fully qualified path
        Throws:
        Db4oIOException - I/O operation failed or was unexpectedly interrupted.
        DatabaseClosedException - db4o database file was closed or failed to open.
        NotSupportedException - is thrown when the operation is not supported in current configuration/environment

      • identity

        public abstract Db4oDatabase identity()
        Description copied from interface: ExtObjectContainer
        returns the Db4oDatabase object for this ObjectContainer.
        Returns:
        the Db4oDatabase identity object for this ObjectContainer.

      • inCallback

        public boolean inCallback()