ObjectManagerImpl.java :  » Database-ORM » JPOX » org » jpox » Java Open Source

Java Open Source » Database ORM » JPOX 
JPOX » org » jpox » ObjectManagerImpl.java
/**********************************************************************
Copyright (c) 2006 Andy Jefferson and others. All rights reserved.
Licensed 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.

Contributors:
2007 Xuan Baldauf - added the use of srm.findObject() to cater for different object lifecycle management policies (in RDBMS and DB4O databases)
2007 Xuan Baldauf - changes to allow the disabling of clearing of fields when transitioning from PERSISTENT_NEW to TRANSIENT.
     ...
 **********************************************************************/
package org.jpox;

import java.lang.reflect.Constructor;
import java.lang.reflect.Modifier;
import java.util.ArrayList;
import java.util.Collection;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Set;

import org.jpox.api.ApiAdapter;
import org.jpox.cache.CachedPC;
import org.jpox.cache.Level1Cache;
import org.jpox.cache.Level2Cache;
import org.jpox.exceptions.ClassNotDetachableException;
import org.jpox.exceptions.ClassNotPersistableException;
import org.jpox.exceptions.ClassNotResolvedException;
import org.jpox.exceptions.JPOXException;
import org.jpox.exceptions.JPOXObjectNotFoundException;
import org.jpox.exceptions.JPOXOptimisticException;
import org.jpox.exceptions.JPOXUserException;
import org.jpox.exceptions.NoPersistenceInformationException;
import org.jpox.exceptions.ObjectDetachedException;
import org.jpox.exceptions.RollbackStateTransitionException;
import org.jpox.exceptions.TransactionActiveOnCloseException;
import org.jpox.exceptions.TransactionNotActiveException;
import org.jpox.identity.OID;
import org.jpox.identity.OIDFactory;
import org.jpox.jdo.JDOAdapter;
import org.jpox.jdo.JPOXJDOHelper;
import org.jpox.jdo.exceptions.CommitStateTransitionException;
import org.jpox.metadata.AbstractClassMetaData;
import org.jpox.metadata.AbstractMemberMetaData;
import org.jpox.metadata.IdentityType;
import org.jpox.metadata.MetaDataManager;
import org.jpox.metadata.TransactionType;
import org.jpox.state.CallbackHandler;
import org.jpox.state.DetachState;
import org.jpox.store.Extent;
import org.jpox.state.FetchPlanState;
import org.jpox.state.StateManagerFactory;
import org.jpox.store.FieldValues;
import org.jpox.store.SCOID;
import org.jpox.store.query.Query;
import org.jpox.store.StoreManager;
import org.jpox.util.JPOXLogger;
import org.jpox.util.Localiser;
import org.jpox.util.StringUtils;
import org.jpox.util.WeakValueMap;

/**
 * Representation of an ObjectManager.
 * An object manager provides management for the persistence of objects into a datastore
 * and the retrieval of these objects using various methods. 
 * <h3>Caching</h3>
 * <p>
 * An ObjectManager has its own Level 1 cache. This stores objects against their identity. The Level 1 Cache
 * is typically a weak referenced map and so cached objects can be garbage collected. Objects are similarly
 * placed in the Level 2 cache of the owning PersistenceManagerFactory. This Level 2 cache caches objects across
 * multiple ObjectManagers, and so we can use this to get objects retrieved by other ObjectManagers. The Caches
 * exist for performance enhancement.
 * <h3>Transactions</h3>
 * <p>
 * Has a single transaction (the "current" transaction).
 * </p>
 * <h3>Persisted Objects</h3>
 * <p>
 * When an object involved in the current transaction it is <i>enlisted</i> (calling enlistInTransaction()).
 * Its' identity is saved (in "txEnlistedIds") for use later in any "persistenceByReachability" process run at commit.
 * Any object that is passed via makePersistent() will be stored (as an identity) in "txKnownPersistedIds" and objects 
 * persisted due to reachability from these objects will also have their identity stored (in "txFlushedNewIds").
 * All of this information is used in the "persistence-by-reachability-at-commit" process which detects if some objects
 * originally persisted are no longer reachable and hence should not be persistent after all.
 * </p>
 * <h3>Queries</h3>
 * <p>
 * ALl queries run during a transaction are registered here. When the transaction commits/rolls back then
 * all queries are notified that the connection is closing so that they can read in any remaining results
 * (and the queries remain usable after). When this manager closes all queries registered here will also be closed
 * meaning that a query has its lifetime defined by the owning PersistenceManager.
 * </p>
 * 
 * @version $Revision: 1.100 $
 */
public class ObjectManagerImpl implements ObjectManager
{
    /** Localisation utility for output messages */
    protected static final Localiser LOCALISER = Localiser.getInstance("org.jpox.Localisation");

    /** Factory for this ObjectManager. */
    private final ObjectManagerFactoryImpl omf;

    /** The owning PersistenceManager/EntityManager object. */
    private Object owner;

    /** State variable for whether the ObjectManager is closed. */
    private boolean closed;

    /** Current FetchPlan for the ObjectManager. */
    private FetchPlan fetchPlan;

    /** The ClassLoader resolver to use for class loading issues. */
    private ClassLoaderResolver clr = null;

    /** Callback handler for this ObjectManager. */
    private CallbackHandler callbacks;

    //-- cache level 1 --//
    /** Level 1 Cache */
    private Level1Cache cache;

    /** Whether to ignore the cache */
    private boolean ignoreCache;

    //-- convenience operations --//
    /** State variable used when searching for the StateManager for an object, representing the object. */
    private Object objectLookingForStateManager = null;

    /** State variable used when searching for the StateManager for an object, representing the StateManager. */
    private StateManager foundStateManager = null;

    //-- transaction --//
    /** Current transaction */
    private Transaction tx;

    /** Cache of StateManagers enlisted in the current transaction, keyed by the object id. */
    private Map enlistedSMCache = new WeakValueMap();

    /** Set of the object ids for all objects enlisted in this transaction. Used in reachability at commit to determine what to check. */
    private Set txEnlistedIds = new HashSet();

    /** List of StateManagers for all current dirty objects managed by this ObjectManager. */
    private List dirtySMs = new ArrayList(10);

    /** List of StateManagers for all current dirty objects made dirty by reachability. Only used by delete process currently. */
    private List indirectDirtySMs = new ArrayList();

    /** StateManagers of all objects that have had managed relationships changed in the last flush-cycle. */
    HashSet managedRelationDirtySMs = null;

    /** State indicator whether we are currently managing the relations. */
    private boolean managingRelations = false;

    /** Set of Object Ids of objects persisted using persistObject, or known as already persistent in the current transaction. */
    private Set txKnownPersistedIds = new HashSet();

    /** Set of Object Ids of objects deleted using deleteObject. */
    private Set txKnownDeletedIds = new HashSet();

    /** Set of Object Ids of objects newly persistent in the current transaction */
    private Set txFlushedNewIds = new HashSet();

    //-- configuration --//
    /** Whether to detach objects on close of the ObjectManager. */
    private boolean detachOnClose;

    /** Whether to detach all objects on commit of the transaction. */
    private boolean detachAllOnCommit;

    /** Whether to copy objects on attaching. */
    private boolean copyOnAttach;

    /** Whether to operate multithreaded */
    private boolean multithreaded;

    /** State variable for whether the ObjectManager is currently flushing its operations. */
    private boolean flushing = false;

    /** State variable for whether we are currently running detachAllOnCommit. */
    private boolean runningDetachAllOnCommit = false;

    /**
     * Map containing any thread-specific state information, keyed by the thread number string.
     * Used where we don't want to pass information down through a large number of method calls.
     */
    private HashMap contextInfoByThread = new HashMap();

    /**
     * Constructor.
     * @param omf Object Manager Factory
     * @param owner The owning PM/EM
     * @param userName Username for the datastore
     * @param password Password for the datastore
     * @throws JPOXUserException if an error occurs allocating the necessary requested components
     */
    public ObjectManagerImpl(ObjectManagerFactoryImpl omf, Object owner, String userName, String password)
    {
        this.owner = owner;
        this.omf = omf;
        closed = false;

        // Set up class loading
        ClassLoader contextLoader = Thread.currentThread().getContextClassLoader();
        clr = omf.getOMFContext().getClassLoaderResolver(contextLoader);
        try
        {
            ImplementationCreator ic = omf.getOMFContext().getImplementationCreator();
            if (ic != null)
            {
                clr.registerClassLoader(ic.getClassLoader());
            }
        }
        catch (Exception ex)
        {
            // do nothing
        }

        // Set up StoreManager, using that of the OMF
        if (JPOXLogger.PERSISTENCE.isDebugEnabled())
        {
            JPOXLogger.PERSISTENCE.debug(LOCALISER.msg("010000", this, omf.getOMFContext().getStoreManager()));
        }

        PersistenceConfiguration config = omf.getOMFContext().getPersistenceConfiguration();

        // Configuration from OMF
        setIgnoreCache(config.getIgnoreCache());
        setDetachOnClose(config.getDetachOnClose());
        setDetachAllOnCommit(config.getDetachAllOnCommit());
        setCopyOnAttach(config.getCopyOnAttach());
        setMultithreaded(config.getMultithreaded());

        // Set up FetchPlan
        fetchPlan = new FetchPlan(omf, clr).setMaxFetchDepth(omf.getMaxFetchDepth());

        // Set up the Level 1 Cache
        initialiseLevel1Cache();

        // Set up the transaction suitable for this ObjectManagerFactory
        if (TransactionType.JTA.toString().equalsIgnoreCase(config.getTransactionType()))
        {
            tx = new JTATransactionImpl(this);
        }
        else
        {
            tx = new TransactionImpl(this);
        }
    }

    /**
     * Method to initialise the L1 cache.
     * @throws JPOXUserException if an error occurs setting up the L1 cache
     */
    protected void initialiseLevel1Cache()
    {
        // Find the L1 cache class name from its plugin name
        String level1Type = omf.getPersistenceConfiguration().getCacheLevel1Type();
        String level1ClassName = getOMFContext().getPluginManager().getAttributeValueForExtension("org.jpox.cache_level1", 
            "name", level1Type, "class-name");
        if (level1ClassName == null)
        {
            // Plugin of this name not found
            throw new JPOXUserException(LOCALISER.msg("003001", level1Type)).setFatal();
        }

        try
        {
            // Create an instance of the L1 Cache
            Class level1CacheClass = clr.classForName(level1ClassName,OMFContext.class.getClassLoader());
            cache = (Level1Cache) level1CacheClass.newInstance();
            if (JPOXLogger.CACHE.isDebugEnabled())
            {
                JPOXLogger.CACHE.debug(LOCALISER.msg("003003", level1Type));
            }
        }
        catch (Exception e)
        {
            // Class name for this L1 cache plugin is not found!
            throw new JPOXUserException(LOCALISER.msg("003002", level1Type, level1ClassName),e).setFatal();
        }
    }

    /**
     * Accessor for whether this ObjectManager is closed.
     * @return Whether this manager is closed.
     */
    public boolean isClosed()
    {
        return closed;
    }

    /**
     * Accessor for the ClassLoaderResolver
     * @return the ClassLoaderResolver
     */
    public ClassLoaderResolver getClassLoaderResolver()
    {
        return clr;
    }

    /**
     * Accessor for the Store Manager.
     * @return StoreManager
     */
    public StoreManager getStoreManager()
    {
        return getOMFContext().getStoreManager();
    }

    /**
     * Accessor for the API adapter.
     * @return API adapter.
     */
    public ApiAdapter getApiAdapter()
    {
        return getOMFContext().getApiAdapter();
    }

    /**
     * Acessor for the current FetchPlan
     * @return FetchPlan
     * @since 1.1
     */
    public FetchPlan getFetchPlan()
    {
        // TODO this should be enabled, but with detachAllOnCommit=true it raises exception 
        //assertIsOpen();
        return fetchPlan;
    }

    /**
     * Method to return the owner PM/EM object.
     * For JDO this will return the PersistenceManager owning this ObjectManager.
     * For JPA this will return the EntityManager owning this ObjectManager.
     * @return The owner manager object
     */
    public Object getOwner()
    {
        return owner;
    }

    /**
     * Gets the context in which this ObjectManager is running
     * @return Returns the context.
     */
    public OMFContext getOMFContext()
    {
        return omf.getOMFContext();
    }

    /**
     * Accessor for the MetaDataManager for this ObjectManager (and its factory).
     * This is used as the interface to MetaData in the ObjectManager/Factory.
     * @return Returns the MetaDataManager.
     */
    public MetaDataManager getMetaDataManager()
    {
        return getOMFContext().getMetaDataManager();
    }

    /**
     * Mutator for whether the Persistence Manager is multithreaded.
     * @param flag Whether to run multithreaded.
     */
    public void setMultithreaded(boolean flag)
    {
        assertIsOpen();
        this.multithreaded = flag;
    }

    /**
     * Accessor for whether the Persistence Manager is multithreaded.
     * @return Whether to run multithreaded.
     */
    public boolean getMultithreaded()
    {
        assertIsOpen();
        return this.multithreaded;
    }

    /**
     * Mutator for whether to detach objects on close of the ObjectManager.
     * <B>This is a JPOX extension and will not work when in JCA mode.</B>
     * @param flag Whether to detach on close.
     */
    public void setDetachOnClose(boolean flag)
    {
        assertIsOpen();
        this.detachOnClose = flag;
    }

