All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.apache.openjpa.kernel.StoreContext Maven / Gradle / Ivy

Go to download

OpenJPA Kernel

There is a newer version: 4.0.1
Show newest version
/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.openjpa.kernel;

import java.util.BitSet;
import java.util.Collection;
import java.util.Iterator;
import java.util.List;

import org.apache.openjpa.conf.OpenJPAConfiguration;
import org.apache.openjpa.meta.ValueMetaData;
import org.apache.openjpa.util.UserException;

/**
 * Represents a set of managed objects and their environment.
 *
 * @since 0.4.0
 * @author Abe White
 */
public interface StoreContext {

    /**
     * Marker bitset to indicate that all field loads should be excluded in
     * the find methods of this interface.
     */
    BitSet EXCLUDE_ALL = new BitSet(0);

    int OID_NOVALIDATE = 2 << 0;
    int OID_NODELETED = 2 << 1;
    int OID_COPY = 2 << 2;
    int OID_ALLOW_NEW = 2 << 3;

    /**
     * Return the broker for this context, if possible. Note that a broker
     * will be unavailable in remote contexts, and this method may return null.
     */
    Broker getBroker();

    /**
     * Return the configuration associated with this context.
     */
    OpenJPAConfiguration getConfiguration();

    /**
     * Return the (mutable) fetch configuration for loading objects from this
     * context.
     */
    FetchConfiguration getFetchConfiguration();

    /**
     * Pushes a new fetch configuration that inherits from the current
     * fetch configuration onto a stack, and makes the new configuration
     * the active one.
     *
     * @since 1.1.0
     * @return the new fetch configuration
     */
    FetchConfiguration pushFetchConfiguration();

    /**
     * Pushes the fetch configuration argument onto a stack, and makes the new configuration
     * the active one.
     *
     * @since 2.1.1
     * @return the new fetch configuration
     */
    FetchConfiguration pushFetchConfiguration(FetchConfiguration fc);

    /**
     * Pops the fetch configuration from the top of the stack, making the
     * next one down the active one. This returns void to avoid confusion,
     * since fetch configurations tend to be used in method-chaining
     * patterns often.
     *
     * @since 1.1.0
     * @throws UserException if the fetch configuration stack is empty
     */
    void popFetchConfiguration();

    /**
     * Return the current thread's class loader at the time this context
     * was obtained.
     */
    ClassLoader getClassLoader();

    /**
     * Return the lock manager in use.
     */
    LockManager getLockManager();

    /**
     * Return the store manager in use. This will be a wrapper around the
     * native store manager, which you can retrieve via
     * {@link DelegatingStoreManager#getInnermostDelegate}.
     */
    DelegatingStoreManager getStoreManager();

    /**
     * Return the connection user name.
     */
    String getConnectionUserName();

    /**
     * Return the connection password.
     */
    String getConnectionPassword();

    /**
     * Return the instance for the given oid/object , or null if not
     * found in the L1 cache.
     *
     * @param oid the object's id
     * @return the cached object, or null if not cached
     */
    Object findCached(Object oid, FindCallbacks call);

    /**
     * Find the persistence object with the given oid. If
     * validate is true, the broker will check the store
     * for the object, and return null if it does not exist. If
     * validate is false, this method never returns null. The
     * broker will either return its cached instance, attempt to create a
     * hollow instance, or throw an ObjectNotFoundException if
     * unable to return a hollow instance.
     *
     * @param validate if true, validate that the instance exists in the
     * store and load fetch group fields, otherwise return
     * any cached or hollow instance
     */
    Object find(Object oid, boolean validate, FindCallbacks call);

    /**
     * Return the objects with the given oids.
     *
     * @param oids the oids of the objects to return
     * @return the objects that were looked up, in the same order as the oids
     * parameter
     * @see #find(Object,boolean,FindCallbacks)
     */
    Object[] findAll(Collection oids, boolean validate,
        FindCallbacks call);

    /**
     * Return the object with the given oid. If present, the
     * cached instance will be returned. Otherwise, the instance will be
     * initialized through the store as usual; however, in this case
     * the store will be passed the given execution data, and the
     * system will load the object according to the given fetch configuration
     * (or the context's configuration, if the given one is null).
     * Fields can optionally be excluded from required loading using the
     * exclude mask. By default this method does not find new
     * unflushed instances, validates, and does not throw an exception
     * if a cached instance has been deleted concurrently. These options
     * are controllable through the given OID_XXX flags.
     */
    Object find(Object oid, FetchConfiguration fetch, BitSet exclude,
        Object edata, int flags);

    /**
     * Return the objects with the given oids.
     *
     * @see #find(Object,FetchConfiguration,BitSet,Object,int)
     */
    Object[] findAll(Collection oids, FetchConfiguration fetch,
        BitSet exclude, Object edata, int flags);

