Overview | Package | Class | Tree | Deprecated | Index | Help
| SolarMetric Kodo JDO 2.5.8 generated on January 11 2004
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.solarmetric.kodo.runtime
Interface StoreManager

All Known Implementing Classes:
  JDBCStoreManager, DataCacheStoreManager

public interface StoreManager

Interface to be implemented by data store mechanisms to interact with this JDO runtime.

Method Summary
`void` | `begin(boolean lock)` Begin a data store transaction.
`void` | `beginOptimistic()` Notification that an optimistic transaction has started.
`boolean` | `checkVersion(StateManagerImpl sm)` Determine whether the given StateManager is the same version as the datastore version.
`void` | `close()` Close any resources used by this store manager.
`void` | `commit()` Commit the current data store transaction.
`Object` | `copyDataStoreId(Object oid, ClassMetaData meta)` Copy the given object id value.
`boolean` | `exists(Object oid, ClassMetaData meta)` Verify that the given instance exists in the data store.
`Collection` | `flush(Collection states)` Flush the given state manager collection to the datastore, returning a collection of user exceptions encountered during flushing.
`Object` | `getDatastoreConnection()` Returns a connection to the data store suitable for use with `StoreManager` APIs that require a conneciton argument.
`Class` | `getDataStoreIdClass(ClassMetaData meta)` Return the class used by this StoreManager for datastore identity values.
`boolean` | `handlesMarkingFlushedFields()` Returns `true` if this store manager implementation takes responsibility for marking which fields are successfully flushed during `flush(java.util.Collection)`; otherwise returns `false`.
`boolean` | `initialize(StateManagerImpl sm, JDOState state, Object connection, Set fields)` Initialize the given StateManager.
`boolean` | `isActive()` Returns `true` if this store manager has an active transaction associated with it.
`boolean` | `isLocking()` Returns `true` if data loaded through this store manager will be locked on the data store side.
`boolean` | `isOnline()` Returns `true` if this store manager currently has a dedicated connection to the data store that it will keep until a well-defined boundary (transaction commit or PersistenceManager commit).
`void` | `load(StateManagerImpl sm, Object connection, Set fields, boolean setVersion)` Load the given StateManager.
`Object` | `newDataStoreId(ClassMetaData meta)` Create a new unique datastore identity for the given type.
`Object` | `newDataStoreId(String str, ClassMetaData meta)` Create a new unique datastore identity for the given type from the given string.
`KodoExtent` | `newExtent(Class candidate, boolean subclasses)` Return an extent of the given candidate class, optionally including subclasses.
`KodoExtent` | `newExtent(ClassMetaData meta, boolean subclasses)` Deprecated. use `newExtent(java.lang.Class,boolean)` instead
`com.solarmetric.kodo.query.KodoQuery` | `newQuery(String language, Object template)` Return a query implementation suitable for this runtime.
`void` | `releaseDatastoreConnection(Object o)` Releases a connection obtained through an invocation of `getDatastoreConnection()`.
`void` | `rollback()` Rollback the current data store transaction.
`void` | `setPersistenceManager(PersistenceManagerImpl pm)` Set a reference to the corresponding PersistenceManager.

Method Detail

### setPersistenceManager

    public void setPersistenceManager(PersistenceManagerImpl pm)

  Set a reference to the corresponding PersistenceManager. This method will be called before the StoreManager is used.

### beginOptimistic

    public void beginOptimistic()

  Notification that an optimistic transaction has started. This method does not replace the `begin(boolean)` method, which will still be called when a true data store transaction should begin.

### begin

    public void begin(boolean lock)

  Begin a data store transaction. If `lock` is `true`, designate that any data loaded through the store manager should be locked on the data store side. Otherwise, data loaded from the store manager will not be locked. After this method is invoked, any operations performed on this data store are considered to be performed within a single transactional context, and it should be possible to commit or roll back these changes at a later time.

  This method should be invoked before attempts to flush any data to the data store, at the latest. It is permissible for a store manager implementation to throw an exception in `flush(java.util.Collection)` if this method has not been invoked since the store manager was created or since the last `commit()` or `rollback()` invocation, whichever happened later.

  If optimistic transactions are in use, this method will not be called until the store manager needs to maintain a transactionally consistent connection to the data store. It is possible that the optimistic transaction does not have the latest versions of all instances (i.e. another transaction has modified the same instances and committed since the optimistic transaction started). On commit, an exception must be thrown on any attempt to overwrite data for an instance with an older version.

  Since:
    2.5.0