    /**
     * Accessor for whether to detach objects on close of the ObjectManager.
     * <B>This is a JPOX extension and will not work when in JCA mode.</B>
     * @return Whether to detach on close.
     */
    public boolean getDetachOnClose()
    {
        assertIsOpen();
        return detachOnClose;
    }

    /**
     * Mutator for whether to detach all objects on commit of the transaction.
     * @param flag Whether to detach all on commit.
     */
    public void setDetachAllOnCommit(boolean flag)
    {
        assertIsOpen();
        this.detachAllOnCommit = flag;
    }

    /**
     * Accessor for whether to detach all objects on commit of the transaction.
     * @return Whether to detach all on commit.
     */
    public boolean getDetachAllOnCommit()
    {
        assertIsOpen();
        return detachAllOnCommit;
    }

    /**
     * Mutator for whether to copy on attaching.
     * @param flag Whether to copy on attaching
     */
    public void setCopyOnAttach(boolean flag)
    {
        assertIsOpen();
        this.copyOnAttach = flag;
    }

    /**
     * Accessor for whether to copy on attaching.
     * @return Whether to copy on attaching
     */
    public boolean getCopyOnAttach()
    {
        assertIsOpen();
        return copyOnAttach;
    }

    /**
     * Mutator for whether to ignore the cache.
     * @param flag Whether to ignore the cache.
     */
    public void setIgnoreCache(boolean flag)
    {
        assertIsOpen();
        this.ignoreCache = flag;
    }

    /**
     * Accessor for whether to ignore the cache.
     * @return Whether to ignore the cache.
     */
    public boolean getIgnoreCache()
    {
        assertIsOpen();
        return ignoreCache;
    }

    /**
     * Whether the datastore operations are delayed until commit/flush. 
     * In optimistic transactions this is automatically enabled. In datastore transactions there is a
     * persistence property to enable it.
     * If we are committing/flushing then will return false since the delay is no longer required.
     * @return true if datastore operations are delayed until commit/flush
     */
    public boolean isDelayDatastoreOperationsEnabled()
    {
        if (flushing || tx.isCommitting())
        {
            // Already sending to the datastore so return false to not confuse things
            return false;
        }

        if (tx.getOptimistic())
        {
            return true;
        }
        else
        {
            return getOMFContext().getPersistenceConfiguration().getDatastoreTransactionsDelayOperations();
        }
    }

    /**
     * Tests whether this persistable object is in the process of being inserted.
     * @param pc the object to verify the status
     * @return true if this instance is inserting.
     */
    public boolean isInserting(Object pc)
    {
        StateManager sm = findStateManager(pc);
        if (sm == null)
        {
            return false;
        }
        return sm.isInserting();
    }

    /**
     * Convenience method to find if the specified field of the specified object has been inserted yet.
     * @param pc The object
     * @param fieldNumber The absolute field number
     * @return Whether it has been inserted into the datastore
     */
    public boolean isInserted(Object pc, int fieldNumber)
    {
        StateManager sm = findStateManager(pc);
        if (sm == null)
        {
            return false;
        }
        return sm.isInserted(fieldNumber);
    }

    /**
     * Convenience method to find if the specified object is inserted down to the specified class level yet.
     * @param pc The object
     * @param className Name of the class that we want to check the insertion level to
     * @return Whether it has been inserted into the datastore
     */
    public boolean isInserted(Object pc, String className)
    {
        StateManager sm = findStateManager(pc);
        if (sm == null)
        {
            return false;
        }
        return sm.isInserted(className);
    }

    /**
     * Accessor for the current transaction.
     * @return The transaction
     */
    public Transaction getTransaction()
    {
        assertIsOpen();
        return tx;
    }

    /**
     * Method to enlist the specified StateManager in the current transaction.
     * @param sm The StateManager
     */
    public synchronized void enlistInTransaction(StateManager sm)
    {
        assertActiveTransaction();
        if (JPOXLogger.TRANSACTION.isDebugEnabled())
        {
            JPOXLogger.TRANSACTION.debug(LOCALISER.msg("015017", 
                StringUtils.toJVMIDString(sm.getObject()), sm.getInternalObjectId().toString()));
        }

        if (omf.getPersistenceByReachabilityAtCommit())
        {
            if (getApiAdapter().isNew(sm.getObject()))
            {
                // Add this object to the list of new objects in this transaction
                txFlushedNewIds.add(sm.getInternalObjectId());
            }
            else if (getApiAdapter().isPersistent(sm.getObject()) && !getApiAdapter().isDeleted(sm.getObject()))
            {
                // Add this object to the list of known valid persisted objects (unless it is a known new object)
                if (!txFlushedNewIds.contains(sm.getInternalObjectId()))
                {
                    txKnownPersistedIds.add(sm.getInternalObjectId());
                }
            }
        }

        // Add the object to those enlisted
        if (omf.getPersistenceByReachabilityAtCommit() && !runningPBRAtCommit)
        {
            // Keep a note of the id for use by persistence-by-reachability-at-commit
            txEnlistedIds.add(sm.getInternalObjectId());
        }
        enlistedSMCache.put(sm.getInternalObjectId(), sm);
    }

    /**
     * Method to evict the specified StateManager from the current transaction.
     * @param sm The StateManager
     */
    public synchronized void evictFromTransaction(StateManager sm)
    {
        if (JPOXLogger.TRANSACTION.isDebugEnabled())
        {
            JPOXLogger.TRANSACTION.debug(LOCALISER.msg("015019", 
                StringUtils.toJVMIDString(sm.getObject()), sm.getInternalObjectId().toString()));
        }

        if (enlistedSMCache.remove(sm.getInternalObjectId()) == null)
        {
            //probably because the object was garbage collected
            if (JPOXLogger.TRANSACTION.isDebugEnabled())
            {
                JPOXLogger.TRANSACTION.debug(LOCALISER.msg("010023", 
                    StringUtils.toJVMIDString(sm.getObject()), sm.getInternalObjectId()));
            }
        }
    }

    /**
     * Method to return if an object is enlisted in the current transaction.
     * This is only of use when running "persistence-by-reachability-at-commit"
     * @param id Identity for the object
     * @return Whether it is enlisted in the current transaction
     */
    public boolean isEnlistedInTransaction(Object id)
    {
        if (id == null)
        {
            return false;
        }
        return txEnlistedIds.contains(id);
    }

    /**
     * Method to add the object managed by the specified StateManager to the cache.
     * @param sm The StateManager
     */
    public synchronized void addStateManager(StateManager sm)
    {
        // Add to the Level 1/2 Caches
        putObjectIntoCache(sm, true, true);
    }

    /**
     * Method to remove the object managed by the specified StateManager from the cache.
     * @param sm The StateManager
     */
    public synchronized void removeStateManager(StateManager sm)
    {
        Object pc = sm.getObject();

        // Remove from the Level 1 Cache
        removeObjectFromCache(pc, sm.getInternalObjectId(), true, false);

        // Remove it from any transaction
        enlistedSMCache.remove(sm.getInternalObjectId());
    }

    /**
     * Accessor for the StateManager of an object given the object id.
     * @param id Id of the object.
     * @return The StateManager
     */
    public synchronized StateManager getStateManagerById(Object id)
    {
        assertIsOpen();
        return findStateManager(getObjectFromCache(id));
    }

    /**
     * Method to find the StateManager for an object.
     * @param pc The object we require the StateManager for.
     * @return The StateManager, null if StateManager not found.
     *     See JDO spec for the calling behavior when null is returned
     */
    public synchronized StateManager findStateManager(Object pc)
    {
        StateManager sm = null;
        Object previousLookingFor = objectLookingForStateManager;
        StateManager previousFound = foundStateManager;
        try
        {
            objectLookingForStateManager = pc;
            foundStateManager = null;
            // We call "ObjectManagerHelper.getObjectManager(pc)".
            // This then calls "JDOHelper.getPersistenceManager(pc)".
            // Which calls "StateManager.getPersistenceManager(pc)".
            // That then calls "hereIsStateManager(sm, pc)" which sets "foundStateManager".
            ObjectManager om = ObjectManagerHelper.getObjectManager(pc);
            if (om != null && this != om)
            {
                throw new JPOXUserException(LOCALISER.msg("010007", getApiAdapter().getIdForObject(pc)));
            }
            sm = foundStateManager;
        }
        finally
        {
            objectLookingForStateManager = previousLookingFor;
            foundStateManager = previousFound;
        }
        return sm;
    }

    /**
     * Method to add the StateManager for an object to this ObjectManager's list.
     * @param sm The StateManager
     * @param pc The object managed by the StateManager
     */
    public synchronized void hereIsStateManager(StateManager sm, Object pc)
    {
        if (objectLookingForStateManager == pc)
        {
            foundStateManager = sm;
        }
    }

    /**
     * Method to close the Persistence Manager.
     */
    public synchronized void close()
    {
        if (closed)
        {
            throw new JPOXUserException(LOCALISER.msg("010002"));
        }
        if (tx.isActive())
        {
            throw new TransactionActiveOnCloseException(this);
        }

        if (detachOnClose)
        {
            // JPOX "detach-on-close" extension, detaching all currently cached objects.
            performDetachOnClose();
        }

        ObjectManagerListener[] listener = omf.getOMFContext().getObjectManagerListeners();

        for (int i=0; i<listener.length; i++)
        {
            listener[i].objectManagerPreClose(this);
        }

        // Disconnect remaining resources
        disconnectSMCache();
        disconnectLifecycleListener();

        // Reset the Fetch Plan to its DFG setting
        getFetchPlan().clearGroups().addGroup(FetchPlan.DEFAULT);
    }

    public void postClose()
    {
        closed = true;
        tx = null;

        if (JPOXLogger.PERSISTENCE.isDebugEnabled())
        {
            JPOXLogger.PERSISTENCE.debug(LOCALISER.msg("010001", this));
        }
    }

    /**
     * Disconnect SM instances, clear cache and reset settings 
     */
    public void disconnectSMCache()
    {
        // Clear out the cache (use separate list since sm.disconnect will remove the object from "cache" so we avoid
        // any ConcurrentModification issues)
        Collection cachedSMsClone = new HashSet(cache.values());
        Iterator iter = cachedSMsClone.iterator();
        while (iter.hasNext())
        {
            StateManager sm = (StateManager) iter.next();
            if (sm != null)
            {
                sm.disconnect();
            }
        }
        cache.clear();
        if (JPOXLogger.CACHE.isDebugEnabled())
        {
            JPOXLogger.CACHE.debug(LOCALISER.msg("003011"));
        }

    }

    // ----------------------------- Lifecycle Methods ------------------------------------

    /**
     * Internal method to evict an object from L1 cache.
     * @param obj The object
     * @throws JPOXException if an error occurs evicting the object
     */
    public void evictObject(Object obj)
    {
        if (obj == null)
        {
            return;
        }

        try
        {
            clr.setPrimary(obj.getClass().getClassLoader());
            assertClassPersistable(obj.getClass());
            assertNotDetached(obj);

            // we do not directly remove from cache level 1 here. The cache level 1 will be evicted 
            // automatically on garbage collection, if the object can be evicted. it means not all
            // jdo states allows the object to be evicted.
            StateManager sm = findStateManager(obj);
            if (sm == null)
            {
                throw new JPOXUserException(LOCALISER.msg("010007", getApiAdapter().getIdForObject(obj)));
            }
            sm.evict();
        }
        finally
        {
            clr.unsetPrimary();
        }
    }

    /**
     * Method to evict all objects of the specified type (and optionaly its subclasses).
     * @param cls Type of persistable object
     * @param subclasses Whether to include subclasses
     */
    public void evictObjects(Class cls, boolean subclasses)
    {
        assertIsOpen();

        ArrayList stateManagersToEvict = new ArrayList();
        stateManagersToEvict.addAll(cache.values());
        Iterator smIter = stateManagersToEvict.iterator();
        while (smIter.hasNext())
        {
            StateManager sm = (StateManager)smIter.next();
            Object pc = sm.getObject();
            boolean evict = false;
            if (!subclasses && pc.getClass() == cls)
            {
                evict = true;
            }
            else if (subclasses && cls.isAssignableFrom(pc.getClass()))
            {
                evict = true;
            }

            if (evict)
            {
                sm.evict();
                removeObjectFromCache(pc, getApiAdapter().getIdForObject(pc), true, false);
            }
        }
    }

    /**
     * Method to evict all current objects from L1 cache.
     */
    public synchronized void evictAllObjects()
    {
        assertIsOpen();

        // All persistent non-transactional instances should be evicted here, but not yet supported
        ArrayList stateManagersToEvict = new ArrayList();
        stateManagersToEvict.addAll(cache.values());

        // Evict StateManagers and remove objects from cache
        // Performed in separate loop to avoid ConcurrentModificationException
        Iterator smIter = stateManagersToEvict.iterator();
        while (smIter.hasNext())
        {
            StateManager sm = (StateManager)smIter.next();
            Object pc = sm.getObject();
            sm.evict();

            // Evict from L1
            removeObjectFromCache(pc, getApiAdapter().getIdForObject(pc), true, false);
        }
    }

    /**
     * Method to do a refresh of an object, updating it from its
     * datastore representation. Also updates the object in the L1/L2 caches.
     * @param obj The Object
     */
    public void refreshObject(Object obj)
    {
        if (obj == null)
        {
            return;
        }
        try
        {
            clr.setPrimary(obj.getClass().getClassLoader());
            assertClassPersistable(obj.getClass());
            assertNotDetached(obj);

            StateManager sm = findStateManager(obj);
            if (sm == null)
            {
                throw new JPOXUserException(LOCALISER.msg("010007", getApiAdapter().getIdForObject(obj)));
            }

            if (getApiAdapter().isPersistent(obj) && sm.isWaitingToBeFlushedToDatastore())
            {
                // Persistent but not yet flushed so nothing to "refresh" from!
                return;
            }

            sm.refresh();
    
            // Refresh L2 cache object since it is a copy of this object
            putObjectIntoCache(sm, false, true);
        }
        finally
        {
            clr.unsetPrimary();
        }
    }

