org.intermine.objectstore
Interface ObjectStore

All Known Subinterfaces:

IntegrationWriter, ObjectStoreWriter

All Known Implementing Classes:

IntegrationWriterAbstractImpl, IntegrationWriterDataTrackingImpl, ObjectStoreAbstractImpl, ObjectStoreFastCollectionsForTranslatorImpl, ObjectStoreFastCollectionsImpl, ObjectStoreInterMineImpl, ObjectStorePassthruImpl, ObjectStoreSafeImpl, ObjectStoreTranslatingImpl, ObjectStoreWriterInterMineImpl

public interface ObjectStore

Gets the Results of a Query from an underlying store.

Field Summary

static java.util.Map<java.lang.Object,java.lang.Integer>

SEQUENCE_IGNORE Object representing no fail-fast concurrency checks required.

Method Summary

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.
InterMineObject	getObjectByExample(InterMineObject 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.
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

InterMineObject getObjectByExample(InterMineObject 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.

Parameters:

o - an example object

fieldNames - a Set of fieldnames

Returns:

a InterMineObject from the objectstore, or null if none fits

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

getSerial

java.lang.Integer getSerial()
                            throws ObjectStoreException

Gets an ID number which is unique in the database.

Returns:

an Integer

Throws:

ObjectStoreException - if a problem occurs

createObjectStoreBag

ObjectStoreBag createObjectStoreBag()
                                    throws ObjectStoreException

Returns a new empty ObjectStoreBag object that is valid for this ObjectStore.

Returns:

an ObjectStoreBag

Throws:

ObjectStoreException - if an error occurs fetching a new ID

createClob

Clob createClob()
                throws ObjectStoreException

Creates a new empty Clob that is valid for this ObjectStore.

Returns:

a Clob

Throws:

ObjectStoreException - if an error occurs fetching a new ID