Interface StoreManager

All Known Implementing Classes:
AbstractStoreManager, FederatedStoreManager

public interface StoreManager
Interface defining management of a datastore. To be implemented by all new datastore support. Please use AbstractStoreManager and extend it. All StoreManagers should have a single constructor with signature
 public MyStoreManager(ClassLoaderResolver clr, NucleusContext ctx, Map<String, Object> props)
 {
 }
 
The constructor arguments are
  • ClassLoader Resolver, for assistance in any class loading needed.
  • The context where the StoreManager is being used, providing services like metadata, etc
  • Any persistence properties that are defined for the store, to configure schema generation etc
See also AbstractStoreManager which provides something that can be extended, simplifying the process of implementing a StoreManager; note that the first argument of the constructor to AbstractStoreManager is the "key" for your StoreManager (e.g ODF has "odf" as its key, RDBMS has "rdbms").
  • Field Details

    • OPTION_APPLICATION_ID

      static final String OPTION_APPLICATION_ID
      Whether the store supports persistence of "application" identity.
      See Also:
    • OPTION_APPLICATION_COMPOSITE_ID

      static final String OPTION_APPLICATION_COMPOSITE_ID
      Whether the store supports persistence of composite "application" identity.
      See Also:
    • OPTION_DATASTORE_ID

      static final String OPTION_DATASTORE_ID
      Whether the store supports persistence of "datastore" identity.
      See Also:
    • OPTION_NONDURABLE_ID

      static final String OPTION_NONDURABLE_ID
      Whether the store supports persistence of "non-durable" identity.
      See Also:
    • OPTION_ORM

      static final String OPTION_ORM
      Whether the store supports "ORM" concepts in general.
      See Also:
    • OPTION_ORM_EMBEDDED_PC

      static final String OPTION_ORM_EMBEDDED_PC
      Whether the store supports embedding PC objects (into the owning objects datastore representation).
      See Also:
    • OPTION_ORM_EMBEDDED_COLLECTION

      static final String OPTION_ORM_EMBEDDED_COLLECTION
      Whether the store supports embedding collections (into the owning objects datastore representation).
      See Also:
    • OPTION_ORM_EMBEDDED_MAP

      static final String OPTION_ORM_EMBEDDED_MAP
      Whether the store supports embedding maps (into the owning objects datastore representation).
      See Also:
    • OPTION_ORM_EMBEDDED_ARRAY

      static final String OPTION_ORM_EMBEDDED_ARRAY
      Whether the store supports embedding arrays (into the owning objects datastore representation).
      See Also:
    • OPTION_ORM_EMBEDDED_PC_NESTED

      static final String OPTION_ORM_EMBEDDED_PC_NESTED
      Whether the embedded object is storable nested like in JSON (default is flat embedding).
      See Also:
    • OPTION_ORM_EMBEDDED_COLLECTION_NESTED

      static final String OPTION_ORM_EMBEDDED_COLLECTION_NESTED
      Whether the embedded element is storable nested like in JSON (default is in separate table).
      See Also:
    • OPTION_ORM_EMBEDDED_MAP_NESTED

      static final String OPTION_ORM_EMBEDDED_MAP_NESTED
      Whether the embedded element is storable nested like in JSON (default is in separate table).
      See Also:
    • OPTION_ORM_EMBEDDED_ARRAY_NESTED

      static final String OPTION_ORM_EMBEDDED_ARRAY_NESTED
      Whether the embedded key/value is storable nested like in JSON (default is in separate table).
      See Also:
    • OPTION_ORM_SERIALISED_PC

      static final String OPTION_ORM_SERIALISED_PC
      Whether the store supports serialisation of a PC into a "column".
      See Also:
    • OPTION_ORM_SERIALISED_COLLECTION_ELEMENT

      static final String OPTION_ORM_SERIALISED_COLLECTION_ELEMENT
      Whether the store supports serialisation of a collection element into a "column".
      See Also:
    • OPTION_ORM_SERIALISED_MAP_KEY

      static final String OPTION_ORM_SERIALISED_MAP_KEY
      Whether the store supports serialisation of a map key into a "column".
      See Also:
    • OPTION_ORM_SERIALISED_MAP_VALUE

      static final String OPTION_ORM_SERIALISED_MAP_VALUE
      Whether the store supports serialisation of a map value into a "column".
      See Also:
    • OPTION_ORM_SERIALISED_ARRAY_ELEMENT

      static final String OPTION_ORM_SERIALISED_ARRAY_ELEMENT
      Whether the store supports serialisation of a array element into a "column".
      See Also:
    • OPTION_ORM_SECONDARY_TABLE

      static final String OPTION_ORM_SECONDARY_TABLE
      Whether the store supports "secondary tables".
      See Also:
    • OPTION_ORM_FOREIGN_KEYS

      static final String OPTION_ORM_FOREIGN_KEYS
      Whether the store supports "foreign keys".
      See Also:
    • OPTION_ORM_INHERITANCE_COMPLETE_TABLE

      static final String OPTION_ORM_INHERITANCE_COMPLETE_TABLE
      Whether the store supports "complete table" inheritance.
      See Also:
    • OPTION_ORM_INHERITANCE_SINGLE_TABLE

      static final String OPTION_ORM_INHERITANCE_SINGLE_TABLE
      Whether the store supports "single table" inheritance.
      See Also:
    • OPTION_ORM_INHERITANCE_JOINED_TABLE

      static final String OPTION_ORM_INHERITANCE_JOINED_TABLE
      Whether the store supports "joined table" inheritance.
      See Also:
    • OPTION_TRANSACTION_ACID

      static final String OPTION_TRANSACTION_ACID
      Whether the store supports ACID transactions.
      See Also:
    • OPTION_TXN_ISOLATION_READ_COMMITTED

      static final String OPTION_TXN_ISOLATION_READ_COMMITTED
      Whether the store supports "read-committed" transaction isolation.
      See Also:
    • OPTION_TXN_ISOLATION_READ_UNCOMMITTED

      static final String OPTION_TXN_ISOLATION_READ_UNCOMMITTED
      Whether the store supports "read-uncommitted" transaction isolation.
      See Also:
    • OPTION_TXN_ISOLATION_REPEATABLE_READ

      static final String OPTION_TXN_ISOLATION_REPEATABLE_READ
      Whether the store supports "repeatable-read" transaction isolation.
      See Also:
    • OPTION_TXN_ISOLATION_SERIALIZABLE

      static final String OPTION_TXN_ISOLATION_SERIALIZABLE
      Whether the store supports "serializable" transaction isolation.
      See Also:
    • OPTION_QUERY_CANCEL

      static final String OPTION_QUERY_CANCEL
      Whether the store supports cancellation of queries once started.
      See Also:
    • OPTION_QUERY_JDOQL_BULK_INSERT

      static final String OPTION_QUERY_JDOQL_BULK_INSERT
      Whether the store supports JDOQL queries performing "bulk" INSERT of data.
      See Also:
    • OPTION_QUERY_JDOQL_BULK_UPDATE

      static final String OPTION_QUERY_JDOQL_BULK_UPDATE
      Whether the store supports JDOQL queries performing "bulk" UPDATE of data.
      See Also:
    • OPTION_QUERY_JDOQL_BULK_DELETE

      static final String OPTION_QUERY_JDOQL_BULK_DELETE
      Whether the store supports JDOQL queries performing "bulk" DELETE of data.
      See Also:
    • OPTION_QUERY_JDOQL_BITWISE_OPS

      static final String OPTION_QUERY_JDOQL_BITWISE_OPS
      Whether the store supports use of "bitwise" operations in JDOQL queries.
      See Also:
    • OPTION_QUERY_JPQL_BULK_INSERT

      static final String OPTION_QUERY_JPQL_BULK_INSERT
      Whether the store supports JPQL queries performing "bulk" INSERT of data.
      See Also:
    • OPTION_QUERY_JPQL_BULK_UPDATE

      static final String OPTION_QUERY_JPQL_BULK_UPDATE
      Whether the store supports JPQL queries performing "bulk" UPDATE of data.
      See Also:
    • OPTION_QUERY_JPQL_BULK_DELETE

      static final String OPTION_QUERY_JPQL_BULK_DELETE
      Whether the store supports JPQL queries performing "bulk" DELETE of data.
      See Also:
    • OPTION_DATASTORE_TIMEOUT

      static final String OPTION_DATASTORE_TIMEOUT
      Whether the store supports specification of a timeout on datastore operations.
      See Also:
    • OPTION_DATASTORE_TIME_STORES_MILLISECS

      static final String OPTION_DATASTORE_TIME_STORES_MILLISECS
      Whether the store will persist milliseconds when persisting a "time" type.
      See Also:
    • OPTION_DATASTORE_TIME_STORES_NANOSECS

      static final String OPTION_DATASTORE_TIME_STORES_NANOSECS
      Whether the store will persist nanoseconds when persisting a "time" type.
      See Also:
    • RELATION_IDENTITY_STORAGE_PERSISTABLE_IDENTITY

      static final String RELATION_IDENTITY_STORAGE_PERSISTABLE_IDENTITY
      See Also:
  • Method Details

    • getSupportedOptions

      Collection<String> getSupportedOptions()
      Strings representing features that are supported by this datastore. Refer to the Strings in org.datanucleus.store.StoreManager with prefix "OPTION_".
      Returns:
      The supported options
    • close

      void close()
    • isClosed

      boolean isClosed()
    • getMetaDataManager

      MetaDataManager getMetaDataManager()
    • getPersistenceHandler

      StorePersistenceHandler getPersistenceHandler()
    • getFlushProcess

      FlushProcess getFlushProcess()
    • getQueryManager

      QueryManager getQueryManager()
    • getNamingFactory

      NamingFactory getNamingFactory()
    • getSchemaHandler

      StoreSchemaHandler getSchemaHandler()
    • getDefaultCatalogName

      default String getDefaultCatalogName()
      Method to return the default "catalog" name for this datastore, if it supports the concept. With most RDBMS, when we just issue an INSERT statement it will be created in the default catalog/schema for the connection.
      Returns:
      Default catalog name
    • getDefaultSchemaName

      default String getDefaultSchemaName()
      Method to return the default "schema" name for this datastore, if it supports the concept. With most RDBMS, when we just issue an INSERT statement it will be created in the default catalog/schema for the connection.
      Returns:
      Default schema name
    • getStoreDataForClass

      StoreData getStoreDataForClass(String className)
    • getNucleusSequence

      default NucleusSequence getNucleusSequence(ExecutionContext ec, SequenceMetaData seqmd)
      Method to return a datastore sequence for this datastore matching the passed sequence MetaData.
      Parameters:
      ec - execution context
      seqmd - SequenceMetaData
      Returns:
      The Sequence
    • getNucleusConnection

      NucleusConnection getNucleusConnection(ExecutionContext ec)
      Method to return a connection to the user for the ExecutionContext. Typically provides a wrapper to the currently in-use ManagedConnection.
      Parameters:
      ec - execution context
      Returns:
      The datastore Connection
    • getConnectionManager

      ConnectionManager getConnectionManager()
      Accessor for the connection manager for this store manager.
      Returns:
      connection manager
    • getConnectionURL

      default String getConnectionURL()
      Convenience accessor for the URL for the connections.
      Returns:
      connection URL
    • getConnectionUserName

      default String getConnectionUserName()
      Convenience accessor for the user name to use for the connections (where required).
      Returns:
      user name
    • getConnectionPassword

      String getConnectionPassword()
      Convenience accessor for the password to use for the connections (where required).
      Returns:
      Password
    • getConnectionDriverName

      default String getConnectionDriverName()
      Convenience accessor for the driver name to use for the connections (where supported).
      Returns:
      driver name
    • getConnectionFactory

      default Object getConnectionFactory()
      Convenience accessor for the primary connection factory (when a factory was provided by the user).
      Returns:
      Connection Factory (primary)
    • getConnectionFactoryName

      default String getConnectionFactoryName()
      Convenience accessor for the factory (JNDI) name for the primary connection factory (when provided by the user).
      Returns:
      Connection Factory name (primary)
    • getConnectionFactory2

      default Object getConnectionFactory2()
      Convenience accessor for the secondary connection factory (when a factory was provided by the user).
      Returns:
      Connection Factory (secondary)
    • getConnectionFactory2Name

      default String getConnectionFactory2Name()
      Convenience accessor for the factory (JNDI) name for the secondary connection factory (when provided by the user).
      Returns:
      Connection Factory name (secondary)
    • getValueGenerationManager

      ValueGenerationManager getValueGenerationManager()
      Accessor for the ValueGenerationManager for generating field values.
      Returns:
      The ValueGenerationManager for this datastore
    • supportsValueGenerationStrategy

      boolean supportsValueGenerationStrategy(String strategy)
      Accessor for whether this value generation strategy is supported.
      Parameters:
      strategy - The value generation strategy
      Returns:
      Whether it is supported.
    • isValueGenerationStrategyDatastoreAttributed

      boolean isValueGenerationStrategyDatastoreAttributed(AbstractClassMetaData cmd, int absFieldNumber)
      Convenience method to return whether the value generation strategy used by the specified class/member is generated in the datastore during a persist.
      Parameters:
      cmd - Metadata for the class
      absFieldNumber - number of the field (or -1 if for datastore-id)
      Returns:
      if the object for the value generation strategy is attributed by the database ("identity", etc)
    • getValueGenerationStrategyValue

      Object getValueGenerationStrategyValue(ExecutionContext ec, AbstractClassMetaData cmd, AbstractMemberMetaData mmd)
      Method to retrieve the value for a value generation strategy for a particular field or datastore-identity.
      Parameters:
      ec - execution context
      cmd - AbstractClassMetaData for the class
      mmd - MetaData for the member when this is for a member (or null for datastore-identity)
      Returns:
      The generated value
    • getValueGenerationStrategyForNative

      String getValueGenerationStrategyForNative(AbstractClassMetaData cmd)
      Method defining which value-strategy to use when the user specifies "native"/"auto" on datastore-identity.
      Parameters:
      cmd - Class requiring the strategy
      Returns:
      The value generation strategy used when "native"/"auto" is specified
    • getValueGenerationStrategyForNative

      String getValueGenerationStrategyForNative(AbstractMemberMetaData mmd)
      Method defining which value-strategy to use when the user specifies "native"/"auto" on a member
      Parameters:
      mmd - Member requiring the strategy
      Returns:
      The value generation strategy used when "native"/"auto" is specified
    • getApiAdapter

      ApiAdapter getApiAdapter()
      Accessor for the API adapter.
      Returns:
      API adapter
    • getStoreManagerKey

      String getStoreManagerKey()
      Accessor for the key for this store manager.
      Returns:
      StoreManager key
    • getQueryCacheKey

      default String getQueryCacheKey()
      Accessor for the key used for representing this store manager in the query cache.
      Returns:
      Key for the query cache
    • getNucleusContext

      PersistenceNucleusContext getNucleusContext()
      Accessor for the context in which this StoreManager is running.
      Returns:
      Returns the context.
    • getDatastoreDate

      default Date getDatastoreDate()
      Get the date/time of the datastore.
      Returns:
      Date/time of the datastore
    • isJdbcStore

      boolean isJdbcStore()
      Returns whether the datastore is a "JDBC datastore". If it is then the JDO spec needs to return a connection that implements java.sql.Connection. RDBMS is the only one that will return true from here (or certainly as we can foresee now).
      Returns:
      Whether this is a JDBC datastore
    • printInformation

      void printInformation(String cat, PrintStream ps) throws Exception
      Method to output particular information owned by this datastore. Each StoreManager can support whichever categories it likes.
      Parameters:
      cat - Category of information
      ps - PrintStream
      Throws:
      Exception - Thrown if an error occurs in the output process
    • useBackedSCOWrapperForMember

      boolean useBackedSCOWrapperForMember(AbstractMemberMetaData mmd, ExecutionContext ec)
      Method to return whether the specified member should use a backed SCO wrapper.
      Parameters:
      mmd - Metadata for the member
      ec - ExecutionContext
      Returns:
      Whether to use a back SCO wrapper (false means use a simple SCO wrapper).
    • managesClass

      boolean managesClass(String className)
      Accessor for whether the specified class is managed currently
      Parameters:
      className - The name of the class
      Returns:
      Whether it is managed
    • manageClasses

      void manageClasses(ClassLoaderResolver clr, String... classNames)
      Manage the specified classes. This method is primarily useful for applications that wish to perform all of their datastore initialization up front, rather than wait for the runtime to do it on-demand.
      Parameters:
      clr - The ClassLoaderResolver
      classNames - The class(es) to be managed
      Throws:
      DatastoreValidationException - If there is some mismatch between the current datastore contents and those necessary to enable persistence of the given classes.
    • unmanageClass

      void unmanageClass(ClassLoaderResolver clr, String className, boolean removeFromDatastore)
      Method to remove knowledge of the specified class from this StoreManager. This can optionally also remove it from the datastore.
      Parameters:
      clr - ClassLoader resolver
      className - Name of the class
      removeFromDatastore - Whether to also remove it from the datastore (otherwise just from the StoreManager)
    • unmanageAllClasses

      void unmanageAllClasses(ClassLoaderResolver clr)
      Remove all classes from the persistence model for the datastore. This empties the datastore of all datastore objects managed by us. All objects of types not managed are left untouched. In the case of RDBMS this means drop all tables for types managed by us.
      Parameters:
      clr - The ClassLoaderResolver
    • manageClassForIdentity

      String manageClassForIdentity(Object id, ClassLoaderResolver clr)
      Convenience method to ensure that the class defined by the passed DatastoreId/SingleFieldId is managed by the store.
      Parameters:
      id - identity
      clr - ClassLoader resolver
      Returns:
      The class name of the class associated to this identity
      Throws:
      NucleusUserException - if the identity is assigned to the wrong class
    • getExtent

      <T> Extent<T> getExtent(ExecutionContext ec, Class<T> c, boolean subclasses)
      Interface to getting an Extent for a class.
      Type Parameters:
      T - Type of the extent
      Parameters:
      ec - execution context
      c - The class requiring the Extent
      subclasses - Whether to include subclasses of 'c'
      Returns:
      The Extent.
    • getSupportedQueryLanguages

      Collection<String> getSupportedQueryLanguages()
      Accessor for the supported query languages.
      Returns:
      The supported query languages
    • supportsQueryLanguage

      boolean supportsQueryLanguage(String language)
      Accessor for whether this query language is supported.
      Parameters:
      language - The language
      Returns:
      Whether it is supported.
    • newQuery

      Query newQuery(String language, ExecutionContext ec)
      Method to return a new query, for the specified language and ExecutionContext.
      Parameters:
      language - The query language
      ec - ExecutionContext
      Returns:
      The query
    • newQuery

      Query newQuery(String language, ExecutionContext ec, String queryString)
      Method to return a new query, for the specified language and ExecutionContext, using the specified query string.
      Parameters:
      language - The query language
      ec - ExecutionContext
      queryString - The query string
      Returns:
      The query
    • newQuery

      Query newQuery(String language, ExecutionContext ec, Query q)
      Method to return a new query, for the specified language and ExecutionContext, using the specified existing query to copy from.
      Parameters:
      language - The query language
      ec - ExecutionContext
      q - Existing query
      Returns:
      The query
    • getNativeQueryLanguage

      default String getNativeQueryLanguage()
      Accessor for the native query language of this store.
      Returns:
      The native query language (e.g "SQL")
    • getClassNameForObjectID

      String getClassNameForObjectID(Object id, ClassLoaderResolver clr, ExecutionContext ec)
      Returns the class corresponding to the given object identity. If the object is datastore-identity, return the PC class specified in the identity. If the object is single-field identity, return the PC class specified in the identity If the object is an AppID PK, return the PC class that uses it. If the object is a SCOID, return the SCO class. If the object is a persistable class, return the class.
      Parameters:
      id - The identity of some object.
      clr - ClassLoader resolver
      ec - execution context
      Returns:
      For datastore identity, return the class of the corresponding object. For application identity, return the class of the corresponding object or null if object does not exist.
      Throws:
      ClassCastException - If the type of ID is not recognized
    • getSubClassesForClass

      Collection<String> getSubClassesForClass(String className, boolean includeDescendents, ClassLoaderResolver clr)
      Utility to return the names of the classes that are known subclasses of the provided class. Actually uses the MetaDataManager for determining what is a subclass since the MetaData is often registered before being needed by the Store. The important difference is that this method will then register the subclass as required
      Parameters:
      className - Class for which we search for subclasses.
      includeDescendents - Whether to include subclasses of subclasses etc
      clr - The ClassLoaderResolver
      Returns:
      Set of classes that are subclasses of the input class.
    • getProperty

      Object getProperty(String name)
    • hasProperty

      boolean hasProperty(String name)
    • getIntProperty

      int getIntProperty(String name)
    • getBooleanProperty

      boolean getBooleanProperty(String name)
    • getBooleanProperty

      boolean getBooleanProperty(String name, boolean resultIfNotSet)
    • getBooleanObjectProperty

      Boolean getBooleanObjectProperty(String name)
    • getStringProperty

      String getStringProperty(String name)
    • enableSchemaGeneration

      void enableSchemaGeneration()
      Convenience method to override the specified schema generation properties and enable schema generation.
    • resetSchemaGeneration

      void resetSchemaGeneration()
      Convenience method to reset the schema generation properties to their initial creation values, effectively undoing a call to enableSchemaGeneration.
    • transactionStarted

      default void transactionStarted(ExecutionContext ec)
      Method to inform the StoreManager that a transaction has started for the specified execution context. This allows the StoreManager to initialise any objects as required.
      Parameters:
      ec - ExecutionContext
    • transactionCommitted

      default void transactionCommitted(ExecutionContext ec)
      Method to inform the StoreManager that a transaction has committed for the specified execution context. This allows the StoreManager to close any objects as required.
      Parameters:
      ec - ExecutionContext
    • transactionRolledBack

      default void transactionRolledBack(ExecutionContext ec)
      Method to inform the StoreManager that a transaction has rolled back for the specified execution context. This allows the StoreManager to close any objects as required.
      Parameters:
      ec - ExecutionContext
    • getDefaultStateManagerClassName

      String getDefaultStateManagerClassName()
    • usesBackedSCOWrappers

      default boolean usesBackedSCOWrappers()
      Whether this store manager uses backing-store based SCO wrappers.
      Returns:
      Whether this store provides backing stores for SCO wrappers.