    /**
     * Method to do a refresh of all objects.
     * @throws JPOXUserException thrown if instances could not be refreshed.
     */
    public synchronized void refreshAllObjects()
    {
        assertIsOpen();

        Set toRefresh = new HashSet();
        toRefresh.addAll(enlistedSMCache.values());
        toRefresh.addAll(dirtySMs);
        toRefresh.addAll(indirectDirtySMs);
        if (!tx.isActive())
        {
            toRefresh.addAll(cache.values());
        }

        List failures = null;
        Iterator iter = toRefresh.iterator();
        while (iter.hasNext())
        {
            try
            {
                Object obj = iter.next();
                StateManager sm;
                if (getApiAdapter().isPersistable(obj))
                {
                    sm = findStateManager(obj);
                }
                else
                {
                    sm = (StateManager) obj;
                }
                sm.refresh();

                // Refresh L2 cache object since it is a copy of this object
                putObjectIntoCache(sm, false, true);
            }
            catch (RuntimeException e)
            {
                if (failures == null)
                {
                    failures = new ArrayList();
                }
                failures.add(e);
            }
        }
        if (failures != null && !failures.isEmpty())
        {
            throw new JPOXUserException(LOCALISER.msg("011002"), (Exception[]) failures.toArray(new Exception[failures.size()]));
        }
    }

    /**
     * Method to retrieve an object.
     * @param obj The object
     * @param fgOnly Whether to retrieve the current fetch group fields only
     */
    public void retrieveObject(Object obj, boolean fgOnly)
    {
        if (obj == null)
        {
            return;
        }
        try
        {
            clr.setPrimary(obj.getClass().getClassLoader());
            assertClassPersistable(obj.getClass());
            assertNotDetached(obj);

            StateManager sm = findStateManager(obj);
            if (sm == null)
            {
                throw new JPOXUserException(LOCALISER.msg("010007", getApiAdapter().getIdForObject(obj)));
            }
            sm.retrieve(fgOnly);
        }
        finally
        {
            clr.unsetPrimary();
        }
    }

    /**
     * Context info for a particular thread. Can be used for storing state information for the current
     * thread where we don't want to pass it through large numbers of method calls (e.g persistence by
     * reachability) where such argument passing would damage the structure of JPOX.
     */
    class ThreadContextInfo
    {
        /** Map of attached PC object keyed by the id. Present when performing a persist operation. */
        HashMap attachedPCById = null;
    }

    /**
     * Accessor for the thread context information, for the current thread.
     * If the current thread is not present, will add an info context for it.
     * @return The thread context information
     */
    protected ThreadContextInfo getThreadContextInfo()
    {
        String threadId = "" + Thread.currentThread().getId();
        synchronized (contextInfoByThread)
        {
            ThreadContextInfo threadInfo = (ThreadContextInfo)contextInfoByThread.get(threadId);
            if (threadInfo == null)
            {
                // Thread not present, so add it
                threadInfo = new ThreadContextInfo();
                contextInfoByThread.put(threadId, threadInfo);
            }
            return threadInfo;
        }
    }

    /**
     * Method to remove the current thread context info for the current thread.
     */
    protected void removeThreadContextInfo()
    {
        String threadId = "" + Thread.currentThread().getId();
        synchronized (contextInfoByThread)
        {
            contextInfoByThread.remove(threadId);
        }
    }

    /**
     * Method to make an object persistent.
     * NOT to be called by internal JPOX methods. Only callable by external APIs (JDO/JPA).
     * @param obj The object
     * @return The persisted object
     * @throws JPOXUserException if the object is managed by a different manager
     */
    public Object persistObject(Object obj)
    {
        assertIsOpen();
        assertWritable();
        if (obj == null)
        {
            return null;
        }

        // Make sure we have attachedPC lookup info initialised in case we need to attach objects multiple times
        ThreadContextInfo threadInfo = getThreadContextInfo();
        if (threadInfo.attachedPCById == null)
        {
            threadInfo.attachedPCById = new HashMap();
        }

        boolean detached = getApiAdapter().isDetached(obj);

        // Persist the object
        Object persistedPc = persistObjectInternal(obj, null, null, -1, StateManager.PC);

        // If using reachability at commit and appropriate save it for reachability checks when we commit
        StateManager sm = findStateManager(persistedPc);
        if (sm != null)
        {
            if (indirectDirtySMs.contains(sm))
            {
                dirtySMs.add(sm);
                indirectDirtySMs.remove(sm);
            }
            else if (!dirtySMs.contains(sm))
            {
                dirtySMs.add(sm);
            }

            if (omf.getPersistenceByReachabilityAtCommit())
            {
                if (detached || getApiAdapter().isNew(persistedPc))
                {
                    txKnownPersistedIds.add(sm.getInternalObjectId());
                }
            }
        }

        // Deallocate attached PC lookup
        threadInfo.attachedPCById.clear();
        threadInfo.attachedPCById = null;
        removeThreadContextInfo(); // Currently remove the whole thread context since only used for this

        return persistedPc;
    }

    /**
     * Method to make an object persistent which should be called from internal calls only.
     * All PM/EM calls should go via persistObject(Object obj).
     * @param obj The object
     * @param preInsertChanges Any changes to make before inserting
     * @param ownerSM StateManager of the owner when embedded
     * @param ownerFieldNum Field number in the owner where this is embedded (or -1 if not embedded)
     * @param objectType Type of object (see org.jpox.StateManager, e.g StateManager.PC)
     * @return The persisted object
     * @throws JPOXUserException if the object is managed by a different manager
     */
    public Object persistObjectInternal(Object obj, FieldValues preInsertChanges, 
            StateManager ownerSM, int ownerFieldNum, int objectType)
    {
        if (obj == null)
        {
            return null;
        }
        assertIsOpen();
        assertWritable();
        // TODO Support embeddedOwner/objectType, so we can add StateManager for embedded objects here

        try
        {
            clr.setPrimary(obj.getClass().getClassLoader());
            assertClassPersistable(obj.getClass());
            if (!getApiAdapter().isDetached(obj) && JPOXLogger.PERSISTENCE.isDebugEnabled())
            {
                JPOXLogger.PERSISTENCE.debug(LOCALISER.msg("010015", StringUtils.toJVMIDString(obj)));
            }
            ObjectManager om = ObjectManagerHelper.getObjectManager(obj);
            if (om != null && om != this)
            {
                // Object managed by a different manager
                throw new JPOXUserException(LOCALISER.msg("010007", obj));
            }

            Object persistedPc = obj; // Persisted object is the passed in pc (unless being attached as a copy)
            if (getApiAdapter().isDetached(obj))
            {
                // Detached : attach it
                assertDetachable(obj);
                if (copyOnAttach)
                {
                    // Attach a copy and return the copy
                    persistedPc = attachObjectCopy(obj, getApiAdapter().getIdForObject(obj) == null);
                }
                else
                {
                    // Attach the object
                    attachObject(obj, getApiAdapter().getIdForObject(obj) == null);
                    persistedPc = obj;
                }
            }
            else if (getApiAdapter().isTransactional(obj) && !getApiAdapter().isPersistent(obj))
            {
                // TransientTransactional : persist it
                StateManager sm = findStateManager(obj);
                if (sm == null)
                {
                    throw new JPOXUserException(LOCALISER.msg("010007", getApiAdapter().getIdForObject(obj)));
                }
                sm.makePersistentTransactionalTransient();
            }
            else if (!getApiAdapter().isPersistent(obj))
            {
                // Transient : persist it
                if (this.multithreaded)
                {
                    synchronized (obj)
                    {
                        StateManager sm = findStateManager(obj);
                        if (sm == null)
                        {
                            if (objectType != StateManager.PC && ownerSM != null)
                            {
                                // SCO object
                                sm = StateManagerFactory.newStateManagerForEmbedded(this, obj, false);
                                sm.addEmbeddedOwner(ownerSM, ownerFieldNum);
                                sm.setPcObjectType(objectType);
                                sm.makePersistent();
                            }
                            else
                            {
                                // FCO object
                                sm = StateManagerFactory.newStateManagerForPersistentNew(this, obj, preInsertChanges);
                                sm.makePersistent();
                            }
                        }
                        else
                        {
                            if (sm.getReferencedPC() == null)
                            {
                                // Persist it
                                sm.makePersistent();
                            }
                            else
                            {
                                // Being attached, so use the attached object
                                persistedPc = sm.getReferencedPC();
                            }
                        }
                    }
                }
                else
                {
                    StateManager sm = findStateManager(obj);
                    if (sm == null)
                    {
                        if (objectType != StateManager.PC && ownerSM != null)
                        {
                            // SCO Object
                            sm = StateManagerFactory.newStateManagerForEmbedded(this, obj, false);
                            sm.addEmbeddedOwner(ownerSM, ownerFieldNum);
                            sm.setPcObjectType(objectType);
                            sm.makePersistent();
                        }
                        else
                        {
                            // FCO object
                            sm = StateManagerFactory.newStateManagerForPersistentNew(this, obj, preInsertChanges);
                            sm.makePersistent();
                        }
                    }
                    else
                    {
                        if (sm.getReferencedPC() == null)
                        {
                            // Persist it
                            sm.makePersistent();
                        }
                        else
                        {
                            // Being attached, so use the attached object
                            persistedPc = sm.getReferencedPC();
                        }
                    }
                }
            }
            else if (getApiAdapter().isPersistent(obj) && getApiAdapter().getIdForObject(obj) == null)
            {
                // Embedded/Serialised : have SM but no identity, allow persist in own right
                // Should we be making a copy of the object here ?
                if (this.multithreaded)
                {
                    synchronized (obj)
                    {
                        StateManager sm = findStateManager(obj);
                        sm.makePersistent();
                    }
                }
                else
                {
                    StateManager sm = findStateManager(obj);
                    sm.makePersistent();
                }
            }
            else if (getApiAdapter().isDeleted(obj))
            {
                // Deleted : (re)-persist it (permitted in JPA, but not JDO - see StateManager)
                StateManager sm = findStateManager(obj);
                sm.makePersistent();
            }
            else
            {
                if (getApiAdapter().isPersistent(obj) &&
                    getApiAdapter().isTransactional(obj) &&
                    getApiAdapter().isDirty(obj) &&
                    isDelayDatastoreOperationsEnabled())
                {
                    // Object provisionally persistent (but not in datastore) so re-run reachability maybe
                    StateManager sm = findStateManager(obj);
                    sm.makePersistent();
                }
            }

            return persistedPc;
        }
        finally
        {
            clr.unsetPrimary();
        }
    }

    /**
     * Method to delete an object from the datastore.
     * NOT to be called by internal JPOX methods. Only callable by external APIs (JDO/JPA).
     * @param obj The object
     */
    public void deleteObject(Object obj)
    {
        StateManager sm = findStateManager(obj);
        if (sm != null)
        {
            // Add the object to the relevant list of dirty StateManagers
            if (indirectDirtySMs.contains(sm))
            {
                // Object is dirty indirectly, but now user-requested so move to direct list of dirty objects
                indirectDirtySMs.remove(sm);
                dirtySMs.add(sm);
            }
            else if (!dirtySMs.contains(sm))
            {
                dirtySMs.add(sm);
            }
        }

        // Delete the object
        deleteObjectInternal(obj);

        if (omf.getPersistenceByReachabilityAtCommit())
        {
            if (sm != null)
            {
                if (getApiAdapter().isDeleted(obj))
                {
                    txKnownDeletedIds.add(sm.getInternalObjectId());
                }
            }
        }
    }

    /**
     * Method to delete an object from persistence which should be called from internal calls only.
     * All PM/EM calls should go via deleteObject(Object obj).
     * @param obj Object to delete
     */
    public void deleteObjectInternal(Object obj)
    {
        if (obj == null)
        {
            return;
        }
        assertIsOpen();
        assertWritable();

        try
        {
            clr.setPrimary(obj.getClass().getClassLoader());
            assertClassPersistable(obj.getClass());

            Object pc = obj;
            if (getApiAdapter().isDetached(obj))
            {
                // Load up the attached instance with this identity
                pc = findObject(getApiAdapter().getIdForObject(obj), true, true, null);
            }

            if (JPOXLogger.PERSISTENCE.isDebugEnabled())
            {
                JPOXLogger.PERSISTENCE.debug(LOCALISER.msg("010019", StringUtils.toJVMIDString(pc)));
            }

            // Check that the object is valid for deleting
            if (getApiAdapter() instanceof JDOAdapter) // TODO Refactor this
            {
                // JDO doesnt allow deletion of transient
                if (!getApiAdapter().isPersistent(pc) && !getApiAdapter().isTransactional(pc))
                {
                    throw new JPOXUserException(LOCALISER.msg("010020"));
                }
                else if (!getApiAdapter().isPersistent(pc) && getApiAdapter().isTransactional(pc))
                {
                    throw new JPOXUserException(LOCALISER.msg("010021"));
                }
            }

            // Delete it
            StateManager sm = findStateManager(pc);
            if (sm == null)
            {
                if (!getApiAdapter().allowDeleteOfNonPersistentObject())
                {
                    // Not permitted by the API
                    throw new JPOXUserException(LOCALISER.msg("010007", getApiAdapter().getIdForObject(pc)));
                }

                // Put StateManager around object so it is P_NEW (unpersisted), then P_NEW_DELETED soon after
                sm = StateManagerFactory.newStateManagerForPNewToBeDeleted(this, pc);
            }

            // Move to deleted state
            sm.deletePersistent();
        }
        finally
        {
            clr.unsetPrimary();
        }
    }

