path: root/lang/java/src/com/sleepycat/persist/EntityStore.java

/*-
 * See the file LICENSE for redistribution information.
 *
 * Copyright (c) 2002, 2015 Oracle and/or its affiliates.  All rights reserved.
 *
 */

package com.sleepycat.persist;

import java.io.Closeable;
import java.util.Set;

import com.sleepycat.db.Database; // for javadoc
import com.sleepycat.db.DatabaseConfig;
import com.sleepycat.db.DatabaseException;
import com.sleepycat.db.Environment;
import com.sleepycat.db.SecondaryConfig;
import com.sleepycat.db.Sequence;
import com.sleepycat.db.SequenceConfig;
import com.sleepycat.db.Transaction;
import com.sleepycat.persist.evolve.EvolveConfig;
import com.sleepycat.persist.evolve.EvolveStats;
import com.sleepycat.persist.evolve.IncompatibleClassException;
import com.sleepycat.persist.evolve.Mutations;
import com.sleepycat.persist.impl.Store;
import com.sleepycat.persist.model.DeleteAction;
import com.sleepycat.persist.model.Entity; // for javadoc
import com.sleepycat.persist.model.EntityModel;
import com.sleepycat.persist.model.PrimaryKey;
import com.sleepycat.persist.model.SecondaryKey;

/**
 * A store for managing persistent entity objects.
 *
 * <p>{@code EntityStore} objects are thread-safe.  Multiple threads may safely
 * call the methods of a shared {@code EntityStore} object.</p>
 *
 * <p>See the {@link <a href="package-summary.html#example">package
 * summary example</a>} for an example of using an {@code EntityStore}.</p>
 *
 * <p>Before creating an <code>EntityStore</code> you must create an {@link
 * Environment} object using the Berkeley DB engine API.  The environment may
 * contain any number of entity stores and their associated databases, as well
 * as other databases not associated with an entity store.</p>
 *
 * <p>An entity store is based on an {@link EntityModel}: a data model which
 * defines persistent classes (<em>entity classes</em>), primary keys,
 * secondary keys, and relationships between entities.  A primary index is
 * created for each entity class.  An associated secondary index is created for
 * each secondary key.  The {@link Entity}, {@link PrimaryKey} and {@link
 * SecondaryKey} annotations may be used to define entities and keys.</p>
 *
 * <p>To use an <code>EntityStore</code>, first obtain {@link PrimaryIndex} and
 * {@link SecondaryIndex} objects by calling {@link #getPrimaryIndex
 * getPrimaryIndex} and {@link #getSecondaryIndex getSecondaryIndex}.  Then use
 * these indices to store and access entity records by key.</p>
 *
 * <p>Although not normally needed, you can also use the entity store along
 * with the {@link com.sleepycat.db Base API}.  Methods in the {@link
 * PrimaryIndex} and {@link SecondaryIndex} classes may be used to obtain
 * databases and bindings.  The databases may be used directly for accessing
 * entity records.  The bindings should be called explicitly to translate
 * between {@link com.sleepycat.db.DatabaseEntry} objects and entity model
 * objects.</p>
 *
 * <p>Each primary and secondary index is associated internally with a {@link
 * Database}.  With any of the above mentioned use cases, methods are provided
 * that may be used for database performance tuning.  The {@link
 * #setPrimaryConfig setPrimaryConfig} and {@link #setSecondaryConfig
 * setSecondaryConfig} methods may be called anytime before a database is
 * opened via {@link #getPrimaryIndex getPrimaryIndex} or {@link
 * #getSecondaryIndex getSecondaryIndex}.  The {@link #setSequenceConfig
 * setSequenceConfig} method may be called anytime before {@link #getSequence
 * getSequence} is called or {@link #getPrimaryIndex getPrimaryIndex} is called
 * for a primary index associated with that sequence.</p>
 *
 *
 * @author Mark Hayes
 */
