Package org.intermine.objectstore

Interface ObjectStore

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.Map<java.lang.Object,​java.lang.Integer> SEQUENCE_IGNORE
      Object representing no fail-fast concurrency checks required.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.lang.Object cacheObjectById​(java.lang.Integer id, InterMineObject obj)
      Places an entry into the objectstore getObjectById cache.
      int count​(Query q, java.util.Map<java.lang.Object,​java.lang.Integer> sequence)
      Counts the number of rows the query will produce
      Clob createClob()
      Creates a new empty Clob that is valid for this ObjectStore.
      ObjectStoreBag createObjectStoreBag()
      Returns a new empty ObjectStoreBag object that is valid for this ObjectStore.
      ResultsInfo estimate​(Query q)
      Explain a Query (give estimate for execution time and number of rows).
      Results execute​(Query q)
      Execute a Query on this ObjectStore
      Results execute​(Query q, int batchSize, boolean optimise, boolean explain, boolean prefetch)
      Execute a Query on this ObjectStore
      java.util.List<ResultsRow<java.lang.Object>> execute​(Query q, int start, int limit, boolean optimise, boolean explain, java.util.Map<java.lang.Object,​java.lang.Integer> sequence)
      Execute a Query on this ObjectStore, asking for a certain range of rows to be returned.
      SingletonResults executeSingleton​(Query q)
      Execute a Query on this ObjectStore, returning a SingletonResults
      SingletonResults executeSingleton​(Query q, int batchSize, boolean optimise, boolean explain, boolean prefetch)
      Execute a Query on this ObjectStore, returning a SingletonResults
      void flushObjectById()
      Completely empties the getObjectById cache.
      java.util.Set<java.lang.Object> getComponentsForQuery​(Query q)
      Returns a Set of independent components that affect the results of the given Query.
      int getMaxLimit()
      Get the maximum LIMIT that can be used in an SQL query without throwing an ObjectStoreLimitReachedException
      int getMaxOffset()
      Get the maximum range start index a that can be accessed in a Results object without throwing an ObjectStoreLimitReachedException
      long getMaxTime()
      Get the maximum time a query may take before throwing an ObjectStoreQueryDurationException
      Model getModel()
      Return the metadata associated with this ObjectStore
      ObjectStoreWriter getNewWriter()
      Create an ObjectStoreWriter that writes into this ObjectStore.
      <T extends InterMineObject>
      T      		 getObjectByExample​(T o, java.util.Set<java.lang.String> fieldNames)
      Return an object from the objectstore that has the fields mentioned in the list set to the same values as the fields in the provided example object.
      InterMineObject getObjectById​(java.lang.Integer id)
      Get an object from the ObjectStore by giving an ID.
      InterMineObject getObjectById​(java.lang.Integer id, java.lang.Class<? extends InterMineObject> clazz)
      Get an object from the ObjectStore by giving an ID and a hint of the Class of the object.
      <T extends InterMineObject>
      java.util.Collection<T>      		 getObjectsByExample​(T o, java.util.Set<java.lang.String> fieldNames)
      Return an object from the objectstore that has the fields mentioned in the list set to the same values as the fields in the provided example object.
      java.util.List<InterMineObject> getObjectsByIds​(java.util.Collection<java.lang.Integer> ids)
      Get an objects from the ObjectStore that have the IDs in the ids colection
      java.util.Map<java.lang.Object,​java.lang.Integer> getSequence​(java.util.Set<java.lang.Object> tables)
      Return the sequence number representing the state of the ObjectStore.
      java.lang.Integer getSerial()
      Gets an ID number which is unique in the database.
      void invalidateObjectById​(java.lang.Integer id)
      Removes an entry from the objectstore getObjectById cache.
      boolean isMultiConnection()
      Return whether or not this ObjectStore gives a performance improvement when multiple simultaneous are made.
      InterMineObject pilferObjectById​(java.lang.Integer id)
      Gets a object from the cache if it is present.
      void prefetchObjectById​(java.lang.Integer id)
      Prefetches an object into the objectstore getObjectById cache.

    • Field Detail

      • SEQUENCE_IGNORE

        static final java.util.Map<java.lang.Object,​java.lang.Integer> SEQUENCE_IGNORE
        Object representing no fail-fast concurrency checks required.

    • Method Detail

      • getNewWriter

        ObjectStoreWriter getNewWriter()
                        throws ObjectStoreException
        Create an ObjectStoreWriter that writes into this ObjectStore. Note that the given object will consume limited resources from the ObjectStore which must be returned by calling the ObjectStoreWriter.close() method.
        Returns:
        an ObjectStoreWriter
        Throws:
        ObjectStoreException - if an error occurs
        java.lang.UnsupportedOperationException - if no writer is available for this ObjectStore

      • execute

        Results execute​(Query q)
        Execute a Query on this ObjectStore
        Parameters:
        q - the Query to execute
        Returns:
        the results of the Query

      • execute

        Results execute​(Query q,
                int batchSize,
                boolean optimise,
                boolean explain,
                boolean prefetch)
        Execute a Query on this ObjectStore
        Parameters:
        q - the Query to execute
        batchSize - the batch size to initialise the Results object with
        optimise - whether to optimise queries
        explain - whether to explain queries
        prefetch - whether to use the PrefetchManager
        Returns:
        the results of the Query

      • executeSingleton

        SingletonResults executeSingleton​(Query q)
        Execute a Query on this ObjectStore, returning a SingletonResults
        Parameters:
        q - the Query to execute
        Returns:
        the results of the Query

      • executeSingleton

        SingletonResults executeSingleton​(Query q,
                                  int batchSize,
                                  boolean optimise,
                                  boolean explain,
                                  boolean prefetch)
        Execute a Query on this ObjectStore, returning a SingletonResults
        Parameters:
        q - the Query to execute
        batchSize - the batch size to initialise the Results object with
        optimise - whether to optimise queries
        explain - whether to explain queries
        prefetch - whether to use the PrefetchManager
        Returns:
        the results of the Query

      • execute

        java.util.List<ResultsRow<java.lang.Object>> execute​(Query q,
                                                     int start,
                                                     int limit,
                                                     boolean optimise,
                                                     boolean explain,
                                                     java.util.Map<java.lang.Object,​java.lang.Integer> sequence)
                                              throws ObjectStoreException
        Execute a Query on this ObjectStore, asking for a certain range of rows to be returned. This will usually only be called by the Results object returned from execute(Query q).
        Parameters:
        q - the Query to execute
        start - the start row
        limit - the maximum number of rows to return
        optimise - true if it is expected that optimising the query will improve performance
        explain - true if the ObjectStore should enforce maximum query running time constraints
        sequence - an object representing the state of the database corresponding to when the action that resulted in this execute was started. This number must match the ObjectStore's internal sequence number or a DataChangedException is thrown. The sequence number is incremented each time the data in the objectstore is changed
        Returns:
        a List of ResultRows
        Throws:
        ObjectStoreException - if an error occurs during the running of the Query

      • getObjectById

        InterMineObject getObjectById​(java.lang.Integer id)
                       throws ObjectStoreException
        Get an object from the ObjectStore by giving an ID.
        Parameters:
        id - the ID of the object to fetch
        Returns:
        the object from the ObjectStore or cache, or null if none exists
        Throws:
        ObjectStoreException - if an error occurs during retrieval of the object

      • getObjectById

        InterMineObject getObjectById​(java.lang.Integer id,
                              java.lang.Class<? extends InterMineObject> clazz)
                       throws ObjectStoreException
        Get an object from the ObjectStore by giving an ID and a hint of the Class of the object. WARNING: If you provide the wrong class hint, this method will negatively cache the non-presence of the object which will cause other getObjectById calls to return null even if the object exists in another class.
        Parameters:
        id - the ID of the object to fetch
        clazz - a class of the object
        Returns:
        the object from the ObjectStore or the cache, or null if none exists
        Throws:
        ObjectStoreException - if an error occurs during the retrieval of the object

      • getObjectsByIds

        java.util.List<InterMineObject> getObjectsByIds​(java.util.Collection<java.lang.Integer> ids)
                                         throws ObjectStoreException
        Get an objects from the ObjectStore that have the IDs in the ids colection
        Parameters:
        ids - the IDs of the objects to fetch
        Returns:
        the objects from the ObjectStore or cache
        Throws:
        ObjectStoreException - if an error occurs during retrieval of the object

      • prefetchObjectById

        void prefetchObjectById​(java.lang.Integer id)
        Prefetches an object into the objectstore getObjectById cache. This method doesn't actually have to do anything - it is merely a hint to the objectstore that a particular operation is likely to be required in the near future.

        This method is provided primarily to help speed up our data loader. The method may block until the prefetch has been completed. However, the prefetch can be done outside of any synchronised areas of code, allowing the time-critical synchronised areas of code to access the object from the cache.

        Parameters:
        id - the ID of the object to prefetch

      • invalidateObjectById

        void invalidateObjectById​(java.lang.Integer id)
        Removes an entry from the objectstore getObjectById cache. The objectstore must guarantee that the next time this example object is requested by getObjectById, the objectstore explicitly fetches the object from the database. Obviously, if the objectstore does not have a getObjectById cache, this method will do nothing.
        Parameters:
        id - the ID of the object to invalidate

      • cacheObjectById

        java.lang.Object cacheObjectById​(java.lang.Integer id,
                                 InterMineObject obj)
        Places an entry into the objectstore getObjectById cache. This method (like prefetch) is merely a hint, and provides no guarantees. The method takes the object provided, and creates a lookup in the getObjectById cache, so that subsequent requests for that object do not access the database. If there is no cache, this method will do nothing.
        Parameters:
        id - the ID of the object
        obj - a fully populated object, as loaded from the database, or null to negatively cache
        Returns:
        an object which is softly-held part of the cache entry. This is useful to the caller for the purpose of ensuring the entry does not expire from the cache. To endure this, the caller merely needs to keep a strong reference to this returned value.

      • flushObjectById

        void flushObjectById()
        Completely empties the getObjectById cache. The objectstore must guarantee that the next time any object is mentioned, it must not be taken from the cache.

      • pilferObjectById

        InterMineObject pilferObjectById​(java.lang.Integer id)
        Gets a object from the cache if it is present. If the object is not in the cache, then no attempt is made to retrieve it from the database, and null is returned. A trivial implementation may just return null always for this method.
        Parameters:
        id - the ID of the object
        Returns:
        the object, or null

      • estimate

        ResultsInfo estimate​(Query q)
              throws ObjectStoreException
        Explain a Query (give estimate for execution time and number of rows).
        Parameters:
        q - the query to estimate rows for
        Returns:
        parsed results of EXPLAIN
        Throws:
        ObjectStoreException - if an error occurs explaining the query

      • count

        int count​(Query q,
          java.util.Map<java.lang.Object,​java.lang.Integer> sequence)
   throws ObjectStoreException
        Counts the number of rows the query will produce
        Parameters:
        q - InterMine Query on which to count rows
        sequence - an object representing the state of the database corresponding to when the action that resulted in this execute was started. This number must match the ObjectStore's internal sequence number or a DataChangedException is thrown. The sequence number is incremented each time the data in the objectstore is changed
        Returns:
        the number of rows that will be produced by query
        Throws:
        ObjectStoreException - if an error occurs counting the query

      • getModel

        Model getModel()
        Return the metadata associated with this ObjectStore
        Returns:
        the Model

      • getObjectByExample

        <T extends InterMineObject> T getObjectByExample​(T o,
                                                 java.util.Set<java.lang.String> fieldNames)
                                          throws ObjectStoreException
        Return an object from the objectstore that has the fields mentioned in the list set to the same values as the fields in the provided example object. If there are no objects in the objectstore like that, then this method returns null. If there are more than one object, then this method throws an IllegalArgumentException.
        Type Parameters:
        T - The actual type to return.
        Parameters:
        o - an example object
        fieldNames - a Set of fieldnames
        Returns:
        an InterMineObject from the objectstore, or null if none fits
        Throws:
        ObjectStoreException - if an underlying error occurs

      • getObjectsByExample

        <T extends InterMineObject> java.util.Collection<T> getObjectsByExample​(T o,
                                                                        java.util.Set<java.lang.String> fieldNames)
                                                                 throws ObjectStoreException
        Return an object from the objectstore that has the fields mentioned in the list set to the same values as the fields in the provided example object. If there are no objects in the objectstore like that, then this method returns null. If there are more than one object, then this method throws an IllegalArgumentException.
        Type Parameters:
        T - The actual type to return.
        Parameters:
        o - an example object
        fieldNames - a Set of fieldnames
        Returns:
        zero or more InterMineObjects from the objectstore
        Throws:
        ObjectStoreException - if an underlying error occurs

      • isMultiConnection

        boolean isMultiConnection()
        Return whether or not this ObjectStore gives a performance improvement when multiple simultaneous are made. Note that ALL Objectstore must be multi-threading safe. If this method returns true, then the ObjectStore probably handles multiple connections to the database. The Results class uses this to work out whether or not to do prefetching.
        Returns:
        true if one should do multiple simultaneous operations

      • getComponentsForQuery

        java.util.Set<java.lang.Object> getComponentsForQuery​(Query q)
        Returns a Set of independent components that affect the results of the given Query.
        Parameters:
        q - a Query
        Returns:
        a Set of objects

      • getSequence

        java.util.Map<java.lang.Object,​java.lang.Integer> getSequence​(java.util.Set<java.lang.Object> tables)
        Return the sequence number representing the state of the ObjectStore. This number is incremented each time the data in the ObjectStore is changed.
        Parameters:
        tables - a Set of independent database components to get data for
        Returns:
        an object representing the current database state

      • getMaxLimit

        int getMaxLimit()
        Get the maximum LIMIT that can be used in an SQL query without throwing an ObjectStoreLimitReachedException
        Returns:
        the maximum limit

      • getMaxOffset

        int getMaxOffset()
        Get the maximum range start index a that can be accessed in a Results object without throwing an ObjectStoreLimitReachedException
        Returns:
        the maximum offset

      • getMaxTime

        long getMaxTime()
        Get the maximum time a query may take before throwing an ObjectStoreQueryDurationException
        Returns:
        the maximum query time