    /**
     * Method to delete an array of objects from the datastore.
     * @param objs The objects
     * @throws JPOXUserException Thrown if an error occurs during the deletion process.
     *     Any exception could have several nested exceptions for each failed object deletion
     */
    public void deleteObjects(Object[] objs)
    {
        if (objs == null)
        {
            return;
        }

        ArrayList failures = null;
        for (int i=0;i<objs.length;i++)
        {
            try
            {
                deleteObject(objs[i]);
            }
            catch (RuntimeException e)
            {
                if (failures == null)
                {
                    failures = new ArrayList();
                }
                failures.add(e);
            }
        }
        if (failures != null && !failures.isEmpty())
        {
            throw new JPOXUserException(LOCALISER.msg("011005"), 
                (Exception[]) failures.toArray(new Exception[failures.size()]));
        }
    }

    /**
     * Method to delete an array of objects from the datastore.
     * @param objs The objects
     * @throws JPOXUserException Thrown if an error occurs during the deletion process.
     *     Any exception could have several nested exceptions for each failed object deletion
     */
    public void deleteObjects(Collection objs)
    {
        if (objs == null)
        {
            return;
        }

        ArrayList failures = null;
        Iterator iter = objs.iterator();
        while (iter.hasNext())
        {
            Object obj = iter.next();
            try
            {
                deleteObject(obj);
            }
            catch (RuntimeException e)
            {
                if (failures == null)
                {
                    failures = new ArrayList();
                }
                failures.add(e);
            }
        }
        if (failures != null && !failures.isEmpty())
        {
            throw new JPOXUserException(LOCALISER.msg("011005"), 
                (Exception[]) failures.toArray(new Exception[failures.size()]));
        }
    }

    /**
     * Method to migrate an object to transient state.
     * @param obj The object
     * @param state Object containing the state of the fetch plan process (if any)
     * @throws JPOXException When an error occurs in making the object transient
     */
    public synchronized void makeObjectTransient(Object obj, FetchPlanState state)
    {
        if (obj == null)
        {
            return;
        }

        try
        {
            clr.setPrimary(obj.getClass().getClassLoader());
            assertClassPersistable(obj.getClass());
            assertNotDetached(obj);

            if (JPOXLogger.PERSISTENCE.isDebugEnabled())
            {
                JPOXLogger.PERSISTENCE.debug(LOCALISER.msg("010022", StringUtils.toJVMIDString(obj)));
            }

            if (getApiAdapter().isPersistent(obj))
            {
                StateManager sm = findStateManager(obj);
                sm.makeTransient(state);
            }
        }
        finally
        {
            clr.unsetPrimary();
        }
    }

    /**
     * Method to make an object transactional.
     * @param obj The object
     * @throws JPOXException Thrown when an error occurs
     */
    public void makeObjectTransactional(Object obj)
    {
        if (obj == null)
        {
            return;
        }
        try
        {
            clr.setPrimary(obj.getClass().getClassLoader());
            assertClassPersistable(obj.getClass());
            assertNotDetached(obj);

            if (getApiAdapter().isPersistent(obj))
            {
                assertActiveTransaction();
            }
            StateManager sm = findStateManager(obj);
            if (sm == null)
            {
                sm = StateManagerFactory.newStateManagerForTransactionalTransient(this, obj);
            }
            sm.makeTransactional();
        }
        finally
        {
            clr.unsetPrimary();
        }
    }

    /**
     * Method to make an object nontransactional.
     * @param obj The object
     */
    public void makeObjectNontransactional(Object obj)
    {
        if (obj == null)
        {
            return;
        }
        try
        {
            clr.setPrimary(obj.getClass().getClassLoader());
            assertClassPersistable(obj.getClass());
            if (!getApiAdapter().isPersistent(obj) && getApiAdapter().isTransactional(obj) && getApiAdapter().isDirty(obj))
            {
                throw new JPOXUserException(LOCALISER.msg("010024"));
            }

            StateManager sm = findStateManager(obj);
            sm.makeNontransactional();
        }
        finally
        {
            clr.unsetPrimary();
        }
    }
    
    /**
     * Method to attach a persistent detached object.
     * If a different object with the same identity as this object exists in the L1 cache then an exception
     * will be thrown.
     * @param pc The persistable object
     * @param sco Whether the PC object is stored without an identity (embedded/serialised)
     */
    public synchronized void attachObject(Object pc, boolean sco)
    {
        assertIsOpen();
        assertClassPersistable(pc.getClass());

        ApiAdapter api = getApiAdapter();
        Object id = api.getIdForObject(pc);
        if (id != null && isInserting(pc))
        {
            // Object is being inserted in this transaction so just return
            return;
        }
        else if (id == null && !sco)
        {
            // Transient object so needs persisting
            persistObjectInternal(pc, null, null, -1, StateManager.PC);
            return;
        }

        if (api.isDetached(pc))
        {
            // Detached, so migrate to attached
            StateManager l1CachedSM = (StateManager)cache.get(id);
            if (l1CachedSM != null && l1CachedSM.getObject() != pc)
            {
                // attached object with the same id already present in the L1 cache so cannot attach in-situ
                throw new JPOXUserException(LOCALISER.msg("010017",
                    StringUtils.toJVMIDString(pc)));
            }

            if (JPOXLogger.PERSISTENCE.isDebugEnabled())
            {
                JPOXLogger.PERSISTENCE.debug(LOCALISER.msg("010016", 
                    StringUtils.toJVMIDString(pc)));
            }
            StateManager sm = 
                StateManagerFactory.newStateManagerForDetached(this, pc, id, api.getVersionForObject(pc));
            sm.attach(sco);
        }
        else
        {
            // Not detached so can't attach it. Just return
            return;
        }
    }

    /**
     * Method to attach a persistent detached object returning an attached copy of the object.
     * If the object is of class that is not detachable, a ClassNotDetachableException will be thrown.
     * @param pc The object
     * @param sco Whether it has no identity (second-class object)
     * @return The attached object
     */
    public synchronized Object attachObjectCopy(Object pc, boolean sco)
    {
        assertIsOpen();
        assertClassPersistable(pc.getClass());
        assertDetachable(pc);

        ApiAdapter api = getApiAdapter();
        Object id = api.getIdForObject(pc);
        if (id != null && isInserting(pc))
        {
            // Object is being inserted in this transaction
            return pc;
        }
        else if (id == null && !sco)
        {
            // Object was not persisted before so persist it
            return persistObjectInternal(pc, null, null, -1, StateManager.PC);
        }
        else if (api.isPersistent(pc))
        {
            // Already persistent hence can't be attached
            return pc;
        }

        // Object should exist in this datastore now
        Object pcTarget = null;
        if (sco)
        {
            // SCO PC (embedded/serialised)
            boolean detached = getApiAdapter().isDetached(pc);
            StateManager smTarget = StateManagerFactory.newStateManagerForEmbedded(this, pc, true);
            pcTarget = smTarget.getObject();
            if (detached)
            {
                // If the object is detached, re-attach it
                if (JPOXLogger.PERSISTENCE.isDebugEnabled())
                {
                    JPOXLogger.PERSISTENCE.debug(LOCALISER.msg("010018", 
                        StringUtils.toJVMIDString(pc), StringUtils.toJVMIDString(pcTarget)));
                }
                smTarget.attachCopy(pc, sco);
            }
        }
        else
        {
            // FCO PC
            boolean detached = getApiAdapter().isDetached(pc);
            pcTarget = findObject(id, false, false, pc.getClass().getName());
            if (detached)
            {
                Object obj = null;
                HashMap attachedPCById = getThreadContextInfo().attachedPCById; // For the current thread
                if (attachedPCById != null) // Only used by persistObject process
                {
                    obj = attachedPCById.get(getApiAdapter().getIdForObject(pc));
                }
                if (obj != null)
                {
                    pcTarget = obj;
                }
                else
                {
                    // If the object is detached, re-attach it
                    if (JPOXLogger.PERSISTENCE.isDebugEnabled())
                    {
                        JPOXLogger.PERSISTENCE.debug(LOCALISER.msg("010018", 
                            StringUtils.toJVMIDString(pc), StringUtils.toJVMIDString(pcTarget)));
                    }
                    findStateManager(pcTarget).attachCopy(pc, sco);

                    // Save the detached-attached PCs for later reference
                    if (attachedPCById != null) // Only used by persistObject process
                    {
                        attachedPCById.put(getApiAdapter().getIdForObject(pc), pcTarget);
                    }
                }
            }
        }

        return pcTarget;
    }

    /**
     * Method to detach a persistent object without making a copy. Note that 
     * also all the objects which are refered to from this object are detached.
     * If the object is of class that is not detachable a ClassNotDetachableException
     * will be thrown. If the object is not persistent a JDOUserException is thrown.
     * <B>For internal use only</B>
     * @param obj The object
     * @param state State for the detachment process
     */
    public synchronized void detachObject(Object obj, FetchPlanState state)
    {
        assertIsOpen();
        assertClassPersistable(obj.getClass());
        assertDetachable(obj); // Is this required?

        if (getApiAdapter().isDetached(obj))
        {
            return;
        }

        if (!getApiAdapter().isPersistent(obj))
        {
            // Transient object passed so persist it before thinking about detaching
            if (tx.isActive())
            {
                persistObjectInternal(obj, null, null, -1, StateManager.PC);
            }
        }

        StateManager sm = findStateManager(obj);
        if (sm == null)
        {
            throw new JPOXUserException(LOCALISER.msg("010007", getApiAdapter().getIdForObject(obj)));
        }
        sm.detach(state);
    }

    /**
     * Detach a copy of the passed persistent object using the provided detach state.
     * If the object is of class that is not detachable it will be detached as transient.
     * If it is not yet persistent it will be first persisted.
     * @param pc The object
     * @param state State for the detachment process
     * @return The detached object
     */
    public Object detachObjectCopy(Object pc, FetchPlanState state)
    {
        assertIsOpen();
        assertClassPersistable(pc.getClass());

        Object thePC = pc;
        try
        {
            clr.setPrimary(pc.getClass().getClassLoader());
            if (!getApiAdapter().isPersistent(pc) && !getApiAdapter().isDetached(pc))
            {
                // Transient object passed so persist it before thinking about detaching
                if (tx.isActive())
                {
                    thePC = persistObjectInternal(pc, null, null, -1, StateManager.PC);
                }
                else
                {
                    // JDO2 [12.6.8] "If a detachCopy method is called outside an active transaction, the reachability algorithm
                    // will not be run; if any transient instances are reachable via persistent fields, a JDOUserException is thrown 
                    // for each persistent instance containing such fields.
                    throw new JPOXUserException(LOCALISER.msg("010014"));
                }
            }

            if (getApiAdapter().isDetached(thePC))
            {
                // Passing in a detached (dirty or clean) instance, so get a persistent copy to detach
                thePC = findObject(getApiAdapter().getIdForObject(thePC), false, true, null);
            }

            Object detached = ((DetachState)state).getDetachedCopyObject(thePC);
            if (detached == null)
            {
                StateManager sm = findStateManager(thePC);
                if (sm == null)
                {
                    throw new JPOXUserException(LOCALISER.msg("010007", getApiAdapter().getIdForObject(thePC)));
                }

                detached = sm.detachCopy(state);
                ((DetachState)state).setDetachedCopyObject(detached, sm.getExternalObjectId(sm.getObject()));
            }
            else
            {
                // What if the fetch-group here implies a different depth through this object ? we need to continue detaching
                // TODO Check the detach and proceed further where necessary
            }
            return detached;
        }
        finally
        {
            clr.unsetPrimary();
        }
    }

    /**
     * Method to detach all objects in the ObjectManager.
     */
    public void detachAll()
    {
        Object[] sms = this.enlistedSMCache.values().toArray();
        FetchPlanState fps = new FetchPlanState();
        for (int i=0; i<sms.length; i++)
        {
            ((StateManager)sms[i]).detach(fps);
        }
    }

    // ----------------------------- New Instances ----------------------------------

    /**
     * Method to generate an instance of an interface, abstract class, or concrete PC class.
     * @param cls The class of the interface or abstract class, or concrete class defined in MetaData
     * @return The instance of this type
     */
    public Object newInstance(Class cls)
    {
        assertIsOpen();

        if (getApiAdapter().isPersistable(cls) && !Modifier.isAbstract(cls.getModifiers()))
        {
            // Concrete PC class so instantiate here
            try
            {
                return cls.newInstance();
            }
            catch (IllegalAccessException iae)
            {
                throw new JPOXUserException(iae.toString(), iae);
            }
            catch (InstantiationException ie)
            {
                throw new JPOXUserException(ie.toString(), ie);
            }
        }

        // Use ImplementationCreator
        assertHasImplementationCreator();
        return getOMFContext().getImplementationCreator().newInstance(cls, getMetaDataManager(), clr);
    }

    // ----------------------------- Object Retrieval by Id ----------------------------------

