Interface ObjectProvider<T>

  • Type Parameters:
    T - Type of the object being managed
    All Superinterfaces:
    StateManager
    All Known Implementing Classes:
    ReferentialStateManagerImpl, StateManagerImpl

    public interface ObjectProvider<T>
    extends StateManager
    Provider of field information for a managed object. A JDO StateManager is one possible implementation of an ObjectProvider, using bytecode enhancement in that case. Another possible implementation would use Java reflection to obtain and set field values in the object. TODO Drop the generics and use Persistable. This will require updates to ExecutionContext to match
    • Field Detail

      • ORIGINAL_FIELD_VALUE_KEY_PREFIX

        static final String ORIGINAL_FIELD_VALUE_KEY_PREFIX
        Key prefix under which the original value of a field is stored in the entity (nondurable objects). This value is set if a field is updated using a setter.
        See Also:
        Constant Field Values
      • EMBEDDED_PC

        static final short EMBEDDED_PC
        Embedded (or serialised) PC
        See Also:
        Constant Field Values
      • EMBEDDED_COLLECTION_ELEMENT_PC

        static final short EMBEDDED_COLLECTION_ELEMENT_PC
        Embedded (or serialised) Collection Element PC
        See Also:
        Constant Field Values
      • EMBEDDED_MAP_KEY_PC

        static final short EMBEDDED_MAP_KEY_PC
        Embedded (or serialised) Map Key PC
        See Also:
        Constant Field Values
      • EMBEDDED_MAP_VALUE_PC

        static final short EMBEDDED_MAP_VALUE_PC
        Embedded (or serialised) Map Value PC
        See Also:
        Constant Field Values
    • Method Detail

      • connect

        void connect​(ExecutionContext ec,
                     AbstractClassMetaData cmd)
        Method to (re)connect this provider to the specified ExecutionContext and object type.
        Parameters:
        ec - ExecutionContext to connect to
        cmd - Metadata for this class
      • disconnect

        void disconnect()
        Disconnect this provider from the ExecutionContext and PC object.
      • initialiseForHollow

        void initialiseForHollow​(Object id,
                                 FieldValues fv,
                                 Class<T> pcClass)
        Initialises a state manager to manage a hollow instance having the given object ID and the given (optional) field values. This constructor is used for creating new instances of existing persistent objects, and consequently shouldnt be used when the StoreManager controls the creation of such objects (such as in an ODBMS).
        Parameters:
        id - the JDO identity of the object.
        fv - the initial field values of the object (optional)
        pcClass - Class of the object that this will manage the state for
      • initialiseForHollowAppId

        void initialiseForHollowAppId​(FieldValues fv,
                                      Class<T> pcClass)
        Deprecated.
        Remove use of this and use initialiseForHollow
        Initialises a state manager to manage a HOLLOW / P_CLEAN instance having the given FieldValues. This constructor is used for creating new instances of existing persistent objects using application identity, and consequently shouldnt be used when the StoreManager controls the creation of such objects (such as in an ODBMS).
        Parameters:
        fv - the initial field values of the object.
        pcClass - Class of the object that this will manage the state for
      • initialiseForPersistentClean

        void initialiseForPersistentClean​(Object id,
                                          T pc)
        Initialises a state manager to manage the passed persistent instance having the given object ID. Used where we have retrieved a PC object from a datastore directly (not field-by-field), for example on an object datastore. This initialiser will not add ObjectProviders to all related PCs. This must be done by any calling process. This simply adds the ObjectProvider to the specified object and records the id, setting all fields of the object as loaded.
        Parameters:
        id - the identity of the object.
        pc - The object to be managed
      • initialiseForEmbedded

        void initialiseForEmbedded​(T pc,
                                   boolean copyPc)
        Initialises a state manager to manage a persistable instance that will be EMBEDDED/SERIALISED into another persistable object. The instance will not be assigned an identity in the process since it is a SCO.
        Parameters:
        pc - The persistable to manage (see copyPc also)
        copyPc - Whether the ObjectProvider should manage a copy of the passed PC or that one
      • initialiseForPersistentNew

        void initialiseForPersistentNew​(T pc,
                                        FieldValues preInsertChanges)
        Initialises a state manager to manage a transient instance that is becoming newly persistent. A new object ID for the instance is obtained from the store manager and the object is inserted in the data store.

        This constructor is used for assigning state managers to existing instances that are transitioning to a persistent state.

        Parameters:
        pc - the instance being make persistent.
        preInsertChanges - Any changes to make before inserting
      • initialiseForTransactionalTransient

        void initialiseForTransactionalTransient​(T pc)
        Initialises a state manager to manage a Transactional Transient instance. A new object ID for the instance is obtained from the store manager and the object is inserted in the data store.

        This constructor is used for assigning state managers to Transient instances that are transitioning to a transient clean state.

        Parameters:
        pc - the instance being make persistent.
      • initialiseForDetached

        void initialiseForDetached​(T pc,
                                   Object id,
                                   Object version)
        Initialises the ObjectProvider to manage a persistable object in detached state.
        Parameters:
        pc - the detach object.
        id - the identity of the object.
        version - the detached version
      • initialiseForPNewToBeDeleted

        void initialiseForPNewToBeDeleted​(T pc)
        Initialises the ObjectProvider to manage a persistable object that is not persistent but is about to be deleted.
        Parameters:
        pc - the object to delete
      • initialiseForCachedPC

        void initialiseForCachedPC​(CachedPC cachedPC,
                                   Object id)
        Initialise the ObjectProvider, assigning the specified id to the object. This is used when getting objects out of the L2 Cache, where they have no ObjectProvider assigned, and returning them as associated with a particular ExecutionContext.
        Parameters:
        cachedPC - The cached PC object
        id - Id to assign to the persistable object
      • getClassMetaData

        AbstractClassMetaData getClassMetaData()
        Accessor for the ClassMetaData for this object.
        Returns:
        The ClassMetaData.
      • getObject

        T getObject()
        Accessor for the persistable object managed by this StateManager.
        Returns:
        the persistable object
      • getObjectAsPrintable

        String getObjectAsPrintable()
        Returns a printable form of the managed object.
        Returns:
        The object reference for the persistable object.
      • getInternalObjectId

        Object getInternalObjectId()
        Accessor for the id of the object managed by this ObjectProvider.
        Returns:
        The identity of the object
      • getExternalObjectId

        Object getExternalObjectId()
      • getLifecycleState

        LifeCycleState getLifecycleState()
        Accessor for the LifeCycleState
        Returns:
        the LifeCycleState
      • replaceField

        void replaceField​(int fieldNumber,
                          Object value)
        Method to change the value of the specified field. This will not make the field dirty
        Parameters:
        fieldNumber - (absolute) field number of the field
        value - The new value.
      • replaceFieldMakeDirty

        void replaceFieldMakeDirty​(int fieldNumber,
                                   Object value)
        Method to change the value of the specified field. This will make the field dirty.
        Parameters:
        fieldNumber - (absolute) field number of the field
        value - The new value.
      • replaceFieldValue

        void replaceFieldValue​(int fieldNumber,
                               Object newValue)
        Convenience method to change the value of a field that is assumed loaded. Will mark the object/field as dirty if it isnt previously. Only for use in management of relations.
        Parameters:
        fieldNumber - Number of field
        newValue - The new value
      • replaceFields

        void replaceFields​(int[] fieldNumbers,
                           FieldManager fm)
        Method to update the data in the object with the values from the passed FieldManager
        Parameters:
        fieldNumbers - (absolute) field numbers of the fields to update
        fm - The FieldManager
      • replaceFields

        void replaceFields​(int[] fieldNumbers,
                           FieldManager fm,
                           boolean replaceWhenDirty)
        Method to update the data in the object with the values from the passed FieldManager
        Parameters:
        fieldNumbers - (absolute) field numbers of the fields to update
        fm - The FieldManager
        replaceWhenDirty - Whether to replace these fields if the field is dirty
      • replaceNonLoadedFields

        void replaceNonLoadedFields​(int[] fieldNumbers,
                                    FieldManager fm)
        Method to update the data in the object with the values from the passed FieldManager. Only non loaded fields are updated
        Parameters:
        fieldNumbers - (absolute) field numbers of the fields to update
        fm - The FieldManager
      • replaceAllLoadedSCOFieldsWithWrappers

        void replaceAllLoadedSCOFieldsWithWrappers()
        Method to replace all loaded SCO fields with wrappers. If the loaded field already uses a SCO wrapper nothing happens to that field.
      • replaceAllLoadedSCOFieldsWithValues

        void replaceAllLoadedSCOFieldsWithValues()
        Method to replace all loaded (wrapped) SCO fields with unwrapped values. If the loaded field doesnt use a SCO wrapper nothing happens to that field.
      • provideFields

        void provideFields​(int[] fieldNumbers,
                           FieldManager fm)
        Method to obtain updated field values from the passed FieldManager.
        Parameters:
        fieldNumbers - The numbers of the fields
        fm - The fieldManager
      • provideField

        Object provideField​(int fieldNumber)
        Method to return the current value of the specified field.
        Parameters:
        fieldNumber - (absolute) field number of the field
        Returns:
        The current value
      • setAssociatedValue

        void setAssociatedValue​(Object key,
                                Object value)
        Method to set an associated value stored with this object. This is for a situation such as in ORM where this object can have an "external" foreign-key provided by an owning object (e.g 1-N uni relation and this is the element with no knowledge of the owner, so the associated value is the FK value).
        Parameters:
        key - Key for the value
        value - The associated value
      • getAssociatedValue

        Object getAssociatedValue​(Object key)
        Accessor for the value of an external field. This is for a situation such as in ORM where this object can have an "external" foreign-key provided by an owning object (e.g 1-N uni relation and this is the element with no knowledge of the owner, so the associated value is the FK value).
        Parameters:
        key - The key for this associated information
        Returns:
        The value stored (if any) against this key
      • removeAssociatedValue

        void removeAssociatedValue​(Object key)
        Method to remove the associated value with the specified key (if it exists).
        Parameters:
        key - The key
      • getDirtyFieldNumbers

        int[] getDirtyFieldNumbers()
        Accessor for the field numbers of all dirty fields.
        Returns:
        Absolute field numbers of the dirty fields in this instance.
      • getDirtyFieldNames

        String[] getDirtyFieldNames()
        Accessor for the names of the fields that are dirty.
        Returns:
        Names of the dirty fields
      • getDirtyFields

        boolean[] getDirtyFields()
        Creates a copy of the internal dirtyFields array.
        Returns:
        a copy of the internal dirtyFields array.
      • makeDirty

        void makeDirty​(int field)
        Marks the given field dirty.
        Parameters:
        field - The no of field to mark as dirty.
      • isEmbedded

        boolean isEmbedded()
        Convenience accessor for whether this ObjectProvider manages an embedded/serialised object.
        Returns:
        Whether the managed object is embedded/serialised.
      • updateOwnerFieldInEmbeddedField

        void updateOwnerFieldInEmbeddedField​(int fieldNumber,
                                             Object value)
        Method to update the owner field in an embedded field.
        Parameters:
        fieldNumber - The field of this object that is embedded
        value - The value of the field (embedded)
      • setPcObjectType

        void setPcObjectType​(short type)
        Method to set this ObjectProvider as managing an embedded/serialised object.
        Parameters:
        type - The type of object being managed
      • setStoringPC

        void setStoringPC()
        Method to set the storing PC flag.
      • unsetStoringPC

        void unsetStoringPC()
        Method to unset the storing PC flag.
      • isFlushedToDatastore

        boolean isFlushedToDatastore()
        Accessor for whether all changes have been written to the datastore.
        Returns:
        Whether the datastore has all changes
      • isFlushedNew

        boolean isFlushedNew()
        Whether this record has been flushed to the datastore in this transaction (i.e called persist() and is in the datastore now). If user has called persist() on it yet not yet persisted then returns false.
        Returns:
        Whether this is flushed new.
      • setFlushedNew

        void setFlushedNew​(boolean flag)
      • flush

        void flush()
        Method to flush all changes to the datastore.
      • setFlushing

        void setFlushing​(boolean flushing)
      • markAsFlushed

        void markAsFlushed()
        Method to notify the object provider that the object has now been flushed to the datastore. This is performed when handling inserts or deletes in a batch external to the ObjectProvider.
      • isWaitingToBeFlushedToDatastore

        boolean isWaitingToBeFlushedToDatastore()
        Tests whether this object is new yet waiting to be flushed to the datastore.
        Returns:
        true if this instance is waiting to be flushed
      • changeActivityState

        void changeActivityState​(ActivityState state)
        Update the acitvity state.
        Parameters:
        state - the activity state
      • isInserting

        boolean isInserting()
        Tests whether this object is being inserted.
        Returns:
        true if this instance is inserting.
      • isDeleting

        boolean isDeleting()
        Tests whether this object is in the process of being deleted.
        Returns:
        true if this instance is being deleted.
      • becomingDeleted

        boolean becomingDeleted()
        Whether this object is moving to a deleted state.
        Returns:
        Whether the object will be moved into a deleted state during this operation
      • isDeleted

        boolean isDeleted()
        Tests whether this object has been deleted. Instances that have been deleted in the current transaction return true. Transient instances return false.
        Returns:
        true if this instance was deleted in the current transaction.
      • isDetaching

        boolean isDetaching()
        Tests whether this object is in the process of being detached.
        Returns:
        true if this instance is being detached.
      • loadFieldValues

        void loadFieldValues​(FieldValues fv)
        Convenience method to load the passed field values. Loads the fields using any required fetch plan and calls jdoPostLoad() as appropriate.
        Parameters:
        fv - Field Values to load (including any fetch plan to use when loading)
      • getReferencedPC

        T getReferencedPC()
        Accessor for the referenced PC object when we are attaching or detaching. 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.
        Returns:
        The referenced object (or null).
      • loadField

        void loadField​(int fieldNumber)
        Convenience method to load the specified field if not loaded.
        Parameters:
        fieldNumber - Absolute field number
      • loadFieldsInFetchPlan

        void loadFieldsInFetchPlan​(FetchPlanState state)
        Method to load all unloaded fields in the FetchPlan. Recurses through the FetchPlan objects and loads fields of sub-objects where needed.
        Parameters:
        state - The FetchPlan state
      • loadFieldFromDatastore

        void loadFieldFromDatastore​(int fieldNumber)
        Convenience method to load a field from the datastore. Used in attaching fields and checking their old values (so we don't want any postLoad method being called). TODO Merge this with one of the loadXXXFields methods.
        Parameters:
        fieldNumber - The field number.
      • loadUnloadedFieldsInFetchPlan

        void loadUnloadedFieldsInFetchPlan()
        Loads (from the database) all unloaded fields that are in the current FetchPlan.
      • loadUnloadedFieldsOfClassInFetchPlan

        void loadUnloadedFieldsOfClassInFetchPlan​(FetchPlan fetchPlan)
        Loads (from the database) all unloaded fields of the managed class that are in the specified FetchPlan.
        Parameters:
        fetchPlan - The FetchPlan
      • loadUnloadedRelationFields

        void loadUnloadedRelationFields()
        Loads (from the database) all unloaded fields that store relations.
      • loadUnloadedFields

        void loadUnloadedFields()
        Fetch from the database all fields that are not currently loaded regardless of whether they are in the current fetch group or not. Called by lifecycle transitions.
      • unloadNonFetchPlanFields

        void unloadNonFetchPlanFields()
        Method that will unload all fields that are not in the FetchPlan.
      • refreshLoadedFields

        void refreshLoadedFields()
        Refreshes from the database all fields currently loaded. Called by life-cycle transitions.
      • clearSavedFields

        void clearSavedFields()
        Method to clear all saved fields on the object.
      • refreshFieldsInFetchPlan

        void refreshFieldsInFetchPlan()
        Refreshes from the database all fields in fetch plan. Called by life-cycle transitions.
      • clearNonPrimaryKeyFields

        void clearNonPrimaryKeyFields()
        Method to clear all fields that are not part of the primary key of the object.
      • restoreFields

        void restoreFields()
        Method to restore all fields of the object.
      • saveFields

        void saveFields()
        Method to save all fields of the object.
      • clearFields

        void clearFields()
        Method to clear all fields of the object.
      • registerTransactional

        void registerTransactional()
        Registers the pc class in the cache
      • isRestoreValues

        boolean isRestoreValues()
        Accessor for the Restore Values flag
        Returns:
        Whether to restore values
      • clearLoadedFlags

        void clearLoadedFlags()
        Method to clear all loaded flags on the object.
      • unloadField

        void unloadField​(String fieldName)
        Mark the specified field as not loaded so that it will be reloaded on next access.
        Parameters:
        fieldName - Name of the field
      • getLoadedFields

        boolean[] getLoadedFields()
      • getLoadedFieldNumbers

        int[] getLoadedFieldNumbers()
        Accessor for the field numbers of all loaded fields.
        Returns:
        Absolute field numbers of the loaded fields in this instance.
      • getLoadedFieldNames

        String[] getLoadedFieldNames()
        Accessor for the names of the fields that are loaded.
        Returns:
        Names of the loaded fields
      • isLoaded

        boolean isLoaded​(int absoluteFieldNumber)
      • getAllFieldsLoaded

        boolean getAllFieldsLoaded()
        Returns whether all fields are loaded.
        Returns:
        Returns true if all fields are loaded.
      • isFieldLoaded

        boolean isFieldLoaded​(int fieldNumber)
        Accessor for whether a field is currently loaded. Just returns the status, unlike "isLoaded" which also loads it if not.
        Parameters:
        fieldNumber - The (absolute) field number
        Returns:
        Whether it is loaded
      • updateFieldAfterInsert

        void updateFieldAfterInsert​(Object pc,
                                    int fieldNumber)
        Marks the given field dirty for issuing an update after the insert.
        Parameters:
        pc - The Persistable object
        fieldNumber - The no of field to mark as dirty.
      • setPostStoreNewObjectId

        void setPostStoreNewObjectId​(Object id)
        Method to allow the setting of the id of the PC object. This is used when it is obtained after persisting the object to the datastore. In the case of RDBMS, this may be via auto-increment, or in the case of ODBMS this may be an accessor for the id after storing.
        Parameters:
        id - the id received from the datastore. May be an OID, or the key value for an OID, or an application id.
      • replaceManagedPC

        void replaceManagedPC​(T pc)
        Method to swap the managed object for the supplied object. This is of particular use for object datastores where the datastore is responsible for creating the in-memory object and where we have a temporary object that we want to swap for the datastore generated object. Makes no change to what fields are loaded/dirty etc, just swaps the managed object.
        Parameters:
        pc - The persistable object to use
      • setTransactionalVersion

        void setTransactionalVersion​(Object nextVersion)
        Sets the value for the version column in a transaction not yet committed
        Parameters:
        nextVersion - version to use
      • getTransactionalVersion

        Object getTransactionalVersion()
        Return the object representing the transactional version of the managed object.
        Returns:
        the object representing the version of the calling instance
      • setVersion

        void setVersion​(Object version)
        Method to set the current version of the managed object.
        Parameters:
        version - The version
      • getVersion

        Object getVersion()
        Method to return the current version of the managed object.
        Returns:
        The version
      • isVersionLoaded

        boolean isVersionLoaded()
        Method to return if the version is loaded. If the class represented is not versioned then returns true
        Returns:
        Whether it is loaded.
      • evictFromTransaction

        void evictFromTransaction()
      • enlistInTransaction

        void enlistInTransaction()
      • makeTransactional

        void makeTransactional()
        Method to make the managed object transactional.
      • makeNontransactional

        void makeNontransactional()
        Method to make the managed object nontransactional.
      • makeTransient

        void makeTransient​(FetchPlanState state)
        Method to make the managed object transient.
        Parameters:
        state - Object containing the state of any fetch plan processing
      • makePersistent

        void makePersistent()
        Method to make the managed object persistent.
      • makePersistentTransactionalTransient

        void makePersistentTransactionalTransient()
        Method to make Transactional Transient instances persistent
      • deletePersistent

        void deletePersistent()
        Method to delete the object from persistence.
      • attachCopy

        T attachCopy​(T detachedPC,
                     boolean embedded)
        Method to attach to this the detached persistable instance
        Parameters:
        detachedPC - the detached persistable instance to be attached
        embedded - Whether it is embedded
        Returns:
        The attached copy
      • attach

        void attach​(boolean embedded)
        Method to attach the object managed by this ObjectProvider.
        Parameters:
        embedded - Whether it is embedded
      • attach

        void attach​(T detachedPC)
        Method to attach the provided detached object into the managed instance.
        Parameters:
        detachedPC - Detached object
      • detachCopy

        T detachCopy​(FetchPlanState state)
        Method to make detached copy of this instance
        Parameters:
        state - State for the detachment process
        Returns:
        the detached persistable instance
      • detach

        void detach​(FetchPlanState state)
        Method to detach the persistable object.
        Parameters:
        state - State for the detachment process
      • validate

        void validate()
        Validates whether the persistence capable instance exists in the datastore. If the instance does not exist in the datastore, this method will fail raising a NucleusObjectNotFoundException.
      • markForInheritanceValidation

        void markForInheritanceValidation()
        Mark the state manager as needing to validate the inheritance of the managed object existence before loading fields.
      • evict

        void evict()
        Method to change the object state to evicted.
      • refresh

        void refresh()
        Method to refresh the values of the currently loaded fields in the managed object.
      • retrieve

        void retrieve​(boolean fgOnly)
        Method to retrieve the fields for this object.
        Parameters:
        fgOnly - Whether to retrieve just the current fetch plan fields
      • preBegin

        void preBegin​(Transaction tx)
        Convenience interceptor to allow operations to be performed before the begin is performed
        Parameters:
        tx - The transaction
      • postCommit

        void postCommit​(Transaction tx)
        Convenience interceptor to allow operations to be performed after the commit is performed but before returning control to the application.
        Parameters:
        tx - The transaction
      • preRollback

        void preRollback​(Transaction tx)
        Convenience interceptor to allow operations to be performed before any rollback is performed.
        Parameters:
        tx - The transaction
      • resetDetachState

        void resetDetachState()
        Convenience method to reset the detached state in the current object.
      • retrieveDetachState

        void retrieveDetachState​(ObjectProvider op)
        Convenience method to retrieve the detach state from the passed ObjectProvider's object
        Parameters:
        op - ObjectProvider
      • checkInheritance

        void checkInheritance​(FieldValues fv)
        Deprecated.
        Dont use this, to be removed
        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. TODO This is only called by some outdated code in LDAPUtils; remove it when that is fixed
        Parameters:
        fv - the initial field values of the object.
      • markFieldsAsLoaded

        void markFieldsAsLoaded​(int[] fieldNumbers)
        Convenience method to mark all fields as "loaded". NOTE: This is a convenience mutator only to be used when you know what you are doing. Currently only used by the XML plugin.
        Parameters:
        fieldNumbers - The field numbers to mark as loaded