### commit

    public void commit()

  Commit the current data store transaction.

### rollback

    public void rollback()

  Rollback the current data store transaction.

### isActive

    public boolean isActive()

  Returns `true` if this store manager has an active transaction associated with it.
  Since:
    2.5.0

### isLocking

    public boolean isLocking()

  Returns `true` if data loaded through this store manager will be locked on the data store side.
  Since:
    2.5.0

### isOnline

    public boolean isOnline()

  Returns `true` if this store manager currently has a dedicated connection to the data store that it will keep until a well-defined boundary (transaction commit or PersistenceManager commit).
  Since:
    2.5.0

### getDatastoreConnection

    public Object getDatastoreConnection()

  Returns a connection to the data store suitable for use with `StoreManager` APIs that require a conneciton argument. If a transaction is not currently in progress, then the connection may not be associated with this store manager's transaction. If a transaction is in progress, it is guaranteed that the returned connection will be the same as that currently being used by the transaction.

### releaseDatastoreConnection

    public void releaseDatastoreConnection(Object o)

  Releases a connection obtained through an invocation of `getDatastoreConnection()`. If this store manager has a reserved connection, and the Connection argument is the same as the Connection that is currently in use, then no action will be taken. Otherwise, the connection will be closed.

### exists

    public boolean exists(Object oid,
                          ClassMetaData meta)

  Verify that the given instance exists in the data store.

### checkVersion

    public boolean checkVersion(StateManagerImpl sm)

  Determine whether the given StateManager is the same version as the datastore version.
  Parameters:
    `sm` - the instance to check
  Returns:
    true if the instance is up-to-date, false otherwise

### initialize

    public boolean initialize(StateManagerImpl sm,
                              JDOState state,
                              Object connection,
                              Set fields)

  Initialize the given StateManager. The `oid` of the StateManager will be set, and the `meta` field of the StateManager will be set to the class of the instance to load, or possibly one of its superclasses. Initialization involves first calling the `StateManagerImpl.initialize(javax.jdo.spi.PersistenceCapable, com.solarmetric.kodo.runtime.JDOState)` method with a new instance of the correct type constructed with the `JDOImplHelper.newInstance(java.lang.Class,javax.jdo.spi.StateManager,java.lang.Object)` method (this will reset the `meta` field of the StateManager if the actual type was a subclass), then possibly loading any fields if desired. The version information for the StateManager should also be set via the `StateManagerImpl.setVersion(java.lang.Object)` method. If this method is called during a data store transaction, the instance should be locked.
  Parameters:
    `sm` - the instance to initialize
    `state` - the JDO state to pass through to the state manager's initialize method
    `connection` - the current connection information, or null if not given to the calling method of the persistence manager
    `fields` - the fields to load. additional fields can be loaded if desired; attempting to load an additional field that has been dirtied will cause the load to be ignored; this bit set should not be modified
  Returns:
    true if the matching instance exists in the data store, false otherwise

### load

    public void load(StateManagerImpl sm,
                     Object connection,
                     Set fields,
                     boolean setVersion)

  Load the given StateManager. Note that any collection or map types loaded into the StateManager will be proxied with the correct type; therefore the StoreManager does not have to load the same concrete collection/map types as the instance declares. However, array types must be consistent with the array type stored by the PersistenceCapable instance. If this method is called during a data store transaction, the instance should be locked.
  Parameters:
    `sm` - the instance to load
    `connection` - the current connection information, or null if not given to the calling method of the persistence manager
    `fields` - the fields to load. additional fields can be loaded if desired; attempting to load an additional field that has been dirtied will cause the load to be ignored; this bit set should not be modified
    `setVersion` - if true, the version information should also be loaded from the db and set in the instance via the `StateManagerImpl.setVersion(java.lang.Object)` method