    /**
     * Method to return if the specified object exists in the datastore.
     * @param obj The (persistable) object
     * @return Whether it exists
     */
    public boolean exists(Object obj)
    {
        if (obj == null)
        {
            return false;
        }

        Object id = getApiAdapter().getIdForObject(obj);
        if (id == null)
        {
            return false;
        }

        try
        {
            findObject(id, true, false, obj.getClass().getName());
        }
        catch (JPOXObjectNotFoundException onfe)
        {
            return false;
        }

        return true;
    }

    /**
     * Accessor for the currently managed objects for the current transaction.
     * If the transaction is not active this returns null.
     * @return Collection of managed objects enlisted in the current transaction
     */
    public Set getManagedObjects()
    {
        if (!tx.isActive())
        {
            return null;
        }

        Set objs = new HashSet();
        Collection sms = enlistedSMCache.values();
        Iterator smsIter = sms.iterator();
        while (smsIter.hasNext())
        {
            StateManager sm = (StateManager)smsIter.next();
            objs.add(sm.getObject());
        }
        return objs;
    }

    /**
     * Accessor for the currently managed objects for the current transaction.
     * If the transaction is not active this returns null.
     * @param classes Classes that we want the enlisted objects for
     * @return Collection of managed objects enlisted in the current transaction
     */
    public Set getManagedObjects(Class[] classes)
    {
        if (!tx.isActive())
        {
            return null;
        }

        Set objs = new HashSet();
        Collection sms = enlistedSMCache.values();
        Iterator smsIter = sms.iterator();
        while (smsIter.hasNext())
        {
            StateManager sm = (StateManager)smsIter.next();
            for (int i=0;i<classes.length;i++)
            {
                if (classes[i] == sm.getObject().getClass())
                {
                    objs.add(sm.getObject());
                    break;
                }
            }
        }
        return objs;
    }

    /**
     * Accessor for the currently managed objects for the current transaction.
     * If the transaction is not active this returns null.
     * @param states States that we want the enlisted objects for
     * @return Collection of managed objects enlisted in the current transaction
     */
    public Set getManagedObjects(String[] states)
    {
        if (!tx.isActive())
        {
            return null;
        }

        Set objs = new HashSet();
        Collection sms = enlistedSMCache.values();
        Iterator smsIter = sms.iterator();
        while (smsIter.hasNext())
        {
            StateManager sm = (StateManager)smsIter.next();
            for (int i=0;i<states.length;i++)
            {
                if (getApiAdapter().getObjectState(sm.getObject()).equals(states[i]))
                {
                    objs.add(sm.getObject());
                    break;
                }
            }
        }
        return objs;
    }

    /**
     * Accessor for the currently managed objects for the current transaction.
     * If the transaction is not active this returns null.
     * @param states States that we want the enlisted objects for
     * @param classes Classes that we want the enlisted objects for
     * @return Collection of managed objects enlisted in the current transaction
     */
    public Set getManagedObjects(String[] states, Class[] classes)
    {
        if (!tx.isActive())
        {
            return null;
        }

        Set objs = new HashSet();
        Collection sms = enlistedSMCache.values();
        Iterator smsIter = sms.iterator();
        while (smsIter.hasNext())
        {
            boolean matches = false;
            StateManager sm = (StateManager)smsIter.next();
            for (int i=0;i<states.length;i++)
            {
                if (getApiAdapter().getObjectState(sm.getObject()).equals(states[i]))
                {
                    for (int j=0;i<classes.length;i++)
                    {
                        if (classes[j] == sm.getObject().getClass())
                        {
                            matches = true;
                            objs.add(sm.getObject());
                            break;
                        }
                    }
                }
                if (matches)
                {
                    break;
                }
            }
        }
        return objs;
    }
    
    /**
     * Accessor for the StateManager of an object given the object AID.
     * @param pcClass The class of the PC object
     * @param fv The field values to be loaded
     * @param ignoreCache true if it must ignore the cache
     * @param checkInheritance Whether look to the database to determine which
     * class this object is. This parameter is a hint. Set false, if it's
     * already determined the correct pcClass for this pc "object" in a certain
     * level in the hierarchy. Set to true and it will look to the database.
     * @return Object
     */
    public synchronized Object findObjectUsingAID(Class pcClass, FieldValues fv, boolean ignoreCache, boolean checkInheritance)
    {
        assertIsOpen();

        // Create StateManager to generate an identity 
        // TODO Provide a more efficient way of doing this. It creates a PC object just to get the id!
        StateManager sm = StateManagerFactory.newStateManagerForHollowPopulatedAppId(this, pcClass, fv);
        if (!ignoreCache)
        {
            // Check the cache
            Object oid = sm.getInternalObjectId();
            Object pc = getObjectFromCache(oid);
            if (pc != null)
            {
                sm = findStateManager(pc);
                sm.loadFieldValues(fv); // Load the values retrieved by the query
                return pc;
            }
            if (checkInheritance)
            {
                ApiAdapter api = getApiAdapter();
                if (oid instanceof OID || api.isSingleFieldIdentity(oid))
                {
                    // Check if this id for any known subclasses is in the cache to save searching
                    String[] subclasses = getMetaDataManager().getSubclassesForClass(pcClass.getName(), true);
                    if (subclasses != null)
                    {
                        for (int i=0;i<subclasses.length;i++)
                        {
                            if (oid instanceof OID)
                            {
                                oid = OIDFactory.getInstance(this, subclasses[i], ((OID)oid).getKeyValue());
                            }
                            else if (api.isSingleFieldIdentity(oid))
                            {
                                oid = api.getNewSingleFieldIdentity(oid.getClass(), clr.classForName(subclasses[i]), 
                                    api.getTargetKeyForSingleFieldIdentity(oid));
                            }
                            pc = getObjectFromCache(oid);
                            if (pc != null)
                            {
                                sm = findStateManager(pc);
                                sm.loadFieldValues(fv); // Load the values retrieved by the query
                                return pc;
                            }
                        }
                    }
                }
            }
        }

        if (checkInheritance)
        {
            sm.checkInheritance(fv); // Find the correct PC class for this object, hence updating the object id
            if (!ignoreCache)
            {
                // Check the cache in case this updated object id is present (since we should use that if available)
                Object oid = sm.getInternalObjectId();
                Object pc = getObjectFromCache(oid);
                if (pc != null)
                {
                    // We have an object with this new object id already so return it with the retrieved field values imposed
                    sm = findStateManager(pc);
                    sm.loadFieldValues(fv); // Load the values retrieved by the query
                    return pc;
                }
            }
        }
        putObjectIntoCache(sm, true, true);

        return sm.getObject();
    }

    /**
     * Accessor for an object given the object id. 
     * @param id Id of the object.
     * @param fv Field values for the object
     * @param cls the type which the object is. This type will be used to instanciat the object
     * @param ignoreCache true if it must ignore the cache
     * @return The Object
     */
    public synchronized Object findObject(Object id, FieldValues fv, Class cls, boolean ignoreCache)
    {
        assertIsOpen();

        Object pc = null;
        if (!ignoreCache)
        {
            pc = getObjectFromCache(id);
        }

        if (pc == null)
        {
            pc = getStoreManager().findObject(this,id);
        }
        
        if (pc == null)
        {
            // Object not found so load the requested fields into a new object
            StateManager sm = StateManagerFactory.newStateManagerForHollowPopulated(this, cls, id, fv);
            // TODO verify it

            pc = sm.getObject();

            // Save the object
            putObjectIntoCache(sm, true, true);
        }
        else
        {
            // Object found in the cache so load the requested fields
            StateManager sm = findStateManager(pc);
            if (sm != null)
            {
                // Load the requested fields
                fv.fetchNonLoadedFields(sm);
            }
        }

        return pc;
    }

    /**
     * Accessor for an object given the object id. Checks the inheritance level of the object
     * @param id Id of the object.
     * @param fv Field values for the object
     * @return The Object
     */
    public synchronized Object findObject(Object id, FieldValues fv)
    {
        assertIsOpen();

        Object pc = getObjectFromCache(id);
        if (pc == null)
        {
            // Find it direct from the store if the store supports that
            // NOTE : This ignores the provided FieldValues!
            pc = getStoreManager().findObject(this, id);

            if (pc == null)
            {
                // Find the class name for this object id so we can attempt to generate it
                // className is null when id class exists, and object has been validated and doesn't exist
                String className = getStoreManager().getClassNameForObjectID(id, clr, this);
                if (className == null)
                {
                    throw new JPOXObjectNotFoundException(LOCALISER.msg("010026"), id);
                }

                if (id instanceof OID)
                {
                    id = OIDFactory.getInstance(this, className, ((OID)id).getKeyValue());

                    // try again to read object from cache
                    pc = getObjectFromCache(id);
                }
                if (pc == null)
                {
                    // Still not found so create a Hollow instance with the supplied field values
                    try
                    {
                        Class pcClass = clr.classForName(className, id.getClass().getClassLoader());
                        StateManager sm = StateManagerFactory.newStateManagerForHollowPopulated(this, pcClass, id, fv);
                        pc = sm.getObject();
                        putObjectIntoCache(sm, true, true);
                    }
                    catch (ClassNotResolvedException e)
                    {
                        JPOXLogger.PERSISTENCE.warn(LOCALISER.msg("010027", id));
                        throw new JPOXUserException(LOCALISER.msg("010027", id), e);
                    }
                }
            }
        }
        return pc;
    }

    /**
     * Accessor for an object given the object id. If validate is false, we return the object
     * if found in the cache, or otherwise a Hollow object with that id. If validate is true
     * we check with the datastore and return an object with the FetchPlan fields loaded (unless
     * the object doesnt exist in the datastore, where we throw a JPOXObjectNotFoundException).
     * @param id Id of the object.
     * @param validate Whether to validate the object state
     * @param checkInheritance Whether look to the database to determine which
     * class this object is.
     * @param objectClassName Class name for the object with this id (if known, optional)
     * @return The Object with this id
     */
    public synchronized Object findObject(Object id, boolean validate, boolean checkInheritance, String objectClassName)
    {
        assertIsOpen();
        if (id == null)
        {
            throw new JPOXUserException(LOCALISER.msg("011010"));
        }

        // try to find object in cache(s)
        Object pc = getObjectFromCache(id);
        boolean fromCache = true;

        ApiAdapter api = getApiAdapter();
        if (id instanceof SCOID && pc != null)
        {
            if (api.isPersistent(pc) && !api.isNew(pc) && !api.isDeleted(pc) && !api.isTransactional(pc))
            {
                // JDO2 [5.4.4] Cant return HOLLOW nondurable objects
                throw new JPOXUserException(LOCALISER.msg("010005"));
            }
        }

        if (pc != null && api.isTransactional(pc))
        {
            // JDO2 [12.6.5] If there's already an object with the same id and it's transactional, return it
            return pc;
        }

        StateManager sm = null;
        if (pc == null)
        {
            // Find it direct from the store if the store supports that
            pc = getStoreManager().findObject(this, id);

            if (pc == null)
            {
                // Object not found in cache(s) with this identity
                String className = null;
                String originalClassName = null;
                boolean checkedClassName = false;
                if (id instanceof SCOID)
                {
                    throw new JPOXUserException(LOCALISER.msg("010006"));
                }
                else if (id instanceof OID)
                {
                    // OID, so check that the implied class is managed
                    originalClassName = getStoreManager().manageClassForIdentity(id, getClassLoaderResolver());
                }
                else if (api.isSingleFieldIdentity(id))
                {
                    // SingleFieldIdentity, so check that the implied class is managed
                    originalClassName = getStoreManager().manageClassForIdentity(id, getClassLoaderResolver());
                }
                else if (objectClassName != null)
                {
                    // Object class name specified so use that directly
                    originalClassName = objectClassName;
                }
                else
                {
                    // We dont know the object class so try to deduce it from what is known by the StoreManager
                    originalClassName = getStoreManager().getClassNameForObjectID(id, clr, this);
                    checkedClassName = true;
                }

                if (checkInheritance)
                {
                    // Verify if correct class inheritance level is set
                    if (!checkedClassName)
                    {
                        className = getStoreManager().getClassNameForObjectID(id, clr, this);
                    }
                    else
                    {
                        // We just checked the name of the class in the section above so just use that
                        className = originalClassName;
                    }
    
                    if (className == null)
                    {
                        throw new JPOXObjectNotFoundException(LOCALISER.msg("010026"), id);
                    }
    
                    if (originalClassName != null && !originalClassName.equals(className))
                    {
                        // Inheritance checking has found a different inherited
                        // object with this identity so create new id
                        if (id instanceof OID)
                        {
                            // Create new OID using correct target class
                            id = OIDFactory.getInstance(this, className, ((OID)id).getKeyValue());
    
                            // try again to read object from cache with this id
                            pc = getObjectFromCache(id);
                        }
                        else if (api.isSingleFieldIdentity(id))
                        {
                            // Create new SingleFieldIdentity using correct targetClass
                            id = api.getNewSingleFieldIdentity(id.getClass(), getClassLoaderResolver().classForName(className), 
                                    api.getTargetKeyForSingleFieldIdentity(id));
    
                            // try again to read object from cache with this id
                            pc = getObjectFromCache(id);
                        }
                    }
                }
                else
                {
                    className = originalClassName;
                }

                if (pc == null)
                {
                    // Still not found so create a Hollow instance with the supplied field values
                    try
                    {
                        Class pcClass = clr.classForName(className, (id instanceof OID) ? null : id.getClass().getClassLoader());
                        sm = StateManagerFactory.newStateManagerForHollow(this, pcClass, id);
                        pc = sm.getObject();
                        fromCache = false;
                    }
                    catch (ClassNotResolvedException e)
                    {
                        JPOXLogger.PERSISTENCE.warn(LOCALISER.msg("010027", id));
                        throw new JPOXUserException(LOCALISER.msg("010027", id), e);
                    }
                }
            }
        }

        if (validate)
        {
            // User requests validation of the instance so go to the datastore to validate it
            // loading any fetchplan fields that are needed in the process.
            if (sm == null)
            {
                sm = findStateManager(pc);
            }
            sm.validate();

            if (!fromCache)
            {
                // We created a Hollow PC earlier but then went to the datastore and let it find the real object
                // This allows the datastore to replace this temporary Hollow object with the real datastore object if required
                // This doesnt change with RDBMS datastores since we just pull in fields, but for DB4O we pull in object graphs
                pc = sm.getObject();
            }
        }

        if (sm != null)
        {
            // Cache the object (update it if already present)
            putObjectIntoCache(sm, !fromCache, true);
        }

        return pc;
    }

