Package com.db4o

Interface ObjectContainer

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void activate​(java.lang.Object obj, int depth)
      Activates all members on a stored object to the specified depth.
      boolean close()
      Closes the ObjectContainer.
      void commit()
      Commits the running transaction.
      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 from the database.
      ExtObjectContainer ext()
      Returns an ObjectContainer with extended functionality.
      Query query()
      Creates a new S.O.D.A.
      <TargetType>
      ObjectSet<TargetType>      		 query​(Predicate<TargetType> predicate)
      Native Query Interface.

      Make sure that you include the db4o-nqopt-java.jar and bloat.jar in your classpath when using native queries.
      <TargetType>
      ObjectSet<TargetType>      		 query​(Predicate<TargetType> predicate, QueryComparator<TargetType> comparator)
      Native Query Interface.
      <TargetType>
      ObjectSet<TargetType>      		 query​(Predicate<TargetType> predicate, java.util.Comparator<TargetType> comparator)
      Native Query Interface.
      <TargetType>
      ObjectSet<TargetType>      		 query​(java.lang.Class<TargetType> clazz)
      Queries for all instances of a class.
      <T> ObjectSet<T> queryByExample​(java.lang.Object template)
      Query-By-Example interface to retrieve objects.
      void rollback()
      Rolls back the running transaction.
      void store​(java.lang.Object obj)
      Stores objects or updates stored objects.

    • Method Detail

      • activate

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

        boolean close()
       throws Db4oIOException
        Closes the ObjectContainer.

        Calling close() automatically performs a commit().
        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

        void deactivate​(java.lang.Object obj,
                int depth)
         throws DatabaseClosedException
        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 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?

      • ext

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

        <T> ObjectSet<T> queryByExample​(java.lang.Object template)
                         throws Db4oIOException,
                                DatabaseClosedException
        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:
        Db4oIOException - I/O operation failed or was unexpectedly interrupted.
        DatabaseClosedException - db4o database file was closed or failed to open.
        See Also:
        Why activation?

      • query

        <TargetType> ObjectSet<TargetType> query​(Predicate<TargetType> predicate)
                                  throws Db4oIOException,
                                         DatabaseClosedException
        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
        Throws:
        Db4oIOException - I/O operation failed or was unexpectedly interrupted.
        DatabaseClosedException - db4o database file was closed or failed to open.

      • rollback

        void rollback()
       throws Db4oIOException,
              DatabaseClosedException,
              DatabaseReadOnlyException
        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: 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.
        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.