    /**
     * Return an iterator over all instances of the given type. The iterator
     * should be closed with {@link org.apache.openjpa.util.ImplHelper#close}
     * when no longer needed. This method delegates to
     * {@link StoreManager#executeExtent}.
     */
    Iterator extentIterator(Class cls, boolean subs,
        FetchConfiguration fetch, boolean ignoreChanges);

    /**
     * Immediately load the given object's persistent fields. One might
     * use this action to make sure that an instance's fields are loaded
     * before transitioning it to transient. Note that this action is not
     * recursive. Any related objects that are loaded will not necessarily
     * have their fields loaded. Unmanaged target is ignored.
     *
     * @param fgOnly indicator as to whether to retrieve only fields
     * in the current fetch groups, or all fields
     * @see #retrieve
     */
    void retrieve(Object pc, boolean fgOnly, OpCallbacks call);

    /**
     * Retrieve the given objects' persistent state. Unmanaged targets are
     * ignored.
     *
     * @param fgOnly indicator as to whether to retrieve only fields
     * @see #retrieve
     */
    void retrieveAll(Collection objs, boolean fgOnly, OpCallbacks call);

    /**
     * Make the given instance embedded.
     *
     * @param obj the instance to embed; may be null to create a new instance
     * @param id the id to give the embedded state manager; may be
     * null for default
     * @param owner the owning state manager
     * @param ownerMeta the value in which the object is embedded
     * @return the state manager for the embedded instance
     */
    OpenJPAStateManager embed(Object obj, Object id,
        OpenJPAStateManager owner, ValueMetaData ownerMeta);

    /**
     * Return the application or datastore identity class the given persistent
     * class uses for object ids.
     */
    Class getObjectIdType(Class cls);

    /**
     * Create a new object id instance from the given value.
     *
     * @param cls the persistent class that uses this identity value
     * @param val an object id instance, stringified object id, or primary
     * key value
     */
    Object newObjectId(Class cls, Object val);

    /**
     * Return the set of classes that have been made persistent in the current
     * transaction.
     *
     * @since 0.3.4
     */
    Collection> getPersistedTypes();

    /**
     * Return the set of classes that have been deleted in the current
     * transaction.
     *
     * @since 0.3.4
     */
    Collection> getDeletedTypes();

    /**
     * Return the set of classes for objects that have been modified
     * in the current transaction.
     *
     * @since 0.3.4
     */
    Collection> getUpdatedTypes();

    /**
     * Return a list of all managed instances.
     */
    Collection getManagedObjects();

    /**
     * Return a list of current transaction instances.
     */
    Collection getTransactionalObjects();

    /**
     * Return a list of instances which will become transactional upon
     * the next transaction.
     */
    Collection getPendingTransactionalObjects();

    /**
     * Return a list of current dirty instances.
     */
    Collection getDirtyObjects();

    /**
     * Whether to maintain the order in which objects are dirtied for
     * {@link #getDirtyObjects}. Default is the store manager's decision.
     */
    boolean getOrderDirtyObjects();

    /**
     * Whether to maintain the order in which objects are dirtied for
     * {@link #getDirtyObjects}. Default is the store manager's decision.
     */
    void setOrderDirtyObjects(boolean order);

    /**
     * Return the state manager for the given instance. Includes objects
     * made persistent in the current transaction. If obj is not
     * a managed type or is managed by another context, throw an exception.
     */
    OpenJPAStateManager getStateManager(Object obj);

    /**
     * Return the lock level of the specified object.
     */
    int getLockLevel(Object obj);

    /**
     * Returns the current version indicator for o.
     */
    Object getVersion(Object obj);

    /**
     * Return whether the given object is dirty.
     */
    boolean isDirty(Object obj);

    /**
     * Return whether the given object is transactional.
     */
    boolean isTransactional(Object obj);

    /**
     * Make the given object transactional.
     *
     * @param pc instance to make transactional
     * @param updateVersion if true, the instance's version will be
     * incremented at the next flush
     */
    void transactional(Object pc, boolean updateVersion, OpCallbacks call);

    /**
     * Make the given objects transactional.
     *
     * @param objs instances to make transactional
     * @param updateVersion if true, the instance's version will be
     * incremented at the next flush
     */
    void transactionalAll(Collection objs, boolean updateVersion, OpCallbacks call);

    /**
     * Make the given object non-transactional.
     */
    void nontransactional(Object pc, OpCallbacks call);

    /**
     * Make the given objects nontransactional.
     */
    void nontransactionalAll(Collection objs, OpCallbacks call);

    /**
     * Return whether the given object is persistent.
     */
    boolean isPersistent(Object obj);

    /**
     * Return whether the given object is a newly-created instance registered
     * with broker.
     */
    boolean isNew(Object obj);

    /**
     * Return whether the given object is deleted.
     */
    boolean isDeleted(Object obj);

    /**
     * Return the oid of the given instance.
     */
    Object getObjectId(Object obj);