    /**
     * This method returns an object id instance corresponding to the pcClass and key arguments.
     * Operates in 2 modes :-
     * <ul>
     * <li>The class uses SingleFieldIdentity and the key is the value of the key field</li>
     * <li>In all other cases the key is the String form of the object id instance</li>
     * </ul>
     * @param pcClass Class of the PersistenceCapable to create the identity for
     * @param key Value of the key for SingleFieldIdentity (or the toString value)
     * @return The new object-id instance
     */
    public Object newObjectId(Class pcClass, Object key)
    {
        assertIsOpen();
        if (pcClass == null)
        {
            throw new JPOXUserException(LOCALISER.msg("010028"));
        }
        assertClassPersistable(pcClass);

        AbstractClassMetaData cmd = getMetaDataManager().getMetaDataForClass(pcClass, clr);
        if (cmd == null)
        {
            throw new NoPersistenceInformationException(pcClass.getName());
        }

        // If the class is not yet managed, manage it
        if (!getStoreManager().managesClass(cmd.getFullClassName()))
        {
            getStoreManager().addClass(cmd.getFullClassName(), clr);
        }

        Object id = null;
        if (cmd.usesSingleFieldIdentityClass())
        {
            // Single Field Identity
            Class idType = clr.classForName(cmd.getObjectidClass());
            id = getApiAdapter().getNewSingleFieldIdentity(idType, pcClass, key);
        }
        else if (key instanceof java.lang.String)
        {
            // String-based PK (datastore identity or application identity)
            if (cmd.getIdentityType() == IdentityType.APPLICATION)
            {
                if (Modifier.isAbstract(pcClass.getModifiers()) && cmd.getObjectidClass() != null) 
                {
                    try
                    {
                        Constructor c = clr.classForName(cmd.getObjectidClass()).getDeclaredConstructor(new Class[] {java.lang.String.class});
                        id = c.newInstance(new Object[] {(String)key});
                    }
                    catch(Exception e) 
                    {
                        String msg = LOCALISER.msg("010030", cmd.getObjectidClass(), cmd.getFullClassName());
                        JPOXLogger.PERSISTENCE.error(msg);
                        JPOXLogger.PERSISTENCE.error(e);

                        throw new JPOXUserException(msg);
                    }
                }
                else
                {
                    clr.classForName(pcClass.getName(), true);
                    id = getApiAdapter().getNewApplicationIdentityObjectId(pcClass, key);
                }
            }
            else
            {
                id = OIDFactory.getInstance(this, (String)key);
            }
        }
        else
        {
            // Key is not a string, and is not SingleFieldIdentity
            throw new JPOXUserException(LOCALISER.msg("010029", pcClass.getName(), key.getClass().getName()));
        }

        return id;
    }

    /**
     * Method to clear an object from the list of dirty objects.
     * @param sm The StateManager
     */
    public synchronized void clearDirty(StateManager sm)
    {
        dirtySMs.remove(sm);
        indirectDirtySMs.remove(sm);
    }

    /**
     * Method to clear all objects marked as dirty (whether directly or indirectly).
     */
    public synchronized void clearDirty()
    {
        dirtySMs.clear();
        indirectDirtySMs.clear();
    }

    /**
     * Method to mark an object (StateManager) as dirty.
     * @param sm The StateManager
     * @param directUpdate Whether the object has had a direct update made on it (if known)
     */
    public synchronized void markDirty(StateManager sm, boolean directUpdate)
    {
        if (tx.isCommitting() && !tx.isActive())
        {
            //post commit cannot change objects (sanity check - avoid changing avoids on detach)
            throw new JPOXException("Cannot change objects when transaction is no longer active.");
        }

        boolean isInDirty = dirtySMs.contains(sm);
        boolean isInIndirectDirty = indirectDirtySMs.contains(sm);
        if (!isDelayDatastoreOperationsEnabled() && !isInDirty && !isInIndirectDirty && 
            dirtySMs.size() >= getOMFContext().getPersistenceConfiguration().getDatastoreTransactionFlushLimit())
        {
            // Reached flush limit so flush
            flushInternal(false);
        }

        if (directUpdate)
        {
            if (isInIndirectDirty)
            {
                indirectDirtySMs.remove(sm);
                dirtySMs.add(sm);
            }
            else if (!isInDirty)
            {
                dirtySMs.add(sm);
            }
        }
        else
        {
            if (!isInDirty && !isInIndirectDirty)
            {
                // Register as an indirect dirty
                indirectDirtySMs.add(sm);
            }
        }
    }

    /**
     * Method to mark the specified StateManager as needing an update due to managed relation constraints.
     * @param sm The StateManager
     */
    public void markManagedRelationDirty(StateManager sm)
    {
        if (managedRelationDirtySMs == null)
        {
            managedRelationDirtySMs = new HashSet();
        }
        managedRelationDirtySMs.add(sm);
    }

    /**
     * Returns whether this ObjectManager is currently performing the manage relationships task.
     * @return Whether in the process of managing relations
     */
    public boolean isManagingRelations()
    {
        return managingRelations;
    }

    /**
     * Method to perform managed relationships tasks.
     * @throws JPOXUserException if a consistency check fails
     */
    protected void performManagedRelationships()
    {
        if (getOMFContext().getPersistenceConfiguration().getManageRelationships() &&
            managedRelationDirtySMs != null && managedRelationDirtySMs.size() > 0)
        {
            try
            {
                managingRelations = true;

                if (JPOXLogger.PERSISTENCE.isDebugEnabled())
                {
                    JPOXLogger.PERSISTENCE.debug(LOCALISER.msg("013000"));
                }

                if (getOMFContext().getPersistenceConfiguration().getManageRelationshipsChecks())
                {
                    // Tests for negative situations where inconsistently assigned
                    Iterator iter = managedRelationDirtySMs.iterator();
                    while (iter.hasNext())
                    {
                        StateManager sm = (StateManager)iter.next();
                        sm.checkManagedRelations();
                    }
                }

                // Process updates to manage the other side of the relations
                Iterator iter = managedRelationDirtySMs.iterator();
                while (iter.hasNext())
                {
                    StateManager sm = (StateManager)iter.next();
                    sm.processManagedRelations();
                    sm.clearManagedRelations();
                }
                managedRelationDirtySMs.clear();

                if (JPOXLogger.PERSISTENCE.isDebugEnabled())
                {
                    JPOXLogger.PERSISTENCE.debug(LOCALISER.msg("013001"));
                }
            }
            finally
            {
                managingRelations = false;
            }
        }
    }

    /**
     * Returns whether the ObjectManager is in the process of flushing.
     * @return true if the ObjectManager is flushing
     */
    public boolean isFlushing()
    {
        return flushing;
    }

    /**
     * Method callable from external APIs for user-management of flushing.
     * Called by JDO PM.flush, or JPA EM.flush().
     * Performs management of relations, prior to performing internal flush of all dirty/new/deleted
     * instances to the datastore.
     */
    public void flush()
    {
        assertIsOpen();
        if (tx.isActive())
        {
            // Managed Relationships
            performManagedRelationships();

            // Perform internal flush
            flushInternal(true);
        }
    }

    /**
     * This method flushes all dirty, new, and deleted instances to the
     * datastore. It has no effect if a transaction is not active. If a
     * datastore transaction is active, this method synchronizes the cache with
     * the datastore and reports any exceptions. If an optimistic transaction is
     * active, this method obtains a datastore connection and synchronizes the
     * cache with the datastore using this connection. The connection obtained
     * by this method is held until the end of the transaction.
     * @param flushToDatastore Whether to ensure any changes reach the datastore
     *     Otherwise they will be flushed to the datastore manager and leave it to
     *     decide the opportune moment to actually flush them to the datastore
     * @throws JPOXOptimisticException when optimistic locking error(s) occur
     */
    public synchronized void flushInternal(boolean flushToDatastore)
    {
        assertIsOpen();

        if (tx.isActive())
        {
            if (!flushToDatastore && dirtySMs.size() == 0 && indirectDirtySMs.size() == 0)
            {
                // Nothing to flush so abort now
                return;
            }

            if (JPOXLogger.PERSISTENCE.isDebugEnabled())
            {
                JPOXLogger.PERSISTENCE.debug(
                    LOCALISER.msg("010003", (dirtySMs.size() + indirectDirtySMs.size())));
            }
            flushing = true;
            try
            {
                List optimisticFailures = null;

                // Flush all dirty, new, deleted instances to the datastore when transaction is active
                Object[] toFlushDirect;
                synchronized(dirtySMs)
                {
                    toFlushDirect = dirtySMs.toArray();
                    dirtySMs.clear();
                }

                Object[] toFlushIndirect;
                synchronized(indirectDirtySMs)
                {
                    toFlushIndirect = indirectDirtySMs.toArray();
                    indirectDirtySMs.clear();
                }

                // a). direct dirty objects
                for (int i = 0; i < toFlushDirect.length; i++)
                {
                    StateManager sm = (StateManager) toFlushDirect[i];
                    try
                    {
                        sm.flush();
                    }
                    catch (JPOXOptimisticException oe)
                    {
                        if (optimisticFailures == null)
                        {
                            optimisticFailures = new ArrayList();
                        }
                        optimisticFailures.add(oe);
                    }
                }

                // b). indirect dirty objects
                for (int i = 0; i < toFlushIndirect.length; i++)
                {
                    StateManager sm = (StateManager) toFlushIndirect[i];
                    try
                    {
                        sm.flush();
                    }
                    catch (JPOXOptimisticException oe)
                    {
                        if (optimisticFailures == null)
                        {
                            optimisticFailures = new ArrayList();
                        }
                        optimisticFailures.add(oe);
                    }
                }

                // Make sure flushes its changes to the datastore
                if (flushToDatastore)
                {
                    tx.flush();
                }
                if (optimisticFailures != null)
                {
                    // Throw a single JPOXOptimisticException containing all optimistic failures
                    throw new JPOXOptimisticException(LOCALISER.msg("010031"), 
                        (Throwable[])optimisticFailures.toArray(new Throwable[optimisticFailures.size()]));
                }
            }
            finally
            {
                if (JPOXLogger.PERSISTENCE.isDebugEnabled())
                {
                    JPOXLogger.PERSISTENCE.debug(LOCALISER.msg("010004"));
                }
                flushing = false;
            }
        }
    }

    /** Flag for whether running persistence-by-reachability-at-commit */
    private boolean runningPBRAtCommit = false;

    /**
     * Method to perform any post-begin checks.
     */
    public synchronized void postBegin()
    {
        StateManager[] sms = (StateManager[])dirtySMs.toArray(new StateManager[dirtySMs.size()]);
        for (int i=0; i<sms.length; i++)
        {
            sms[i].preBegin(tx);
        }
        sms = (StateManager[])indirectDirtySMs.toArray(new StateManager[indirectDirtySMs.size()]);
        for (int i=0; i<sms.length; i++)
        {
            sms[i].preBegin(tx);
        }
    }

    /**
     * Method to perform any pre-commit checks.
     */
    public synchronized void preCommit()
    {
        // Make sure all is flushed before we start
        flush();

        if (omf.getPersistenceByReachabilityAtCommit())
        {
            // Persistence-by-reachability at commit
            try
            {
                runningPBRAtCommit = true;
                performReachabilityAtCommit();
                getTransaction().flush();
            }
            catch (Throwable t)
            {
                JPOXLogger.PERSISTENCE.error(t);
                if (t instanceof JPOXException)
                {
                    throw (JPOXException) t;
                }
                else
                {
                    throw new JPOXException("Unexpected error during precommit",t);
                }
            }
            finally
            {
                runningPBRAtCommit = false;
            }
        }

        if (detachAllOnCommit)
        {
            // "detach-on-commit"
            performDetachAllOnCommitPreparation();
        }
    }