public class EntityStore
    {

    private Store store;

    /**
     * Opens an entity store in a given environment.
     *
     * @param env an open Berkeley DB Environment.
     *
     * @param storeName the name of the entity store within the given
     * environment.  An empty string is allowed.  Named stores may be used to
     * distinguish multiple sets of persistent entities for the same entity
     * classes in a single environment.  Underlying database names are prefixed
     * with the store name.
     *
     * @param config the entity store configuration, or null to use default
     * configuration properties.
     *
     * @throws IncompatibleClassException if an incompatible class change has
     * been made and mutations are not configured for handling the change.  See
     * {@link com.sleepycat.persist.evolve Class Evolution} for more
     * information.
     *
     *
     * @throws DatabaseException the base class for all BDB exceptions.
     */
    public EntityStore(Environment env, String storeName, StoreConfig config)
        throws StoreExistsException,
               StoreNotFoundException,
               IncompatibleClassException,
               DatabaseException {

        store = new Store(env, storeName, config, false /*rawAccess*/);
    }

    /**
     * Returns the environment associated with this store.
     *
     * @return the environment.
     */
    public Environment getEnvironment() {
        return store.getEnvironment();
    }

    /**
     * Returns a copy of the entity store configuration.
     *
     * @return the config.
     */
    public StoreConfig getConfig() {
        return store.getConfig();
    }

    /**
     * Returns the name of this store.
     *
     * @return the name.
     */
    public String getStoreName() {
        return store.getStoreName();
    }

    

    /**
     * Returns the current entity model for this store.  The current model is
     * derived from the configured entity model and the live entity class
     * definitions.
     *
     * @return the model.
     */
    public EntityModel getModel() {
        return store.getModel();
    }

    /**
     * Returns the set of mutations that were configured when the store was
     * opened, or if none were configured, the set of mutations that were
     * configured and stored previously.
     *
     * @return the mutations.
     */
    public Mutations getMutations() {
        return store.getMutations();
    }

    /**
     * Returns the primary index for a given entity class, opening it if
     * necessary.
     *
     * <p>If they are not already open, the primary and secondary databases for
     * the entity class are created/opened together in a single internal
     * transaction.  When the secondary indices are opened, that can cascade to
     * open other related primary indices.</p>
     *
     * @param primaryKeyClass the class of the entity's primary key field, or
     * the corresponding primitive wrapper class if the primary key field type
     * is a primitive.
     *
     * @param entityClass the entity class for which to open the primary index.
     *
     * @return the primary index.
     *
     * @throws IllegalArgumentException if the entity class or classes
     * referenced by it are not persistent, or the primary key class does not
     * match the entity's primary key field, or if metadata for the entity or
     * primary key is invalid.
     *
     *
     * @throws DatabaseException the base class for all BDB exceptions.
     */
    public <PK, E> PrimaryIndex<PK, E>
        getPrimaryIndex(Class<PK> primaryKeyClass, Class<E> entityClass)
        throws DatabaseException {

        try {
            return store.getPrimaryIndex
                (primaryKeyClass, primaryKeyClass.getName(),
                 entityClass, entityClass.getName());
        } catch (IndexNotAvailableException e) {
            if (!store.attemptRefresh()) {
                throw e;
            }
            return store.getPrimaryIndex
                (primaryKeyClass, primaryKeyClass.getName(),
                 entityClass, entityClass.getName());
        }
    }

    /**
     * Returns a secondary index for a given primary index and secondary key,
     * opening it if necessary.
     *
     * <p><em>NOTE:</em> If the secondary key field is declared in a subclass
     * of the entity class, use {@link #getSubclassIndex} instead.</p>
     *
     * <p>If a {@link SecondaryKey#relatedEntity} is used and the primary index
     * for the related entity is not already open, it will be opened by this
     * method.  That will, in turn, open its secondary indices, which can
     * cascade to open other primary indices.</p>
     *
     * @param primaryIndex the primary index associated with the returned
     * secondary index.  The entity class of the primary index, or one of its
     * superclasses, must contain a secondary key with the given secondary key
     * class and key name.
     *
     * @param keyClass the class of the secondary key field, or the
     * corresponding primitive wrapper class if the secondary key field type is
     * a primitive.
     *
     * @param keyName the name of the secondary key field, or the {@link
     * SecondaryKey#name} if this name annotation property was specified.
     *
     * @return the secondary index.
     *
     * @throws IllegalArgumentException if the entity class or one of its
     * superclasses does not contain a key field of the given key class and key
     * name, or if the metadata for the secondary key is invalid.
     *
     *
     * @throws DatabaseException the base class for all BDB exceptions.
     */
    public <SK, PK, E> SecondaryIndex<SK, PK, E>
        getSecondaryIndex(PrimaryIndex<PK, E> primaryIndex,
                          Class<SK> keyClass,
                          String keyName)
        throws DatabaseException {

        try {
            return store.getSecondaryIndex
                (primaryIndex, primaryIndex.getEntityClass(),
                 primaryIndex.getEntityClass().getName(),
                 keyClass, keyClass.getName(), keyName);
        } catch (IndexNotAvailableException e) {
            if (!store.attemptRefresh()) {
                throw e;
            }
            return store.getSecondaryIndex
                (primaryIndex, primaryIndex.getEntityClass(),
                 primaryIndex.getEntityClass().getName(),
                 keyClass, keyClass.getName(), keyName);
        }
    }

    /**
     * Returns a secondary index for a secondary key in an entity subclass,
     * opening it if necessary.
     *
     * <p>If a {@link SecondaryKey#relatedEntity} is used and the primary index
     * for the related entity is not already open, it will be opened by this
     * method.  That will, in turn, open its secondary indices, which can
     * cascade to open other primary indices.</p>
     *
     * @param primaryIndex the primary index associated with the returned
     * secondary index.  The entity class of the primary index, or one of its
     * superclasses, must contain a secondary key with the given secondary key
     * class and key name.
     *
     * @param entitySubclass a subclass of the entity class for the primary
     * index.  The entity subclass must contain a secondary key with the given
     * secondary key class and key name.
     *
     * @param keyClass the class of the secondary key field, or the
     * corresponding primitive wrapper class if the secondary key field type is
     * a primitive.
     *
     * @param keyName the name of the secondary key field, or the {@link
     * SecondaryKey#name} if this name annotation property was specified.
     *
     * @return the secondary index.
     *
     * @throws IllegalArgumentException if the given entity subclass does not
     * contain a key field of the given key class and key name, or if the
     * metadata for the secondary key is invalid.
     *
     *
     * @throws DatabaseException the base class for all BDB exceptions.
     */
    public <SK, PK, E1, E2 extends E1> SecondaryIndex<SK, PK, E2>
        getSubclassIndex(PrimaryIndex<PK, E1> primaryIndex,
                         Class<E2> entitySubclass,
                         Class<SK> keyClass,
                         String keyName)
        throws DatabaseException {

        /* Make subclass metadata available before getting the index. */
        getModel().getClassMetadata(entitySubclass.getName());

        try {
            return store.getSecondaryIndex
                (primaryIndex, entitySubclass,
                 primaryIndex.getEntityClass().getName(),
                 keyClass, keyClass.getName(), keyName);
        } catch (IndexNotAvailableException e) {
            if (!store.attemptRefresh()) {
                throw e;
            }
            return store.getSecondaryIndex
                (primaryIndex, entitySubclass,
                 primaryIndex.getEntityClass().getName(),
                 keyClass, keyClass.getName(), keyName);
        }
    }

    /**
     * Performs conversion of unevolved objects in order to reduce lazy
     * conversion overhead.  Evolution may be performed concurrently with
     * normal access to the store.
     *
     * <p>Conversion is performed one entity class at a time.  An entity class
     * is converted only if it has {@link Mutations} associated with it via
     * {@link StoreConfig#setMutations StoreConfig.setMutations}.</p>
     *
     * <p>Conversion of an entity class is performed by reading each entity,
     * converting it if necessary, and updating it if conversion was performed.
     * When all instances of an entity class are converted, references to the
     * appropriate {@link Mutations} are deleted.  Therefore, if this method is
     * called twice successfully without changing class definitions, the second
     * call will do nothing.</p>
     *
     *
     * @throws DatabaseException the base class for all BDB exceptions.
     *
     * @see com.sleepycat.persist.evolve Class Evolution
     */
    public EvolveStats evolve(EvolveConfig config)
        throws DatabaseException {

        return store.evolve(config);
    }

    /**
     * Deletes all instances of this entity class and its (non-entity)
     * subclasses.
     *
     * <p>The primary database for the given entity class will be truncated and
     * all secondary databases will be removed.  The primary and secondary
     * databases associated with the entity class must not be open except by
     * this store, since database truncation/removal is only possible when the
     * database is not open.</p>
     *
     * <p>The primary and secondary databases for the entity class will be
     * closed by this operation and the existing {@link PrimaryIndex} and
     * {@link SecondaryIndex} objects will be invalidated.  To access the
     * indexes, the user must call {@link #getPrimaryIndex} and {@link
     * #getSecondaryIndex} after this operation is complete.</p>
     *
     * <p>Auto-commit is used implicitly if the store is transactional.</p>
     *
     * @param entityClass the entity class whose instances are to be deleted.
     *
     *
     * @throws DatabaseException the base class for all BDB exceptions.
     */
    public void truncateClass(Class entityClass)
        throws DatabaseException {

        store.truncateClass(null, entityClass);
    }

    /**
     * Deletes all instances of this entity class and its (non-entity)
     * subclasses.
     *
     * <p>The primary database for the given entity class will be truncated and
     * all secondary databases will be removed.  The primary and secondary
     * databases associated with the entity class must not be open except by
     * this store, since database truncation/removal is only possible when the
     * database is not open.</p>
     *
     * <p>The primary and secondary databases for the entity class will be
     * closed by this operation and the existing {@link PrimaryIndex} and
     * {@link SecondaryIndex} objects will be invalidated.  To access the
     * indexes, the user must call {@link #getPrimaryIndex} and {@link
     * #getSecondaryIndex} after this operation is complete.</p>
     *
     * @param txn the transaction used to protect this operation, null to use
     * auto-commit, or null if the store is non-transactional.
     *
     * @param entityClass the entity class whose instances are to be deleted.
     *
     *
     * @throws DatabaseException the base class for all BDB exceptions.
     */
    public void truncateClass(Transaction txn, Class entityClass)
        throws DatabaseException {

        store.truncateClass(txn, entityClass);
    }


    /**
     * Closes the primary and secondary databases for the given entity class
     * that were opened via this store.  The caller must ensure that the
     * primary and secondary indices for the entity class are no longer in
     * use.
     *
     * <p>The primary and secondary databases for the entity class will be
     * closed by this operation and the existing {@link PrimaryIndex} and
     * {@link SecondaryIndex} objects will be invalidated.  To access the
     * indexes, the user must call {@link #getPrimaryIndex} and {@link
     * #getSecondaryIndex} after this operation is complete.</p>
     *
     * @param entityClass the entity class whose databases are to be closed.
     *
     * @throws DatabaseException the base class for all BDB exceptions.
     */
    public void closeClass(Class entityClass)
        throws DatabaseException {

        store.closeClass(entityClass);
    }

    /**
     * Closes all databases and sequences that were opened via this store.  The
     * caller must ensure that no databases opened via this store are in use.
     *
     * <p>WARNING: To guard against memory leaks, the application should
     * discard all references to the closed handle.  While BDB makes an effort
     * to discard references from closed objects to the allocated memory for an
     * environment, this behavior is not guaranteed.  The safe course of action
     * for an application is to discard all references to closed BDB
     * objects.</p>
     *
     * @throws DatabaseException the base class for all BDB exceptions.
     */
    public void close()
        throws DatabaseException {

        store.close();
    }

    /**
     * Returns a named sequence for using Berkeley DB engine API directly,
     * opening it if necessary.
     *
     * @param name the sequence name, which is normally defined using the
     * {@link PrimaryKey#sequence} annotation property.
     *
     * @return the open sequence for the given sequence name.
     *
     * @throws DatabaseException the base class for all BDB exceptions.
     */
    public Sequence getSequence(String name)
        throws DatabaseException {

        return store.getSequence(name);
    }

    /**
     * Returns the default Berkeley DB engine API configuration for a named key
     * sequence.
     *
     * </p>The returned configuration is as follows.  All other properties have
     * default values.</p>
     * <ul>
     * <li>The {@link SequenceConfig#setInitialValue InitialValue} is one.</li>
     * <li>The {@link SequenceConfig#setRange Range} minimum is one.</li>
     * <li>The {@link SequenceConfig#setCacheSize CacheSize} is 100.</li>
     * <li>{@link SequenceConfig#setAutoCommitNoSync AutoCommitNoSync} is
     * true.</li>
     * <li>{@link SequenceConfig#setAllowCreate AllowCreate} is set to the
     * inverse of the store {@link StoreConfig#setReadOnly ReadOnly}.
     * setting.</li>
     * </ul>
     *
     * @param name the sequence name, which is normally defined using the
     * {@link PrimaryKey#sequence} annotation property.
     *
     * @return the default configuration for the given sequence name.
     */
    public SequenceConfig getSequenceConfig(String name) {
        return store.getSequenceConfig(name);
    }

    /**
     * Configures a named key sequence using the Berkeley DB engine API.
     *
     * <p>To be compatible with the entity model and the Direct Persistence
     * Layer, the configuration should be retrieved using {@link
     * #getSequenceConfig getSequenceConfig}, modified, and then passed to this
     * method.  The following configuration properties may not be changed:</p>
     * <ul>
     * <li>{@link SequenceConfig#setExclusiveCreate ExclusiveCreate}</li>
     * </ul>
     * <p>In addition, {@link SequenceConfig#setAllowCreate AllowCreate} must be
     * the inverse of {@code ReadOnly}</p>
     *
     * <p>If the range is changed to include the value zero, see {@link
     * PrimaryKey} for restrictions.</p>
     *
     * @param name the sequence name, which is normally defined using the
     * {@link PrimaryKey#sequence} annotation property.
     *
     * @param config the configuration to use for the given sequence name.
     *
     * @throws IllegalArgumentException if the configuration is incompatible
     * with the entity model or the Direct Persistence Layer.
     *
     * @throws IllegalStateException if the sequence has already been opened.
     */
    public void setSequenceConfig(String name, SequenceConfig config) {
        store.setSequenceConfig(name, config);
    }

    /**
     * Returns the default primary database Berkeley DB engine API
     * configuration for an entity class.
     *
     * </p>The returned configuration is as follows.  All other properties have
     * default values.</p>
     * <ul>
     * <li>{@link DatabaseConfig#setTransactional Transactional} is set to
     * match {@link StoreConfig#setTransactional StoreConfig}.</li>
     * <li>{@link DatabaseConfig#setAllowCreate AllowCreate} is set to the
     * inverse of the store {@link StoreConfig#setReadOnly ReadOnly}.
     * setting.</li>
     * <li>{@link DatabaseConfig#setReadOnly ReadOnly} is set to match
     * {@link StoreConfig#setReadOnly StoreConfig}.</li>
     * <li>{@link DatabaseConfig#setBtreeComparator BtreeComparator} is set to
     * an internal class if a key comparator is used.</li>
     * </ul>
     *
     * @param entityClass the entity class identifying the primary database.
     *
     * @return the default configuration for the given entity class.
     */
    public DatabaseConfig getPrimaryConfig(Class entityClass) {
        return store.getPrimaryConfig(entityClass);
    }

    /**
     * Configures the primary database for an entity class using the Berkeley
     * DB engine API.
     *
     * <p>To be compatible with the entity model and the Direct Persistence
     * Layer, the configuration should be retrieved using {@link
     * #getPrimaryConfig getPrimaryConfig}, modified, and then passed to this
     * method.  The following configuration properties may not be changed:</p>
     * <ul>
     * <li>{@link DatabaseConfig#setExclusiveCreate ExclusiveCreate}</li>
     * <li>{@link DatabaseConfig#setSortedDuplicates SortedDuplicates}</li>
     * <li>{@link DatabaseConfig#setBtreeComparator BtreeComparator}</li>
     * </ul>
     * <p>In addition, {@link DatabaseConfig#setAllowCreate AllowCreate} must be
     * the inverse of {@code ReadOnly}</p>
     *
     * @param entityClass the entity class identifying the primary database.
     *
     * @param config the configuration to use for the given entity class.
     *
     * @throws IllegalArgumentException if the configuration is incompatible
     * with the entity model or the Direct Persistence Layer.
     *
     * @throws IllegalStateException if the database has already been opened.
     */
    public void setPrimaryConfig(Class entityClass, DatabaseConfig config) {
        store.setPrimaryConfig(entityClass, config);
    }

    /**
     * Returns the default secondary database Berkeley DB engine API
     * configuration for an entity class and key name.
     *
     * </p>The returned configuration is as follows.  All other properties have
     * default values.</p>
     * <ul>
     * <li>{@link DatabaseConfig#setTransactional Transactional} is set to
     * match the primary database.</li>
     * <li>{@link DatabaseConfig#setAllowCreate AllowCreate} is set to the
     * inverse of the primary database {@link DatabaseConfig#setReadOnly
     * ReadOnly} setting.</li>
     * <li>{@link DatabaseConfig#setReadOnly ReadOnly} is set to match
     * the primary database.</li>
     * <li>{@link DatabaseConfig#setBtreeComparator BtreeComparator} is set to
     * an internal class if a key comparator is used.</li>
     * <li>{@link DatabaseConfig#setSortedDuplicates SortedDuplicates} is set
     * according to {@link SecondaryKey#relate}.</p>
     * <li>{@link SecondaryConfig#setAllowPopulate AllowPopulate} is set to
     * true when a secondary key is added to an existing primary index.</li>
     * <li>{@link SecondaryConfig#setKeyCreator KeyCreator} or {@link
     * SecondaryConfig#setMultiKeyCreator MultiKeyCreator} is set to an
     * internal instance.</p>
     * <li>{@link SecondaryConfig#setForeignMultiKeyNullifier
     * ForeignMultiKeyNullifier} is set to an internal instance if {@link
     * SecondaryKey#onRelatedEntityDelete} is {@link DeleteAction#NULLIFY}.</li>
     * </ul>
     *
     * @param entityClass the entity class containing the given secondary key
     * name.
     *
     * @param keyName the name of the secondary key field, or the {@link
     * SecondaryKey#name} if this name annotation property was specified.
     *
     * @return the default configuration for the given secondary key.
     */
    public SecondaryConfig getSecondaryConfig(Class entityClass,
                                              String keyName) {
        return store.getSecondaryConfig(entityClass, keyName);
    }

    /**
     * Configures a secondary database for an entity class and key name using
     * the Berkeley DB engine API.
     *
     * <p>To be compatible with the entity model and the Direct Persistence
     * Layer, the configuration should be retrieved using {@link
     * #getSecondaryConfig getSecondaryConfig}, modified, and then passed to
     * this method.  The following configuration properties may not be
     * changed:</p>
     * <ul>
     * <li>{@link DatabaseConfig#setExclusiveCreate ExclusiveCreate}</li>
     * <li>{@link DatabaseConfig#setSortedDuplicates SortedDuplicates}</li>
     * <li>{@link DatabaseConfig#setBtreeComparator BtreeComparator}</li>
     * <li>{@link DatabaseConfig#setDuplicateComparator
     * DuplicateComparator}</li>
     * <li>{@link SecondaryConfig#setAllowPopulate AllowPopulate}</li>
     * <li>{@link SecondaryConfig#setKeyCreator KeyCreator}</li>
     * <li>{@link SecondaryConfig#setMultiKeyCreator MultiKeyCreator}</li>
     * <li>{@link SecondaryConfig#setForeignKeyNullifier
     * ForeignKeyNullifier}</li>
     * <li>{@link SecondaryConfig#setForeignMultiKeyNullifier
     * ForeignMultiKeyNullifier}</li>
     * <li>{@link SecondaryConfig#setForeignKeyDeleteAction
     * ForeignKeyDeleteAction}</li>
     * <li>{@link SecondaryConfig#setForeignKeyDatabase
     * ForeignKeyDatabase}</li>
     * </ul>
     * <p>In addition, {@link DatabaseConfig#setAllowCreate AllowCreate} must be
     * the inverse of {@code ReadOnly}</p>
     *
     * @param entityClass the entity class containing the given secondary key
     * name.
     *
     * @param keyName the name of the secondary key field, or the {@link
     * SecondaryKey#name} if this name annotation property was specified.
     *
     * @param config the configuration to use for the given secondary key.
     *
     * @throws IllegalArgumentException if the configuration is incompatible
     * with the entity model or the Direct Persistence Layer.
     *
     * @throws IllegalStateException if the database has already been opened.
     */
    public void setSecondaryConfig(Class entityClass,
                                   String keyName,
                                   SecondaryConfig config) {
        store.setSecondaryConfig(entityClass, keyName, config);
    }
}