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 Detail

      • OPTION_APPLICATION_ID

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

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

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

        static final String OPTION_NONDURABLE_ID
        Whether the store supports persistence of "non-durable" identity.
        See Also:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • OPTION_ORM_SERIALISED_PC

        static final String OPTION_ORM_SERIALISED_PC
        Whether the store supports serialisation of a PC into a "column".
        See Also:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • OPTION_ORM_SECONDARY_TABLE

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

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

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

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

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

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

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

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

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

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

        static final String OPTION_QUERY_CANCEL
        Whether the store supports cancellation of queries once started.
        See Also:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • OPTION_DATASTORE_TIMEOUT

        static final String OPTION_DATASTORE_TIMEOUT
        Whether the store supports specification of a timeout on datastore operations.
        See Also:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • RELATION_IDENTITY_STORAGE_PERSISTABLE_IDENTITY

        static final String RELATION_IDENTITY_STORAGE_PERSISTABLE_IDENTITY
        See Also:
        Constant Field Values
    • Method Detail

      • 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()
      • 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.
      • 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.