    /**
     * Method to perform persistence-by-reachability at commit.
     * Utilises txKnownPersistedIds, and txFlushedNewIds, together with txKnownDeletedIds
     * and runs reachability, performing any necessary delettions of no longer reachable objects.
     */
    private void performReachabilityAtCommit()
    {
        if (JPOXLogger.REACHABILITY.isDebugEnabled())
        {
            JPOXLogger.REACHABILITY.debug(LOCALISER.msg("010032"));
        }

        // If we have some new objects in this transaction, and we have some known persisted objects (either
        // from makePersistent in this txn, or enlisted existing objects) then run reachability checks
        if (txKnownPersistedIds.size() > 0 && txFlushedNewIds.size() > 0)
        {
            Set currentReachables = new HashSet();

            // Run "reachability" on all known persistent objects for this txn
            Object ids[] = txKnownPersistedIds.toArray();
            Set objectNotFound = new HashSet();
            for (int i=0; i<ids.length; i++)
            {
                if (!txKnownDeletedIds.contains(ids[i]))
                {
                    if (JPOXLogger.REACHABILITY.isDebugEnabled())
                    {
                        JPOXLogger.REACHABILITY.debug("Performing reachability algorithm on object with id \""+ids[i]+"\"");
                    }
                    try
                    {
                        StateManager sm = findStateManager(findObject(ids[i], true, true, null));
                        sm.runReachability(currentReachables);
                        if (i % 10000 == 0 || i == ids.length-1)
                        {
                            // Flush every 10000 or on the last one to make sure tx cache is empty
                            flushInternal(true);
                        }
                    }
                    catch (JPOXObjectNotFoundException ex)
                    {
                        objectNotFound.add(ids[i]);
                    }
                }
                else
                {
                    // Was deleted earlier so ignore
                }
            }

            // Remove any of the "reachable" instances that are no longer "reachable"
            txFlushedNewIds.removeAll(currentReachables);

            Object nonReachableIds[] = txFlushedNewIds.toArray();
            if (nonReachableIds != null && nonReachableIds.length > 0)
            {
                // For all of instances no longer reachable we need to delete them from the datastore
                // A). Nullify all of their fields.
                // TODO See CORE-3276 for a possible change to this
                for (int i=0; i<nonReachableIds.length; i++)
                {
                    if (JPOXLogger.REACHABILITY.isDebugEnabled())
                    {
                        JPOXLogger.REACHABILITY.debug(
                            LOCALISER.msg("010033", nonReachableIds[i]));
                    }
                    try
                    {
                        if (!objectNotFound.contains(nonReachableIds[i]))
                        {
                            StateManager sm = findStateManager(findObject(nonReachableIds[i], true, true, null));
                            sm.nullifyFields();

                            if (i % 10000 == 0 || i == nonReachableIds.length-1)
                            {
                                // Flush every 10000 or on the last one to clear out dirties
                                flushInternal(true);
                            }
                        }
                    }
                    catch (JPOXObjectNotFoundException ex)
                    {
                        // just ignore if the object does not exist anymore  
                    }
                }

                // B). Remove the objects
                for (int i=0; i<nonReachableIds.length; i++)
                {
                    try
                    {
                        if (!objectNotFound.contains(nonReachableIds[i]))
                        {
                            StateManager sm = findStateManager(findObject(nonReachableIds[i], true, true, null));
                            sm.deletePersistent();
                            if (i % 10000 == 0 || i == nonReachableIds.length-1)
                            {
                                // Flush every 10000 or on the last one to clear out dirties
                                flushInternal(true);
                            }
                        }
                    }
                    catch (JPOXObjectNotFoundException ex)
                    {
                        //just ignore if the file does not exist anymore  
                    }
                }
            }
        }

        if (JPOXLogger.REACHABILITY.isDebugEnabled())
        {
            JPOXLogger.REACHABILITY.debug(LOCALISER.msg("010034"));
        }
    }

    /**
     * Temporary array of StateManagers to detach at commit (to prevent garbage collection). 
     * Set up in preCommit() and used in postCommit().
     */
    private StateManager[] detachAllOnCommitSMs = null;

    /**
     * Method to perform all necessary preparation for detach-all-on-commit.
     * Identifies all objects affected and makes sure that all fetch plan fields are loaded.
     */
    private void performDetachAllOnCommitPreparation()
    {
        // JDO2 spec 12.7.3 "Root instances"
        // "Root instances are parameter instances for retrieve, detachCopy, and refresh; result
        // instances for queries. Root instances for DetachAllOnCommit are defined explicitly by
        // the user via the FetchPlan property DetachmentRoots or DetachmentRootClasses. 
        // If not set explicitly, the detachment roots consist of the union of all root instances of
        // methods executed since the last commit or rollback."
        Collection sms = new ArrayList();
        Collection roots = fetchPlan.getDetachmentRoots();
        Class[] rootClasses = fetchPlan.getDetachmentRootClasses();
        if (roots != null && roots.size() > 0)
        {
            // Detachment roots specified
            Iterator rootsIter = roots.iterator();
            while (rootsIter.hasNext())
            {
                Object obj = rootsIter.next();
                sms.add(findStateManager(obj));
            }
        }
        else if (rootClasses != null && rootClasses.length > 0)
        {
            // Detachment root classes specified
            StateManager[] txSMs = (StateManager[])enlistedSMCache.values().toArray(new StateManager[enlistedSMCache.size()]);
            for (int i=0;i<txSMs.length;i++)
            {
                for (int j=0;j<rootClasses.length;j++)
                {
                    // Check if object is of this root type
                    if (txSMs[i].getObject().getClass() == rootClasses[j])
                    {
                        // This SM is for a valid root object
                        sms.add(txSMs[i]);
                        break;
                    }
                }
            }
        }
        else
        {
            // Detach all objects in the L1 cache
            sms.addAll(cache.values());
        }

        // Make sure that all FetchPlan fields are loaded
        Iterator smsIter = sms.iterator();
        while (smsIter.hasNext())
        {
            StateManager sm = (StateManager)smsIter.next();
            Object pc = sm.getObject();
            if (pc != null && !getApiAdapter().isDetached(pc) && !getApiAdapter().isDeleted(pc))
            {
                // Load all fields (and sub-objects) in the FetchPlan
                FetchPlanState state = new FetchPlanState();
                try
                {
                    sm.loadFieldsInFetchPlan(state);
                }
                catch (JPOXObjectNotFoundException onfe)
                {
                    // This object doesnt exist in the datastore at this point.
                    // Either the user has some other process that has deleted it or they have
                    // defined datastore based cascade delete and it has been deleted that way
                    JPOXLogger.PERSISTENCE.warn(LOCALISER.msg("010013",
                        StringUtils.toJVMIDString(pc), sm.getInternalObjectId()));
                    smsIter.remove();
                    // TODO Move the object state to P_DELETED for consistency
                }
            }
        }
        detachAllOnCommitSMs = (StateManager[])sms.toArray(new StateManager[sms.size()]);
    }

    /**
     * Method to perform detach-all-on-commit, using the data identified by
     * performDetachAllOnCommitPreparation().
     */
    private void performDetachAllOnCommit()
    {
        try
        {
            runningDetachAllOnCommit = true;

            // Detach all detachment root objects (causes recursion through the fetch plan)
            StateManager[] smsToDetach = detachAllOnCommitSMs;
            DetachState state = new DetachState(getApiAdapter());
            for (int i=0;i<smsToDetach.length;i++)
            {
                Object pc = smsToDetach[i].getObject();
                if (pc != null)
                {
                    smsToDetach[i].detach(state);
                }
            }
            detachAllOnCommitSMs = null; // No longer need these references
        }
        finally
        {
            runningDetachAllOnCommit = false;
        }
    }

    /**
     * Accessor for whether this ObjectManager is currently running detachAllOnCommit.
     * @return Whether running detachAllOnCommit
     */
    public boolean isRunningDetachAllOnCommit()
    {
        return runningDetachAllOnCommit;
    }

    /**
     * Method to perform detach on close (of the ObjectManager).
     */
    private void performDetachOnClose()
    {
        JPOXLogger.PERSISTENCE.debug(LOCALISER.msg("010011"));
        try
        {
            // Start a transaction in case we need to load any unloaded fields
            tx.begin();

            List toDetach = new ArrayList();
            toDetach.addAll(cache.values());
            Iterator iter = toDetach.iterator();
            while (iter.hasNext())
            {
                Object obj = iter.next();
                StateManager sm = (StateManager) obj;
                if (sm != null)
                {
                    //TODO why SM is in cache if null state ...
                    if (sm != null && sm.getObject() != null && 
                        !sm.getObjectManager().getApiAdapter().isDeleted(sm.getObject()))
                    {
                        try
                        {
                            sm.detach(new DetachState(getApiAdapter()));
                        }
                        catch (JPOXObjectNotFoundException onfe)
                        {
                            // Catch exceptions for any objects that are deleted in other managers whilst having this open
                        }
                    }
                }
            }
            tx.commit();
        }
        finally
        {
            if (tx.isActive())
            {
                tx.rollback();
            }
        }
        JPOXLogger.PERSISTENCE.debug(LOCALISER.msg("010012"));
    }

    /**
     * Commit any changes made to objects managed by the persistence manager to the database.
     */
    public synchronized void postCommit()
    {
        if (detachAllOnCommit)
        {
            // Detach-all-on-commit
            performDetachAllOnCommit();
        }

        List failures = null;
        try
        {
            // Commit all enlisted StateManagers
            ApiAdapter api = getApiAdapter();
            StateManager[] sms = (StateManager[]) enlistedSMCache.values().toArray(new StateManager[enlistedSMCache.size()]);
            for (int i = 0; i < sms.length; ++i)
            {
                try
                {
                    // Perform any operations required after committing
                    //TODO this if is due to sms that can have lc == null, why?, should not be here then
                    if (sms[i] != null && 
                        sms[i].getObject() != null &&
                        (api.isPersistent(sms[i].getObject()) || api.isTransactional(sms[i].getObject())))
                    {
                        sms[i].postCommit(getTransaction());
    
                        // TODO Change this check so that we remove all objects that are no longer suitable for caching
                        if (detachAllOnCommit && api.isDetachable(sms[i].getObject()))
                        {
                            // "DetachAllOnCommit" - Remove the object from the L1 cache since it is now detached
                            removeStateManager(sms[i]);
                        }
                    }
                }
                catch (RuntimeException e)
                {
                    if (failures == null)
                    {
                        failures = new ArrayList();
                    }
                    failures.add(e);
                }
            }
        }
        finally
        {
            enlistedSMCache.clear();
            txEnlistedIds.clear();
            txKnownPersistedIds.clear();
            txKnownDeletedIds.clear();
            txFlushedNewIds.clear();
            fetchPlan.resetDetachmentRoots();
            if (managedRelationDirtySMs != null)
            {
                managedRelationDirtySMs.clear();
            }
        }
        if (failures != null && !failures.isEmpty())
        {
            throw new CommitStateTransitionException((Exception[]) failures.toArray(new Exception[failures.size()]));
        }
    }

    /**
     * Rollback any changes made to objects managed by the persistence manager
     * to the database.
     */
    public synchronized void preRollback()
    {
        ArrayList failures = null;
        try
        {
            Collection sms = enlistedSMCache.values();
            Iterator smsIter = sms.iterator();
            while (smsIter.hasNext())
            {
                StateManager sm = (StateManager)smsIter.next();
                try
                {
                    sm.preRollback(getTransaction());
                }
                catch (RuntimeException e)
                {
                    if (failures == null)
                    {
                        failures = new ArrayList();
                    }
                    failures.add(e);
                }
            }
            clearDirty();
        }
        finally
        {
            enlistedSMCache.clear();
            txEnlistedIds.clear();
            txKnownPersistedIds.clear();
            txKnownDeletedIds.clear();
            txFlushedNewIds.clear();
            if (managedRelationDirtySMs != null)
            {
                managedRelationDirtySMs.clear();
            }
        }
        if (failures != null && !failures.isEmpty())
        {
            throw new RollbackStateTransitionException((Exception[]) failures.toArray(new Exception[failures.size()]));
        }
    }

    // -------------------------------------- Cache Management ---------------------------------------

    /**
     * Replace the previous object id for a persistable object with a new one.
     * This is used where we have already added the object to the cache(s) and/or enlisted it in the txn before
     * its real identity was fixed (attributed in the datastore).
     * @param pc The Persistable object
     * @param oldID the old id it was known by
     * @param newID the new id
     */
    public synchronized void replaceObjectId(Object pc, Object oldID, Object newID)
    {
        if (pc == null || getApiAdapter().getIdForObject(pc) == null)
        {
            JPOXLogger.CACHE.warn(LOCALISER.msg("003006"));
            return;
        }

        Object o = cache.get(oldID); //use get() because a cache.remove operation returns a weakReference instance
        if (o != null)
        {
            // Remove the old variant
            if (JPOXLogger.CACHE.isDebugEnabled())
            {
                JPOXLogger.CACHE.debug(LOCALISER.msg("003012", StringUtils.toJVMIDString(pc), oldID, newID));
            }
            cache.remove(oldID);
        }

        // Put into both caches
        StateManager sm = findStateManager(pc);
        if (sm != null)
        {
            putObjectIntoCache(sm, true, true);
        }

        if (enlistedSMCache.get(oldID) != null)
        {
            // Swap the enlisted object identity
            if (sm != null)
            {
                enlistedSMCache.remove(oldID);
                enlistedSMCache.put(newID, sm);
                if (JPOXLogger.TRANSACTION.isDebugEnabled())
                {
                    JPOXLogger.TRANSACTION.debug(LOCALISER.msg("015018",
                        StringUtils.toJVMIDString(pc), oldID, newID));
                }
            }
        }

        if (omf.getPersistenceByReachabilityAtCommit())
        {
            if (txEnlistedIds.remove(oldID))
            {
                txEnlistedIds.add(newID);
            }
            if (txFlushedNewIds.remove(oldID))
            {
                txFlushedNewIds.add(newID);
            }
            if (txKnownPersistedIds.remove(oldID))
            {
                txKnownPersistedIds.add(newID);
            }
            if (txKnownDeletedIds.remove(oldID))
            {
                txKnownDeletedIds.add(newID);
            }
        }
    }