### flush

    public Collection flush(Collection states)

  Flush the given state manager collection to the datastore, returning a collection of user exceptions encountered during flushing. The given state collection may include states that do not require data store action, such as persistent-clean instances or persistent-dirty instances that have not been modified since they were last flushed. For datastore updates and inserts, the dirty, non-flushed fields of each state should be flushed. Datastore version information should be updated during flush, and the state manager's version indicator updated through the `StateManagerImpl.setNextVersion(java.lang.Object)` method. The current version will roll over to this next version upon successful commit.

  If `handlesMarkingFlushedFields()` returns `true`, then this method is responsible for marking which fields are successfully flushed to the data store. Otherwise, the `PersistenceManagerImpl` will mark all dirty fields in all flushed objects as flushed upon successful completion of this method. See `handlesMarkingFlushedFields()` for details.

### handlesMarkingFlushedFields

    public boolean handlesMarkingFlushedFields()

  Returns `true` if this store manager implementation takes responsibility for marking which fields are successfully flushed during `flush(java.util.Collection)`; otherwise returns `false`.

  It is preferable for implementations to return `true` from this method. If the store manager can mark those fields that are successfully flushed, then exceptions returned from `flush(java.util.Collection)` can be ignored, as the state of the objects will be consistent with the data store.

  If this method returns `false`, then the `PersistenceManagerImpl` will mark all dirty fields in all flushed objects as flushed after successful completion of `flush(java.util.Collection)`. If an exception is thrown during the flush, then the `PersistenceManagerImpl` will throw a `JDOFatalDataStoreException` and the transaction will be rolled back. The post-rollback values of the unsuccessfully flushed objects will be defined by the normal behavior of a rollback during a transaction commit.

  Since:
    2.5.0

### getDataStoreIdClass

    public Class getDataStoreIdClass(ClassMetaData meta)

  Return the class used by this StoreManager for datastore identity values.

### copyDataStoreId

    public Object copyDataStoreId(Object oid,
                                  ClassMetaData meta)

  Copy the given object id value.

### newDataStoreId

    public Object newDataStoreId(ClassMetaData meta)

  Create a new unique datastore identity for the given type.

### newDataStoreId

    public Object newDataStoreId(String str,
                                 ClassMetaData meta)

  Create a new unique datastore identity for the given type from the given string.

### newExtent

    public KodoExtent newExtent(ClassMetaData meta,
                                boolean subclasses)

  Deprecated. use `newExtent(java.lang.Class,boolean)` instead

  Return an extent of the given candidate class, optionally including subclasses. If the extent is iterated within a data store transaction, returned instances should be locked.

### newExtent

    public KodoExtent newExtent(Class candidate,
                                boolean subclasses)

  Return an extent of the given candidate class, optionally including subclasses. If the extent is iterated within a data store transaction, returned instances should be locked.
  Since:
    2.5

### newQuery

    public com.solarmetric.kodo.query.KodoQuery newQuery(String language,
                                                         Object template)

  Return a query implementation suitable for this runtime. If the query is iterated within a data store transaction, returned instances should be locked.
  Parameters:
    `the` - query language; implementations are only required to support `javax.jdo.query.JDOQL`
    `a` - template query instance also from this StoreManager; this instance may be null; if not null, the filter, variables, parameters, imports, and candidate class should be copied from the template to the returned Query instance

### close

    public void close()

  Close any resources used by this store manager. After this method has been invoked, all database resources held by the store manager will be released. However, it is still possible to use this StoreManager for nontransactional operations, potentially using different connection resources than were used for earlier operations.
  Since:
    2.5.0

Overview | Package | Class | Tree | Deprecated | Index | Help
| SolarMetric Kodo JDO 2.5.8 generated on January 11 2004
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright 2001,2002,2003 SolarMetric, Inc. All Rights Reserved.