blackboard.persist
Interface PersistenceContext

public interface PersistenceContext

The PersistenceContext interface describes an object capable of storing and tracking object Id changes as those objects move between containers within the persistence framework. This is especially important when trying to properly resolve relationships between data objects as those objects are moved from one container to another.

An example of a data object relationship that needs to be tracked is that of an assessment, and a pool the assessment refers to. Since a pool is an independent object (it can exist external to an assessment) an assessment refers to a pool by its Id value. When moving both an assessment and a referenced pool to a new container, the old pool reference (Id value) contained in the assessment will no longer be valid (within the new container -- this is because the Id value of the pool is almost certain to change when it is persisted within the new target container) and it must therefore be mapped to be the new Id value of the pool in the new container space.

While special requirements may dictate the need to write a custom PersistenceContext implementation, the majority of needs should be met by the default implementation provided within the persistence framework. The default implementation is DefaultPersistenceContext.

Since:

Bb 5.5

Version:

$Revision: #1 $ $Date: 2005/06/27 $

See Also:

DefaultPersistenceContext

Method Summary

boolean	hasMapping(Id id) Returns whether or not a mapping exists for the given Id.
Id	mapId(Id idInContainerA, Container containerB) Maps the given Id in the specified container space.
void	registerReference(Id idInContainerA, Id idInContainerB) Registers an Id mapping with the context.

Method Detail

mapId

Id mapId(Id idInContainerA,
         Container containerB)

Maps the given Id in the specified container space. A mapping will exist, and thus be returned, if a prior call was made to registerReference(Id,Id) specifying the given idInContainerA value and another Id (idInContainerB) that exists within the specfied Container. If a proper mapping can not be found, null will be returned.

Parameters:

idInContainerA - the Id that we should look for a mapping of

containerB - the container into which we should look for the mapping

Returns:

the mapping for the given Id in the specified Container if a mapping was previously registered, null otherwise

registerReference

void registerReference(Id idInContainerA,
                       Id idInContainerB)

Registers an Id mapping with the context. A data object contains the Id of itself as it appeared in the last container that it interacted with. Therefore, it is necessary, when performing cross-container loading/persisting, to have a mapping between the object's Id as it existed in the original container (container A) and how it now appears in the new container (container B). This method provides a mechanism for storing that mapping.

Parameters:

idInContainerA - the object's Id as it existed in the original container

idInContainerB - the object's Id as it exists in the new container

hasMapping

boolean hasMapping(Id id)

Returns whether or not a mapping exists for the given Id. Has a previous call to registerReference(Id,Id) been made for the given Id value (the passed in Id value represents the Id in container A as provided to registerReference(Id,Id)). This method does not allow the caller to determine into which container the given Id maps, but only that a mapping does exist. If the caller wishes to determine if a mapping exists into a specific container, call mapId(Id,Container) and check for a null return value.

Parameters:

id - the Id that we should check for a mapping of

Returns:

true if a mapping does exist for the given Id, false otherwise