    /**
     * Convenience method to add an object to the cache(s).
     * @param sm The State Manager
     * @param level1 Whether to put it in the L1 cache
     * @param level2 Whether to put it in the L2 cache
     */
    public synchronized void putObjectIntoCache(StateManager sm, boolean level1, boolean level2)
    {
        Object id = sm.getInternalObjectId();
        if (id == null || sm.getObject() == null)
        {
            JPOXLogger.CACHE.warn(LOCALISER.msg("003006"));
            return;
        }

        // Put into Level 1 Cache
        if (level1)
        {
            Object oldSM = cache.put(sm.getInternalObjectId(), sm);
            if (JPOXLogger.CACHE.isDebugEnabled())
            {
                if (oldSM == null)
                {
                    JPOXLogger.CACHE.debug(LOCALISER.msg("003004", 
                        StringUtils.toJVMIDString(sm.getObject()), sm.getInternalObjectId()));
                }
                else
                {
                    JPOXLogger.CACHE.debug(LOCALISER.msg("003005", 
                        StringUtils.toJVMIDString(sm.getObject()), sm.getInternalObjectId()));
                }
            }
        }

        // Put into Level 2 Cache
        if (level2 && this.omf.getCacheLevel2())
        {
            boolean storeInL2Cache = true;
            AbstractClassMetaData acmd = getMetaDataManager().getMetaDataForClass(sm.getObject().getClass(), clr);
            if (acmd != null && acmd.getIdentityType() == IdentityType.APPLICATION)
            {
                // If using compound identity dont put it in the L2 Cache (the id uses a PC which we can't link to)
                int[] pkFieldNumbers = acmd.getPKMemberPositions();
                for (int i=0;i<pkFieldNumbers.length;i++)
                {
                    AbstractMemberMetaData fmd = acmd.getMetaDataForManagedMemberAtAbsolutePosition(pkFieldNumbers[i]);
                    if (getApiAdapter().isPersistable(fmd.getType()))
                    {
                        storeInL2Cache = false;
                    }
                }
            }

            if (storeInL2Cache)
            {
                if (JPOXLogger.CACHE.isDebugEnabled())
                {
                    JPOXLogger.CACHE.debug(LOCALISER.msg("004003",
                        StringUtils.toJVMIDString(sm.getObject()), id));
                }
                // Store an L2 cacheable form of this object
                CachedPC pcCopy = sm.getL2CacheableObject();
                this.omf.getLevel2Cache().put(id, pcCopy);
            }
        }
    }

    /**
     * Convenience method to evict an object from the cache(s).
     * @param pc The Persistpable object
     * @param id The Persistable object id
     * @param level1 Whether to evict from the L1 cache
     * @param level2 Whether to evict from the L2 cache
     */
    public synchronized void removeObjectFromCache(Object pc, Object id, boolean level1, boolean level2)
    {
        // Evict from the L1 cache
        if (level1 && id != null)
        {
            if (JPOXLogger.CACHE.isDebugEnabled())
            {
                JPOXLogger.CACHE.debug(LOCALISER.msg("003009", 
                    StringUtils.toJVMIDString(pc), id, String.valueOf(cache.size())));
            }
            Object pcRemoved = cache.remove(id);
            if (pcRemoved == null && JPOXLogger.CACHE.isDebugEnabled())
            {
                // For some reason the object isn't in the L1 cache - garbage collected maybe ?
                JPOXLogger.CACHE.debug(LOCALISER.msg("003010",
                    StringUtils.toJVMIDString(pc), id));
            }
        }

        // Evict from the L2 cache
        if (level2 && omf.getCacheLevel2() && getApiAdapter().getIdForObject(pc) != null)
        {
            Level2Cache l2Cache = omf.getLevel2Cache();
            if (JPOXLogger.CACHE.isDebugEnabled())
            {
                JPOXLogger.CACHE.debug(LOCALISER.msg("004007", 
                    StringUtils.toJVMIDString(pc), getApiAdapter().getIdForObject(pc), String.valueOf(l2Cache.getSize())));
            }
            l2Cache.evict(getApiAdapter().getIdForObject(pc));
        }
    }

    /**
     * Convenience method to access an object in the cache.
     * Firstly looks in the L1 cache for this ObjectManager, and if not found looks in the L2 cache.
     * @param id Id of the object
     * @return Persistence Capable object (with connected StateManager).
     */
    public synchronized Object getObjectFromCache(Object id)
    {
        Object pc = null;

        // Try Level 1 first
        StateManager sm = (StateManager)cache.get(id);
        if (sm != null)
        {
            pc = sm.getObject();
            
            if (JPOXLogger.CACHE.isDebugEnabled())
            {
                JPOXLogger.CACHE.debug(LOCALISER.msg("003008", StringUtils.toJVMIDString(pc), 
                    id, "" + cache.size()));
            }
            // Wipe the detach state that may have been added if the object has been serialised in the meantime
            sm.resetDetachState();

            return pc;
        }
        else
        {
            if (JPOXLogger.CACHE.isDebugEnabled())
            {
                JPOXLogger.CACHE.debug(LOCALISER.msg("003007", id, "" + cache.size()));
            }
        }

        // Try Level 2 since not in Level 1
        if (omf.getCacheLevel2())
        {
            Level2Cache l2Cache = omf.getLevel2Cache();
            CachedPC cachedPC = l2Cache.get(id);

            // Copy the cached object and connect to a StateManager, with the same object id
            if (cachedPC != null)
            {
                sm = StateManagerFactory.newStateManagerForCachedPC(this, 
                    cachedPC.getPersistableObject(), id, cachedPC.getLoadedFields());
                pc = sm.getObject();
                if (JPOXLogger.CACHE.isDebugEnabled())
                {
                    JPOXLogger.CACHE.debug(LOCALISER.msg("004006", 
                        StringUtils.toJVMIDString(pc), id, "" + l2Cache.getSize()));
                }
                cache.put(id, sm); // Put into L1 cache for easy referencing
                return pc;
            }
            else
            {
                if (JPOXLogger.CACHE.isDebugEnabled())
                {
                    JPOXLogger.CACHE.debug(LOCALISER.msg("004005", 
                        id, "" + l2Cache.getSize()));
                }
            }
        }

        return null;
    }

    // ------------------------------------- Queries/Extents --------------------------------------

    /**
     * Extents are collections of datastore objects managed by the datastore,
     * not by explicit user operations on collections. Extent capability is a
     * boolean property of classes that are persistence capable. If an instance
     * of a class that has a managed extent is made persistent via reachability,
     * the instance is put into the extent implicitly.
     * @param pcClass The class to query
     * @param subclasses Whether to include subclasses in the query.
     * @return returns an Extent that contains all of the instances in the
     * parameter class, and if the subclasses flag is true, all of the instances
     * of the parameter class and its subclasses.
     */
    public synchronized Extent getExtent(Class pcClass, boolean subclasses)
    {
        assertIsOpen();
        ClassLoaderResolver clr = getClassLoaderResolver();
        try
        {
            clr.setPrimary(pcClass.getClassLoader());
            assertClassPersistable(pcClass);

            return getStoreManager().getExtent(this, pcClass, subclasses);
        }
        catch (JPOXException jpe)
        {
            // Convert any JPOX exceptions into what JDO expects
            throw JPOXJDOHelper.getJDOExceptionForJPOXException(jpe);
        }
        finally
        {
            clr.unsetPrimary();
        }
    }

    /**
     * Construct an empty query instance.
     * @return The query
     */
    public synchronized Query newQuery()
    {
        return getOMFContext().getQueryManager().newQuery("javax.jdo.query.JDOQL", this, null);
    }

    // ------------------------------------- Callback Listeners --------------------------------------

    /**
     * This method removes all previously registered lifecycle listeners.
     * It is necessary to make sure, that a cached ObjectManager (in j2ee environment)
     * will have no listener before the listeners are copied from the OMF.
     * Otherwise they might be registered multiple times.
     */
    public void removeAllInstanceLifecycleListeners()
    {
        if (callbacks != null)
        {
            callbacks.close();
        }
    }

    /**
     * Retrieve the callback handler for this ObjectManager.
     * @return the callback handler
     */
    public CallbackHandler getCallbackHandler()
    {
        if (callbacks != null)
        {
            return callbacks;
        }

        String callbackHandlerClassName = getOMFContext().getPluginManager().getAttributeValueForExtension("org.jpox.callbackhandler",
            "name", getOMFContext().getApi(), "class-name");
        if (callbackHandlerClassName != null)
        {
            try
            {
                callbacks = (CallbackHandler) clr.classForName(callbackHandlerClassName,OMFContext.class.getClassLoader()).newInstance();
                return callbacks;
            }
            catch (InstantiationException e)
            {
                JPOXLogger.PERSISTENCE.error(LOCALISER.msg("025000", callbackHandlerClassName, e));
            }
            catch (IllegalAccessException e)
            {
                JPOXLogger.PERSISTENCE.error(LOCALISER.msg("025000", callbackHandlerClassName, e));
            }
        }

        return null;
    }

    /**
     * Method to register a listener for instances of the specified classes.
     * @param listener The listener to sends events to
     * @param classes The classes that it is interested in
     */
    public void addListener(Object listener, Class[] classes)
    {
        assertIsOpen();
        if (listener == null)
        {
            return;
        }
        getCallbackHandler().addListener(listener, classes);
    }

    /**
     * Method to remove a currently registered listener.
     * @param listener The listener to remove.
     */
    public void removeListener(Object listener)
    {
        assertIsOpen();
        if (listener != null)
        {
            getCallbackHandler().removeListener(listener);
        }
    }

    /**
     * Disconnect the registered LifecycleListener
     */
    public void disconnectLifecycleListener()
    {
        // Clear out lifecycle listeners that were registered
        if (callbacks != null)
        {
            callbacks.close();
        }
    }

    // ------------------------------- Assert Utilities ---------------------------------

    /**
     * Method to assert if this Object Manager is open. 
     * Throws a JPOXUserException if the ObjectManager is closed.
     */
    protected void assertIsOpen()
    {
        if (isClosed())
        {
            throw new JPOXUserException(LOCALISER.msg("010002")).setFatal();
        }
    }

    /**
     * Method to assert if the specified class is Persistence Capable.
     * @param cls The class to check
     * @throws ClassNotPersistableException if class is not persistable
     * @throws NoPersistenceInformationException if no metadata/annotations are found for class
     */
    public void assertClassPersistable(Class cls)
    {
        if (cls != null && !getOMFContext().getApiAdapter().isPersistable(cls) && !cls.isInterface())
        {
            throw new ClassNotPersistableException(cls.getName());
        }
        if (!hasPersistenceInformationForClass(cls))
        {
            throw new NoPersistenceInformationException(cls.getName());
        }
    }

    /**
     * Method to assert if the specified object is Detachable. 
     * Throws a ClassNotDetachableException if not capable
     * @param object The object to check
     */
    protected void assertDetachable(Object object)
    {
        if (object != null && !getApiAdapter().isDetachable(object))
        {
            throw new ClassNotDetachableException(object.getClass().getName());
        }
    }

    /**
     * Method to assert if the specified object is detached.
     * Throws a ObjectDetachedException if it is detached.
     * @param object The object to check
     */
    protected void assertNotDetached(Object object)
    {
        if (object != null && getApiAdapter().isDetached(object))
        {
            throw new ObjectDetachedException(object.getClass().getName());
        }
    }

    /**
     * Method to assert if the current transaction is active. Throws a
     * TransactionNotActiveException if not active
     */
    protected void assertActiveTransaction()
    {
        if (!tx.isActive())
        {
            throw new TransactionNotActiveException();
        }
    }
    
    /**
     * Method to assert if the current transaction is active or non transactional
     * writes are allowed.
     * @throws a TransactionNotActiveException if not active and non transactional writes are disabled
     */
    protected void assertWritable()
    {
        if (!getTransaction().isActive() && !getTransaction().getNontransactionalWrite())
        {
            throw new TransactionNotActiveException();
        }
    }
    

    /**
     * Validates that an ImplementationCreator instance is accessible.
     * @throws JPOXUserException if an ImplementationCreator instance does not exist
     */
    protected void assertHasImplementationCreator()
    {
        if (getOMFContext().getImplementationCreator() == null)
        {
            throw new JPOXUserException(LOCALISER.msg("010035"));
        }
    }
    
    /**
     * Method to assert if no active transaction and nontransactionalRead is not set.
     * @param operation The operation being performed (used in error reporting)
     * @throws JPOXUserException if the tx is not active and no non-transactional read is available
     */
    protected void assertActiveTransactionOrNontransactionRead(String operation)
    {
        if (!tx.isActive() && !tx.getNontransactionalRead())
        {
            throw new JPOXUserException(LOCALISER.msg("011009", operation));
        }
    }

    /**
     * Utility method to check if the specified class has reachable metadata or annotations.
     * @param cls The class to check
     * @return Whether the class has reachable metadata or annotations
     */
    public boolean hasPersistenceInformationForClass(Class cls)
    {
        if (cls == null)
        {
            return false;
        }
        
        if ((getMetaDataManager().getMetaDataForClass(cls, getClassLoaderResolver()) != null))
        {
            return true;
        }

        if (cls.isInterface())
        {
            // JDO2 "persistent-interface"
            // Try to create an implementation of the interface at runtime. 
            // It will register the MetaData and make an implementation available
            try
            {
                newInstance(cls);
            }
            catch (RuntimeException ex)
            {
                JPOXLogger.PERSISTENCE.warn(ex);
            }
            return getMetaDataManager().getMetaDataForClass(cls, getClassLoaderResolver()) != null;
        }
        return false;
    }
}
java2s.com  | Contact Us | Privacy Policy
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.