    /**
     * Detach mode constant to determine which fields are part of the
     * detached graph. Defaults to {@link DetachState#DETACH_LOADED}.
     */
    int getDetachState();

    /**
     * Detach mode constant to determine which fields are part of the
     * detached graph. Defaults to {@link DetachState#DETACH_LOADED}.
     */
    void setDetachState(int mode);

    /**
     * Whether objects accessed during this transaction will be added to the
     * store cache. Defaults to true.
     *
     * @since 0.3.4
     */
    boolean getPopulateDataCache();

    /**
     * Whether to populate the store cache with objects used by this
     * transaction. Defaults to true.
     *
     * @since 0.3.4
     */
    void setPopulateDataCache(boolean cache);

    /**
     * Whether memory usage is reduced during this transaction at the expense
     * of tracking changes at the type level instead of the instance level,
     * resulting in more aggressive cache invalidation.
     *
     * @since 1.0.0
     */
    boolean isTrackChangesByType();

    /**
     * If a large number of objects will be created, modified, or deleted
     * during this transaction setting this option to true will reduce memory
     * usage if you perform periodic flushes by tracking changes at the type
     * level instead of the instance level, resulting in more aggressive cache
     * invalidation. Upon transaction commit the data cache will have to
     * more aggressively flush objects. The store cache will have to flush
     * instances of objects for each class of object modified during the
     * transaction. A side benefit of large transaction mode is that smaller
     * update messages can be used for
     * {@link org.apache.openjpa.event.RemoteCommitEvent}s. Defaults to false.
     *
     * @since 1.0.0
     */
    void setTrackChangesByType(boolean largeTransaction);

    /**
     * Whether this context is using managed transactions.
     */
    boolean isManaged();

    /**
     * Whether a logical transaction is active.
     */
    boolean isActive();

    /**
     * Whether a data store transaction is active.
     */
    boolean isStoreActive();

    /**
     * Begin a data store transaction.
     */
    void beginStore();

    /**
     * Whether the broker has a dedicated connection based on the configured
     * connection retain mode and transaction status.
     */
    boolean hasConnection();

    /**
     * Return the connection in use by the context, or a new connection if none.
     */
    Object getConnection();

    /**
     * Synchronizes on an internal lock if the
     * Multithreaded flag is set to true. Make sure to call
	 * {@link #unlock} in a finally clause of the same method.
	 */
	void lock ();

	/**
	 * Releases the internal lock.
	 */
	void unlock ();

    /**
     * Return the 'JTA' connectionFactoryName
     */
    String getConnectionFactoryName();

    /**
     * Set the 'JTA' ConnectionFactoryName.
     */
    void setConnectionFactoryName(String connectionFactoryName);

    /**
     * Return the 'NonJTA' ConnectionFactoryName.
     */
    String getConnectionFactory2Name();

    /**
     * Set the 'NonJTA' ConnectionFactoryName.
     */
    void setConnectionFactory2Name(String connectionFactory2Name);

    /**
     * Return the 'JTA' ConnectionFactory, looking it up from JNDI if needed.
     *
     * @return the JTA connection factory or null if connectionFactoryName is blank.
     */
    Object getConnectionFactory();

    /**
     * Return the 'NonJTA' ConnectionFactory, looking it up from JNDI if needed.
     *
     * @return the NonJTA connection factory or null if connectionFactoryName is blank.
     */
    Object getConnectionFactory2();

    /**
     * Indicate whether the oid can be found in the StoreContext's L1 cache or in the StoreManager cache.
     * @param oid List of ObjectIds for PersistenceCapables which may be found in memory.
     * @return true if the oid is available in memory (cached) otherwise false.
     * @since 2.0.0.
     */
    boolean isCached(List oid);

    /**
     * Affirms if this context will allow its managed instances to refer instances
     * that are managed by other contexts.
     * Note: Some specification (such as JPA) does not warranty predictable
     * behavior when strict group-like property of a persistent context (where managed
     * instances can only refer to instances managed by the same context).
     * Please be aware of consequences when the flag is set to true.
     *
     * @since 2.1
     */
    void setAllowReferenceToSiblingContext(boolean flag);

    /**
     * Affirms if this context will allow its managed instances to refer instances
     * that are managed by other contexts.
     *
     * @return false by default.
     *
     * @since 2.1
     */
    boolean getAllowReferenceToSiblingContext();


    /**
     * Set to true if the merge operation should trigger
     * a @PostLoad lifecycle event.
     * @param allow PostLoad lifecycle events to be triggered on a merge operation
     */
    void setPostLoadOnMerge(boolean allow);

    /**
     * Force sending a @PostLoad lifecycle event while merging.
     *
     * @return false by default
     *
     * @since 2.2
     */
    boolean getPostLoadOnMerge();

}
    

    

    

            

    

            



    
    






    
© 2015 - 2024 Weber Informatics LLC | Privacy Policy