Class ExecutionContextImpl

  • All Implemented Interfaces:
    ExecutionContextReference, ExecutionContext, TransactionEventListener
    Direct Known Subclasses:
    ExecutionContextThreadedImpl

    public class ExecutionContextImpl
    extends Object
    implements ExecutionContext, TransactionEventListener
    Manager for persistence/retrieval of objects within an execution context, equating to the work required by JDO PersistenceManager and JPA EntityManager.

    Caching

    An ExecutionContext 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 placed in the Level 1 cache during the transaction. The NucleusContext also has a Level 2 cache. This is used to allow cross-communication between ExecutionContexts. Objects are placed in the Level 2 cache during commit() of a transaction. If an object is deleted during a transaction then it will be removed from the Level 2 cache at commit(). If an object is no longer enlisted in the transaction at commit then it will be removed from the Level 2 cache (so we remove the chance of handing out old data).

    Transactions

    An ExecutionContext has a single transaction (the "current" transaction). The transaction can be "active" (if begin() has been called on it) or "inactive".

    Persisted Objects

    When an object involved in the current transaction it is enlisted (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.

    StateManager-based storage

    You may note that we have various fields here storing StateManager-related information such as which StateManager is embedded into which StateManager etc, or the managed relations for a StateManager. These are stored here to avoid adding a reference to the storage of each and every StateManager, since we could potentially have a very large number of StateManagers (and they may not use that field in the majority, but it still needs the reference). The same should be followed as a general rule when considering storing something in StateManager.

    This class is NOT thread-safe. Use ExecutionContextThreadedImpl if you want to *attempt* to have multithreaded PM/EMs.

    • Field Detail

      • cache

        protected Level1Cache cache
        Level 1 Cache, essentially a Map of StateManager keyed by the id.
      • stateManagerAssociatedValuesMap

        protected Map<DNStateManager,​Map<?,​?>> stateManagerAssociatedValuesMap
        Map of associated values per StateManager. This can contain anything really and is down to the StoreManager to define. For example RDBMS datastores typically put external FK info in here keyed by the mapping of the field to which it pertains.
    • Constructor Detail

      • ExecutionContextImpl

        public ExecutionContextImpl​(PersistenceNucleusContext ctx,
                                    Object owner,
                                    Map<String,​Object> options)
        Constructor. TODO userName/password aren't currently used and we always use the PMF/EMF userName/password.
        Parameters:
        ctx - NucleusContext
        owner - Owning object (for bytecode enhancement contract, PersistenceManager)
        options - Any options affecting startup
        Throws:
        NucleusUserException - if an error occurs allocating the necessary requested components
    • Method Detail

      • close

        public void close()
        Method to close the context.
        Specified by:
        close in interface ExecutionContext
      • setLevel2Cache

        protected void setLevel2Cache​(boolean flag)
        Method to set whether we are supporting the Level2 Cache with this ExecutionContext Note that if the NucleusContext has no Level2 Cache enabled then you cannot turn it on here.
        Parameters:
        flag - Whether to enable/disable it
      • isClosed

        public boolean isClosed()
        Accessor for whether this context is closed.
        Specified by:
        isClosed in interface ExecutionContext
        Returns:
        Whether this manager is closed.
      • acquireThreadContextInfo

        protected org.datanucleus.ExecutionContextImpl.ThreadContextInfo acquireThreadContextInfo()
        Accessor for the thread context information, for the current thread. If the current thread is not present, will add an info context for it.

        You must call releaseThreadContextInfo() when you don't need it anymore, since we use reference counting. Use a try...finally-block for this purpose.

        Returns:
        The thread context information
        See Also:
        getThreadContextInfo()
      • getThreadContextInfo

        protected org.datanucleus.ExecutionContextImpl.ThreadContextInfo getThreadContextInfo()
        Get the current ThreadContextInfo assigned to the current thread without changing the reference counter.
        Returns:
        the thread context information
        See Also:
        acquireThreadContextInfo()
      • releaseThreadContextInfo

        protected void releaseThreadContextInfo()
        Method to remove the current thread context info for the current thread, after the reference counter reached 0. This method decrements a reference counter (per thread), that is incremented by acquireThreadContextInfo().
        See Also:
        acquireThreadContextInfo()
      • initialiseLevel1Cache

        protected void initialiseLevel1Cache()
        Method to initialise the L1 cache.
        Throws:
        NucleusUserException - if an error occurs setting up the L1 cache
      • getOwner

        public Object getOwner()
        Accessor for the owner of this ExecutionContext. This will typically be PersistenceManager (JDO) or EntityManager (JPA).
        Specified by:
        getOwner in interface ExecutionContextReference
        Returns:
        The owner
      • setProperties

        public void setProperties​(Map props)
        Description copied from interface: ExecutionContext
        Method to set properties on the execution context.
        Specified by:
        setProperties in interface ExecutionContext
        Parameters:
        props - The properties
      • setProperty

        public void setProperty​(String name,
                                Object value)
        Description copied from interface: ExecutionContext
        Method to set a property on the execution context
        Specified by:
        setProperty in interface ExecutionContext
        Parameters:
        name - Name of the property
        value - Value to set
      • getMultithreaded

        public boolean getMultithreaded()
        Accessor for whether the usage is multi-threaded.
        Specified by:
        getMultithreaded in interface ExecutionContext
        Returns:
        False
      • getFlushMode

        public FlushMode getFlushMode()
        Description copied from interface: ExecutionContext
        Accessor for the flush mode. Whether to auto-commit, or whether to delay flushing.
        Specified by:
        getFlushMode in interface ExecutionContext
        Returns:
        The flush mode.
      • isDelayDatastoreOperationsEnabled

        public boolean isDelayDatastoreOperationsEnabled()
        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.
        Specified by:
        isDelayDatastoreOperationsEnabled in interface ExecutionContext
        Returns:
        true if datastore operations are delayed until commit/flush
      • getTenantId

        public String getTenantId()
        Description copied from interface: ExecutionContext
        Accessor for the tenant id, for this ExecutionContext.
        Specified by:
        getTenantId in interface ExecutionContext
        Returns:
        The tenant id for this context.
      • getCurrentUser

        public String getCurrentUser()
        Description copied from interface: ExecutionContext
        Accessor for the current user, for this ExecutionContext.
        Specified by:
        getCurrentUser in interface ExecutionContext
        Returns:
        The current user for this context
      • isInserting

        public boolean isInserting​(Object pc)
        Tests whether this persistable object is in the process of being inserted.
        Specified by:
        isInserting in interface ExecutionContext
        Parameters:
        pc - the object to verify the status
        Returns:
        true if this instance is inserting.
      • enlistInTransaction

        public void enlistInTransaction​(DNStateManager sm)
        Method to enlist the specified StateManager in the current transaction.
        Specified by:
        enlistInTransaction in interface ExecutionContext
        Parameters:
        sm - StateManager
      • evictFromTransaction

        public void evictFromTransaction​(DNStateManager sm)
        Method to evict the specified StateManager from the current transaction.
        Specified by:
        evictFromTransaction in interface ExecutionContext
        Parameters:
        sm - StateManager
      • isEnlistedInTransaction

        public boolean isEnlistedInTransaction​(Object id)
        Method to return if an object is enlisted in the current transaction. This is only of use when running "persistence-by-reachability" at commit.
        Specified by:
        isEnlistedInTransaction in interface ExecutionContext
        Parameters:
        id - Identity for the object
        Returns:
        Whether it is enlisted in the current transaction
      • getAttachedObjectForId

        public Object getAttachedObjectForId​(Object id)
        Convenience method to return the attached object for the specified id if one exists. Returns null if there is no currently enlisted/cached object with the specified id.
        Specified by:
        getAttachedObjectForId in interface ExecutionContext
        Parameters:
        id - The id
        Returns:
        The attached object
      • addStateManagerToCache

        public void addStateManagerToCache​(DNStateManager sm)
        Method to add the object managed by the specified StateManager to the (L1) cache.
        Specified by:
        addStateManagerToCache in interface ExecutionContext
        Parameters:
        sm - StateManager
      • findStateManager

        public DNStateManager findStateManager​(Object pc)
        Method to return StateManager for an object (if managed).
        Specified by:
        findStateManager in interface ExecutionContext
        Parameters:
        pc - The object we are checking
        Returns:
        StateManager, null if not found.
        Throws:
        NucleusUserException - if the persistable object is managed by a different ExecutionContext
      • findStateManager

        public DNStateManager findStateManager​(Object pc,
                                               boolean persist)
        Find StateManager for the specified object, persisting it if required.
        Specified by:
        findStateManager in interface ExecutionContext
        Parameters:
        pc - The persistable object
        persist - persists the object if not yet persisted.
        Returns:
        StateManager
      • findStateManagerForEmbedded

        public DNStateManager findStateManagerForEmbedded​(Object value,
                                                          DNStateManager ownerSM,
                                                          AbstractMemberMetaData mmd,
                                                          PersistableObjectType objectType)
        Description copied from interface: ExecutionContext
        Method to find StateManager for the passed embedded persistable object. Will create one if not already registered, and tie it to the specified owner.
        Specified by:
        findStateManagerForEmbedded in interface ExecutionContext
        Parameters:
        value - The embedded object
        ownerSM - The owner StateManager (if known).
        mmd - Metadata for the field of the owner
        objectType - Type of persistable object being stored
        Returns:
        StateManager for the embedded object
      • processNontransactionalUpdate

        public void processNontransactionalUpdate()
        Method called when a non-tx update has been performed (via setter call on the persistable object, or via use of mutator methods of a field). Only hands the update across to be "committed" if not part of an owning persist/delete call.
        Specified by:
        processNontransactionalUpdate in interface ExecutionContext
      • processNontransactionalAtomicChanges

        protected void processNontransactionalAtomicChanges()
        Handler for all outstanding changes to be "committed" atomically. If a transaction is active, non-tx writes are disabled, or atomic updates not enabled then will do nothing. Otherwise will flush any updates that are outstanding (updates to an object), will perform detachAllOnCommit if enabled (so user always has detached objects), update objects in any L2 cache, and migrates any objects through lifecycle changes. Is similar in content to "flush"+"preCommit"+"postCommit" Note that this handling for updates is not part of standard JDO which expects non-tx updates to migrate an object to P_NONTRANS_DIRTY rather than committing it directly. TODO If any update fails we should throw the appropriate exception for the API
      • evictObject

        public void evictObject​(Object obj)
        Internal method to evict an object from L1 cache.
        Specified by:
        evictObject in interface ExecutionContext
        Parameters:
        obj - The object
        Throws:
        NucleusException - if an error occurs evicting the object
      • evictObjects

        public void evictObjects​(Class cls,
                                 boolean subclasses)
        Method to evict all objects of the specified type (and optionally its subclasses) that are present in the L1 cache.
        Specified by:
        evictObjects in interface ExecutionContext
        Parameters:
        cls - Type of persistable object
        subclasses - Whether to include subclasses
      • evictAllObjects

        public void evictAllObjects()
        Method to evict all current objects from L1 cache.
        Specified by:
        evictAllObjects in interface ExecutionContext
      • refreshObject

        public void refreshObject​(Object obj)
        Method to do a refresh of an object, updating it from its datastore representation. Also updates the object in the L1/L2 caches.
        Specified by:
        refreshObject in interface ExecutionContext
        Parameters:
        obj - The Object
      • retrieveObjects

        public void retrieveObjects​(boolean useFetchPlan,
                                    Object... pcs)
        Method to retrieve fields for objects.
        Specified by:
        retrieveObjects in interface ExecutionContext
        Parameters:
        useFetchPlan - Whether to use the current fetch plan
        pcs - The objects to retrieve the fields for
      • persistObject

        public Object persistObject​(Object obj,
                                    boolean merging)
        Method to make an object persistent. NOT to be called by internal DataNucleus methods. Only callable by external APIs (JDO/JPA).
        Specified by:
        persistObject in interface ExecutionContext
        Parameters:
        obj - The object
        merging - Whether this object (and dependents) is being merged
        Returns:
        The persisted object
        Throws:
        NucleusUserException - if the object is managed by a different manager
      • persistObjects

        public Object[] persistObjects​(Object... objs)
        Method to persist an array of objects to the datastore.
        Specified by:
        persistObjects in interface ExecutionContext
        Parameters:
        objs - The objects to persist
        Returns:
        The persisted objects
        Throws:
        NucleusUserException - Thrown if an error occurs during the persist process. Any exception could have several nested exceptions for each failed object persist
      • persistObjectInternal

        public <T> T persistObjectInternal​(T obj,
                                           FieldValues preInsertChanges,
                                           DNStateManager ownerSM,
                                           int ownerFieldNum,
                                           PersistableObjectType objectType)
        Method to make an object persistent which should be called from internal calls only. All PM/EM calls should go via persistObject(Object obj).
        Specified by:
        persistObjectInternal in interface ExecutionContext
        Type Parameters:
        T - Type of the persistable object
        Parameters:
        obj - The object
        preInsertChanges - Any changes to make before inserting
        ownerSM - StateManager of the owner when embedded
        ownerFieldNum - Field number in the owner where this is embedded (or -1 if not embedded)
        objectType - Type of object
        Returns:
        The persisted object
        Throws:
        NucleusUserException - if the object is managed by a different manager
      • persistObjectInternal

        public <T> T persistObjectInternal​(T pc,
                                           DNStateManager ownerSM,
                                           int ownerFieldNum,
                                           PersistableObjectType objectType)
        Method to persist the passed object (internally).
        Specified by:
        persistObjectInternal in interface ExecutionContext
        Type Parameters:
        T - Type of the persistable object
        Parameters:
        pc - The object
        ownerSM - StateManager of the owner when embedded
        ownerFieldNum - Field number in the owner where this is embedded (or -1 if not embedded)
        objectType - Type of object
        Returns:
        The persisted object
      • deleteObjects

        public void deleteObjects​(Object... objs)
        Method to delete an array of objects from the datastore.
        Specified by:
        deleteObjects in interface ExecutionContext
        Parameters:
        objs - The objects
        Throws:
        NucleusUserException - Thrown if an error occurs during the deletion process. Any exception could have several nested exceptions for each failed object deletion
      • deleteObject

        public void deleteObject​(Object obj)
        Method to delete an object from the datastore. NOT to be called by internal methods. Only callable by external APIs (JDO/JPA).
        Specified by:
        deleteObject in interface ExecutionContext
        Parameters:
        obj - The object
      • deleteObjectInternal

        public void deleteObjectInternal​(Object obj)
        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).
        Specified by:
        deleteObjectInternal in interface ExecutionContext
        Parameters:
        obj - Object to delete
      • makeObjectTransient

        public void makeObjectTransient​(Object obj,
                                        FetchPlanState state)
        Method to migrate an object to transient state.
        Specified by:
        makeObjectTransient in interface ExecutionContext
        Parameters:
        obj - The object
        state - Object containing the state of the fetch plan process (if any)
        Throws:
        NucleusException - When an error occurs in making the object transient
      • attachObject

        public void attachObject​(DNStateManager ownerSM,
                                 Object pc,
                                 boolean sco)
        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.
        Specified by:
        attachObject in interface ExecutionContext
        Parameters:
        ownerSM - StateManager of the owner object that has this in a field that causes this attach
        pc - The persistable object
        sco - Whether the PC object is stored without an identity (embedded/serialised)
      • attachObjectCopy

        public <T> T attachObjectCopy​(DNStateManager ownerSM,
                                      T pc,
                                      boolean sco)
        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.
        Specified by:
        attachObjectCopy in interface ExecutionContext
        Type Parameters:
        T - Type of the persistable object
        Parameters:
        ownerSM - StateManager of the owner object that has this in a field that causes this attach
        pc - The object
        sco - Whether it has no identity (second-class object)
        Returns:
        The attached object
      • detachObject

        public void detachObject​(FetchPlanState state,
                                 Object obj)
        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 NucleusUserException is thrown.
        Specified by:
        detachObject in interface ExecutionContext
        Parameters:
        state - State for the detachment process
        obj - The object
      • detachObjectCopy

        public <T> T detachObjectCopy​(FetchPlanState state,
                                      T pc)
        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.
        Specified by:
        detachObjectCopy in interface ExecutionContext
        Type Parameters:
        T - Type of the persistable object
        Parameters:
        state - State for the detachment process
        pc - The object
        Returns:
        The detached object
      • detachAll

        public void detachAll()
        Method to detach all objects in the context. Detaches all objects enlisted as well as all objects in the L1 cache. Of particular use with JPA when doing a clear of the persistence context.
        Specified by:
        detachAll in interface ExecutionContext
      • getAttachDetachReferencedObject

        public Object getAttachDetachReferencedObject​(DNStateManager sm)
        Description copied from interface: ExecutionContext
        Access a referenced object for this StateManager during the attach/detach process. When attaching and this is the detached object this returns the newly attached object. When attaching and this is the newly attached object this returns the detached object. When detaching and this is the newly detached object this returns the attached object. When detaching and this is the attached object this returns the newly detached object.
        Specified by:
        getAttachDetachReferencedObject in interface ExecutionContext
        Parameters:
        sm - StateManager
        Returns:
        The referenced object (if any)
      • setAttachDetachReferencedObject

        public void setAttachDetachReferencedObject​(DNStateManager sm,
                                                    Object obj)
        Description copied from interface: ExecutionContext
        Register a referenced object against this StateManager for the attach/detach process.
        Specified by:
        setAttachDetachReferencedObject in interface ExecutionContext
        Parameters:
        sm - StateManager
        obj - The referenced object (or null to clear out any reference)
      • newInstance

        public <T> T newInstance​(Class<T> cls)
        Method to generate an instance of an interface, abstract class, or concrete PC class.
        Specified by:
        newInstance in interface ExecutionContext
        Type Parameters:
        T - Type of the persistable object
        Parameters:
        cls - The class of the interface or abstract class, or concrete class defined in MetaData
        Returns:
        The instance of this type
        Throws:
        NucleusUserException - if an ImplementationCreator instance does not exist and one is needed (i.e not a concrete class passed in)
      • exists

        public boolean exists​(Object obj)
        Method to return if the specified object exists in the datastore.
        Specified by:
        exists in interface ExecutionContext
        Parameters:
        obj - The (persistable) object
        Returns:
        Whether it exists
      • getManagedObjects

        public Set getManagedObjects()
        Accessor for the currently managed objects for the current transaction. If the transaction is not active this returns null.
        Specified by:
        getManagedObjects in interface ExecutionContext
        Returns:
        Collection of managed objects enlisted in the current transaction
      • getManagedObjects

        public Set getManagedObjects​(Class[] classes)
        Accessor for the currently managed objects for the current transaction. If the transaction is not active this returns null.
        Specified by:
        getManagedObjects in interface ExecutionContext
        Parameters:
        classes - Classes that we want the enlisted objects for
        Returns:
        Collection of managed objects enlisted in the current transaction
      • getManagedObjects

        public Set getManagedObjects​(String[] states)
        Accessor for the currently managed objects for the current transaction. If the transaction is not active this returns null.
        Specified by:
        getManagedObjects in interface ExecutionContext
        Parameters:
        states - States that we want the enlisted objects for
        Returns:
        Collection of managed objects enlisted in the current transaction
      • getManagedObjects

        public Set getManagedObjects​(String[] states,
                                     Class[] classes)
        Accessor for the currently managed objects for the current transaction. If the transaction is not active this returns null.
        Specified by:
        getManagedObjects in interface ExecutionContext
        Parameters:
        states - States that we want the enlisted objects for
        classes - Classes that we want the enlisted objects for
        Returns:
        Collection of managed objects enlisted in the current transaction
      • findObject

        public <T> T findObject​(Class<T> cls,
                                Object key)
        Accessor for an object of the specified type with the provided id "key". With datastore id or single-field id the "key" is the key of the id, and with composite ids the "key" is the toString() of the id.
        Specified by:
        findObject in interface ExecutionContext
        Type Parameters:
        T - Type of the persistable
        Parameters:
        cls - Class of the persistable
        key - Value of the key field for SingleFieldIdentity, or the string value of the key otherwise
        Returns:
        The object for this id.
      • findObjects

        public <T> List<T> findObjects​(Class<T> cls,
                                       List keys)
        Description copied from interface: ExecutionContext
        Accessor for objects of the specified type, with the provided id "key"s. With datastore id or single-field id the "key" is the key of the id, and with composite ids the "key" is the toString() of the id.
        Specified by:
        findObjects in interface ExecutionContext
        Type Parameters:
        T - Type of the persistable
        Parameters:
        cls - Class of the persistable
        keys - Values of the key field for SingleFieldIdentity, or the string value of the keys otherwise
        Returns:
        The objects meeting this requirement
      • findObjectByUnique

        public <T> T findObjectByUnique​(Class<T> cls,
                                        String[] memberNames,
                                        Object[] memberValues)
        Description copied from interface: ExecutionContext
        Accessor for an object of the specified type with the provided values for a unique key. Alternative would be to have an intermediate class and do this
         ec.findObjectByUnique(cls).for("field1", val1).for("field2", val2).find();
         
        Specified by:
        findObjectByUnique in interface ExecutionContext
        Type Parameters:
        T - Type of the persistable
        Parameters:
        cls - Class of the persistable
        memberNames - Name(s) of the field(s) forming the unique key
        memberValues - Value(s) of the field(s) forming the unique key
        Returns:
        The object meeting this requirement
      • findObject

        public Persistable findObject​(Object id,
                                      boolean validate)
        Description copied from interface: ExecutionContext
        Shortcut to calling "findObject(id, validate, validate, null)". Note: This is used by the bytecode enhancement contract in
        dnCopyKeyFieldsFromObjectId
        Specified by:
        findObject in interface ExecutionContext
        Specified by:
        findObject in interface ExecutionContextReference
        Parameters:
        id - The id of the object
        validate - Whether to validate the id
        Returns:
        The object
      • findObject

        public Persistable findObject​(Object id,
                                      FieldValues fv,
                                      Class cls,
                                      boolean ignoreCache,
                                      boolean checkInheritance)
        Accessor for an object given the object id and a set of field values to apply to it. This is intended for use where we have done a query and have the id from the results, and we want to create the object, preferably using the cache, and then apply any field values to it.
        Specified by:
        findObject in interface ExecutionContext
        Parameters:
        id - Id of the object.
        fv - Field values for the object (to copy in)
        cls - the type which the object is (optional). Used to instantiate the object
        ignoreCache - true if it must ignore the cache
        checkInheritance - Whether to check the inheritance on the id of the object
        Returns:
        The Object
      • findObjectsById

        public Persistable[] findObjectsById​(Object[] identities,
                                             boolean validate)
        Accessor for objects with the specified identities.
        Specified by:
        findObjectsById in interface ExecutionContext
        Parameters:
        identities - Ids of the object(s).
        validate - Whether to validate the object state
        Returns:
        The Objects with these ids (same order)
        Throws:
        NucleusObjectNotFoundException - if an object doesn't exist in the datastore
      • findObject

        public Persistable findObject​(Object id,
                                      boolean validate,
                                      boolean checkInheritance,
                                      String objectClassName)
        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. TODO Would be nice, when using checkInheritance, to be able to specify the "id" is an instance of class X or subclass. See IdentityUtils where we have the min class
        Specified by:
        findObject in interface ExecutionContext
        Parameters:
        id - Id of the object.
        validate - Whether to validate the object state
        checkInheritance - Whether look to the database to determine which class this object is.
        objectClassName - Class name for the object with this id (if known, optional)
        Returns:
        The Object with this id
        Throws:
        NucleusObjectNotFoundException - if the object doesn't exist in the datastore
      • newObjectId

        public Object newObjectId​(Class pcClass,
                                  Object key)
        This method returns an object id instance corresponding to the pcClass and key arguments. Operates in 2 modes :-
        • The class uses SingleFieldIdentity and the key is the value of the key field
        • In all other cases the key is the String form of the object id instance
        Specified by:
        newObjectId in interface ExecutionContext
        Parameters:
        pcClass - Class of the persistable object to create the identity for
        key - Value of the key for SingleFieldIdentity (or the toString value)
        Returns:
        The new object-id instance
      • newObjectId

        public Object newObjectId​(String className,
                                  Object pc)
        This method returns an object id instance corresponding to the class name, and the passed object (when using app identity).
        Specified by:
        newObjectId in interface ExecutionContext
        Parameters:
        className - Name of the class of the object.
        pc - The persistable object. Used for application-identity
        Returns:
        A new object ID.
      • clearDirty

        public void clearDirty​(DNStateManager sm)
        Method to clear an object from the list of dirty objects.
        Specified by:
        clearDirty in interface ExecutionContext
        Parameters:
        sm - StateManager
      • clearDirty

        public void clearDirty()
        Method to clear all objects marked as dirty (whether directly or indirectly).
        Specified by:
        clearDirty in interface ExecutionContext
      • markDirty

        public void markDirty​(DNStateManager sm,
                              boolean directUpdate)
        Method to mark an object (StateManager) as dirty.
        Specified by:
        markDirty in interface ExecutionContext
        Parameters:
        sm - StateManager
        directUpdate - Whether the object has had a direct update made on it (if known)
      • getManageRelations

        public boolean getManageRelations()
        Accessor for whether to manage relationships at flush/commit.
        Specified by:
        getManageRelations in interface ExecutionContext
        Returns:
        Whether to manage relationships at flush/commit.
      • getRelationshipManager

        public RelationshipManager getRelationshipManager​(DNStateManager sm)
        Method to return the RelationshipManager for StateManager. If we are currently managing relations and StateManager has no RelationshipManager allocated then one is created.
        Specified by:
        getRelationshipManager in interface ExecutionContext
        Parameters:
        sm - StateManager
        Returns:
        The RelationshipManager
      • isManagingRelations

        public boolean isManagingRelations()
        Returns whether this context is currently performing the manage relationships task.
        Specified by:
        isManagingRelations in interface ExecutionContext
        Returns:
        Whether in the process of managing relations
      • getObjectsToBeFlushed

        public List<DNStateManager> getObjectsToBeFlushed()
        Convenience method to inspect the list of objects with outstanding changes to flush.
        Specified by:
        getObjectsToBeFlushed in interface ExecutionContext
        Returns:
        StateManagers for the objects to be flushed.
      • isFlushing

        public boolean isFlushing()
        Returns whether the context is in the process of flushing.
        Specified by:
        isFlushing in interface ExecutionContext
        Returns:
        true if the context is flushing
      • flush

        public void flush()
        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.
        Specified by:
        flush in interface ExecutionContext
      • flushInternal

        public void flushInternal​(boolean flushToDatastore)
        This method flushes all dirty, new, and deleted instances to the datastore.
        Specified by:
        flushInternal in interface ExecutionContext
        Parameters:
        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:
        NucleusOptimisticException - when optimistic locking error(s) occur
      • getOperationQueue

        public OperationQueue getOperationQueue()
        Description copied from interface: ExecutionContext
        Accessor for the operation queue. The queue can be null if there are no operations queued (txn not active, not optimistic, no ops arrived yet).
        Specified by:
        getOperationQueue in interface ExecutionContext
        Returns:
        The operation queue (typically for collections/maps)
      • operationQueueIsActive

        public boolean operationQueueIsActive()
        Description copied from interface: ExecutionContext
        Accessor for whether the operation queue is currently active. Will return false if not delaying flush, or not in a transaction, or flushing.
        Specified by:
        operationQueueIsActive in interface ExecutionContext
        Returns:
        Whether the operation queue is active for adding operations
      • postBegin

        public void postBegin()
        Method to perform any post-begin checks.
      • preCommit

        public void preCommit()
        Method to perform any pre-commit checks.
      • isObjectModifiedInTransaction

        public boolean isObjectModifiedInTransaction​(Object id)
        Accessor for whether the object with this identity is modified in the current transaction. Only returns true when using the L2 cache and the object has been modified during the txn.
        Specified by:
        isObjectModifiedInTransaction in interface ExecutionContext
        Parameters:
        id - The identity
        Returns:
        Whether it is modified/new/deleted in this transaction
      • markFieldsForUpdateInLevel2Cache

        public void markFieldsForUpdateInLevel2Cache​(Object id,
                                                     boolean[] fields)
        Description copied from interface: ExecutionContext
        Method to mark the object with specifed id to have the supplied fields updated in the L2 cache at commit.
        Specified by:
        markFieldsForUpdateInLevel2Cache in interface ExecutionContext
        Parameters:
        id - Id of the object
        fields - The fields to update
      • isRunningDetachAllOnCommit

        public boolean isRunningDetachAllOnCommit()
        Accessor for whether this context is currently running detachAllOnCommit.
        Specified by:
        isRunningDetachAllOnCommit in interface ExecutionContext
        Returns:
        Whether running detachAllOnCommit
      • postCommit

        public void postCommit()
        Commit any changes made to objects managed by the object manager to the database.
      • preRollback

        public void preRollback()
        Rollback any changes made to objects managed by the object manager to the database.
      • postRollback

        public void postRollback()
        Callback invoked after the actual datastore rollback.
      • getLevel2CacheRetrieveMode

        protected String getLevel2CacheRetrieveMode()
      • getLevel2CacheStoreMode

        protected String getLevel2CacheStoreMode()
      • putObjectIntoLevel2Cache

        protected void putObjectIntoLevel2Cache​(DNStateManager sm,
                                                boolean updateIfPresent)
        Method to add/update the managed object into the L2 cache as long as it isn't modified in the current transaction.
        Parameters:
        sm - StateManager for the object
        updateIfPresent - Whether to update it in the L2 cache if already present
      • getL2CacheableObject

        protected CachedPC getL2CacheableObject​(DNStateManager sm,
                                                CachedPC currentCachedPC)
        Convenience method to convert the object managed by StateManager into a form suitable for caching in an L2 cache.
        Parameters:
        sm - StateManager for the object
        currentCachedPC - Current L2 cached object (if any) to use for updating
        Returns:
        The cacheable form of the object
      • putObjectsIntoLevel2Cache

        protected void putObjectsIntoLevel2Cache​(Set<DNStateManager> sms)
        Method to put the passed objects into the L2 cache. Performs the "put" in batches
        Parameters:
        sms - StateManagers whose objects are to be cached
      • putObjectIntoLevel2CacheInternal

        protected void putObjectIntoLevel2CacheInternal​(DNStateManager sm,
                                                        boolean updateIfPresent)
        Convenience method to add/update an object in the L2 cache.
        Parameters:
        sm - StateManager of the object to add.
        updateIfPresent - Whether to update the L2 cache if it is present
      • removeObjectFromLevel1Cache

        public void removeObjectFromLevel1Cache​(Object id)
        Convenience method to evict an object from the L1 cache.
        Specified by:
        removeObjectFromLevel1Cache in interface ExecutionContext
        Parameters:
        id - The Persistable object id
      • removeObjectFromLevel2Cache

        public void removeObjectFromLevel2Cache​(Object id)
        Convenience method to remove the object with the specified identity from the L2 cache.
        Specified by:
        removeObjectFromLevel2Cache in interface ExecutionContext
        Parameters:
        id - Identity of the object
      • hasIdentityInCache

        public boolean hasIdentityInCache​(Object id)
        Whether the specified identity is cached currently. Looks in L1 cache and L2 cache.
        Specified by:
        hasIdentityInCache in interface ExecutionContext
        Parameters:
        id - The identity
        Returns:
        Whether an object exists in the cache(s) with this identity
      • getObjectFromCache

        public Persistable getObjectFromCache​(Object id)
        Convenience method to access an object in the cache. Firstly looks in the L1 cache for this context, and if not found looks in the L2 cache.
        Specified by:
        getObjectFromCache in interface ExecutionContext
        Parameters:
        id - Id of the object
        Returns:
        Persistable object (with connected StateManager).
      • getObjectsFromCache

        public Persistable[] getObjectsFromCache​(Object[] ids)
        Convenience method to access objects in the cache. Firstly looks in the L1 cache for this context, and if not found looks in the L2 cache.
        Specified by:
        getObjectsFromCache in interface ExecutionContext
        Parameters:
        ids - Ids of the objects
        Returns:
        Persistable objects (with connected StateManagers), or null.
      • getObjectFromLevel1Cache

        protected Persistable getObjectFromLevel1Cache​(Object id)
        Convenience method to access an object in the Level 1 cache.
        Parameters:
        id - Id of the object
        Returns:
        Persistable object (with connected StateManager).
      • getObjectFromLevel2Cache

        protected Persistable getObjectFromLevel2Cache​(Object id)
        Convenience method to access an object in the Level 2 cache.
        Parameters:
        id - Id of the object
        Returns:
        Persistable object (with connected StateManager).
      • getObjectFromLevel2CacheForUnique

        protected Persistable getObjectFromLevel2CacheForUnique​(CacheUniqueKey uniKey)
        Convenience method to access the identity that corresponds to a unique key, in the Level 2 cache.
        Parameters:
        uniKey - The CacheUniqueKey to use in lookups
        Returns:
        Identity of the associated object
      • getObjectsFromLevel2Cache

        protected Map<Object,​Persistable> getObjectsFromLevel2Cache​(Collection ids)
        Convenience method to access a collection of objects from the Level 2 cache.
        Parameters:
        ids - Collection of ids to retrieve
        Returns:
        Map of persistable objects (with connected StateManager) keyed by their id if found in the L2 cache
      • replaceObjectId

        public void replaceObjectId​(Persistable pc,
                                    Object oldID,
                                    Object newID)
        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).
        Specified by:
        replaceObjectId in interface ExecutionContext
        Parameters:
        pc - The Persistable object
        oldID - the old id it was known by
        newID - the new id
      • getSerializeReadForClass

        public boolean getSerializeReadForClass​(String className)
        Convenience method to return the setting for serialize read for the current transaction for the specified class name. Returns the setting for the transaction (if set), otherwise falls back to the setting for the class, otherwise returns false.
        Specified by:
        getSerializeReadForClass in interface ExecutionContext
        Parameters:
        className - Name of the class
        Returns:
        Setting for serialize read
      • getExtent

        public <T> Extent<T> getExtent​(Class<T> pcClass,
                                       boolean subclasses)
        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.
        Specified by:
        getExtent in interface ExecutionContext
        Type Parameters:
        T - Type of the persistable object
        Parameters:
        pcClass - The class to query
        subclasses - Whether to include subclasses in the query.
        Returns:
        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.
      • getCallbackHandler

        public CallbackHandler getCallbackHandler()
        Retrieve the callback handler for this context. If the callback handler hasn't yet been created, this will create it.
        Specified by:
        getCallbackHandler in interface ExecutionContext
        Returns:
        the callback handler
      • closeCallbackHandler

        public void closeCallbackHandler()
        Close the callback handler and disconnect any registered listeners.
        Specified by:
        closeCallbackHandler in interface ExecutionContext
      • assertIsOpen

        protected void assertIsOpen()
        Method to assert if this context is open. Throws a NucleusUserException if the context is closed.
      • assertDetachable

        protected void assertDetachable​(Object object)
        Method to assert if the specified object is Detachable. Throws a ClassNotDetachableException if not capable
        Parameters:
        object - The object to check
      • assertNotDetached

        protected void assertNotDetached​(Object object)
        Method to assert if the specified object is detached. Throws a ObjectDetachedException if it is detached.
        Parameters:
        object - The object to check
      • assertActiveTransaction

        protected void assertActiveTransaction()
        Method to assert if the current transaction is active. Throws a TransactionNotActiveException if not active
      • hasPersistenceInformationForClass

        public boolean hasPersistenceInformationForClass​(Class cls)
        Utility method to check if the specified class has reachable metadata or annotations.
        Specified by:
        hasPersistenceInformationForClass in interface ExecutionContext
        Parameters:
        cls - The class to check
        Returns:
        Whether the class has reachable metadata or annotations
      • getFetchGroupManager

        protected FetchGroupManager getFetchGroupManager()
        Convenience accessor for the FetchGroupManager. Creates it if not yet existing.
        Returns:
        The FetchGroupManager
      • removeInternalFetchGroup

        protected void removeInternalFetchGroup​(FetchGroup grp)
        Method to remove a dynamic FetchGroup.
        Parameters:
        grp - The group
      • removeEmbeddedOwnerRelation

        public void removeEmbeddedOwnerRelation​(DNStateManager ownerSM,
                                                int ownerFieldNum,
                                                DNStateManager embSM)
        Description copied from interface: ExecutionContext
        Convenience method to remove the EmbeddedOwnerRelation between the specified StateManagers.
        Specified by:
        removeEmbeddedOwnerRelation in interface ExecutionContext
        Parameters:
        ownerSM - Owner StateManager
        ownerFieldNum - Field in owner
        embSM - Embedded StateManager