org.apache.jackrabbit.core.state
Class SharedItemStateManager

java.lang.Object
  org.apache.jackrabbit.core.state.SharedItemStateManager

All Implemented Interfaces:

ItemStateListener, ItemStateManager, Dumpable

Direct Known Subclasses:

VersionItemStateManager

public class SharedItemStateManager
extends Object
implements ItemStateManager, ItemStateListener, Dumpable

Shared ItemStateManager (SISM). Caches objects returned from a PersistenceManager. Objects returned by this item state manager are shared among all sessions.

A shared item state manager operates on a PersistenceManager (PM) that is used to load and store the item states. Additionally, a SISM can have VirtualItemStateProviders (VISP) that are used to provide additional, non-persistent, read-only states. Examples of VISP are the content representation of the NodeTypes (/jcr:system/jcr:nodeTypes) and the version store (/jcr:system/jcr:versionStore). those 2 VISP are added to the SISM during initialization of a workspace. i.e. they are 'mounted' to all workspaces. we assume, that VISP cannot be added dynamically, neither during runtime nor by configuration.

The states from the VISP are readonly. by the exception for node references. remember that the referrers are stored in a NodeReferences state, having the ID of the target state.
there are 5 types of referential relations to be distinguished:

1. normal --> normal (references from 'normal' states to 'normal' states) this is the normal case and will be handled by the SISM.
2. normal --> virtual (references from 'normal' states to 'virtual' states) those references should be handled by the VISP rather by the SISM.
3. virtual --> normal (references from 'virtual' states to 'normal' states) such references are not supported. eg. references of versioned nodes do not impose any constraints on the referenced nodes.
4. virtual --> virtual (references from 'virtual' states to 'virtual' states of the same VISP). intra-virtual references are handled by the item state manager of the VISP.
5. virtual --> virtual' (references from 'virtual' states to 'virtual' states of different VISP). those do currently not occurr and are therfor not supported.

if VISP are not dynamic, there is not risk that NV-type references can dangle (since a VISP cannot be 'unmounted', leaving eventual references dangling). although multi-workspace-referrers are not explicitelt supported, the architecture of NodeReferences support multiple referrers with the same PropertyId. So the number of references can be tracked (an example of multi-workspace-refferres is a version referenced by the jcr:baseVersion of several (corresponding) nodes in multiple workspaces).
As mentioned, VN-type references should not impose any constraints on the referrers (e.g. a normal node referenced by a versioned reference property). In case of the version store, the VN-type references are not stored at all, but reinforced as NN-type references in the normal states in case of a checkout operation.
VV-type references should be handled by the respective VISP. they look as NN-type references in the scope if the VISP anyway...so no special treatment should be neccessairy.
VV'-type references are currently not possible, since the version store and virtual nodetype representation don't allow such references.

Constructor Summary

SharedItemStateManager(PersistenceManager persistMgr, NodeId rootNodeId, NodeTypeRegistry ntReg, boolean usesReferences, ItemStateCacheFactory cacheFactory, ISMLocking locking)
Creates a new SharedItemStateManager instance.

Method Summary

void	addListener(ItemStateListener listener) Add an ItemStateListener
void	addVirtualItemStateProvider(VirtualItemStateProvider prov) Adds a new virtual item state provider. NOTE: This method is not synchronized, because it is called right after creation only by the same thread and therefore concurrency issues do not occur.
org.apache.jackrabbit.core.state.SharedItemStateManager.Update	beginUpdate(ChangeLog local, EventStateCollectionFactory factory, VirtualItemStateProvider virtualProvider) Begin update operation.
protected void	checkReferentialIntegrity(ChangeLog changes) Verifies that no referenceable nodes are deleted if they are still being referenced targets of modified node references exist
void	dispose() Disposes this SharedItemStateManager and frees resources.
protected void	doExternalUpdate(ChangeLog external) Perform the external update.
void	dump(PrintStream ps) Dumps the state of this instance in a human readable format for diagnostic purposes.
void	externalUpdate(ChangeLog external, EventStateCollection events) Handle an external update.
ItemState	getItemState(ItemId id) Return an item state, given its item id.
NodeReferences	getNodeReferences(NodeReferencesId id) Return a node references object, given its target id
boolean	hasItemState(ItemId id) Return a flag indicating whether an item state for a given item id exists.
boolean	hasNodeReferences(NodeReferencesId id) Return a flag indicating whether a node references object for a given target id exists.
void	removeListener(ItemStateListener listener) Remove an ItemStateListener
void	setEventChannel(UpdateEventChannel eventChannel) Set an update event channel
void	setISMLocking(ISMLocking ismLocking) Sets a new locking strategy.
void	setNoLockHack(boolean noLockHack) enables or disables the write-lock hack.
void	stateCreated(ItemState created) Called when an ItemState has successfully been created (i.e. Notifications are received for items that this manager created itself or items that are managed by one of the virtual providers.
void	stateDestroyed(ItemState destroyed) Called when an ItemState has successfully been removed (i.e. Notifications are received for items that this manager created itself or items that are managed by one of the virtual providers.
void	stateDiscarded(ItemState discarded) Called when an ItemState has been discarded (i.e. Notifications are received for items that this manager created itself or items that are managed by one of the virtual providers.
void	stateModified(ItemState modified) Called when an ItemState has successfully been modified (i.e. Notifications are received for items that this manager created itself or items that are managed by one of the virtual providers.
void	update(ChangeLog local, EventStateCollectionFactory factory) Store modifications registered in a ChangeLog.
protected void	updateReferences(ChangeLog changes, VirtualItemStateProvider virtualProvider) Updates the target node references collections based on the modifications in the change log (i.e.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SharedItemStateManager

public SharedItemStateManager(PersistenceManager persistMgr,
                              NodeId rootNodeId,
                              NodeTypeRegistry ntReg,
                              boolean usesReferences,
                              ItemStateCacheFactory cacheFactory,
                              ISMLocking locking)
                       throws ItemStateException

Creates a new SharedItemStateManager instance.

Parameters:

persistMgr -

rootNodeId -

ntReg -

Throws:

ItemStateException

Method Detail

setNoLockHack

public void setNoLockHack(boolean noLockHack)

enables or disables the write-lock hack. this should only be called by the XAVersionManager.

Parameters:

noLockHack -

setEventChannel

public void setEventChannel(UpdateEventChannel eventChannel)

Set an update event channel

Parameters:

eventChannel - update event channel

setISMLocking

public void setISMLocking(ISMLocking ismLocking)

Sets a new locking strategy.

Parameters:

ismLocking - the locking strategy for this item state manager.

getItemState

public ItemState getItemState(ItemId id)
                       throws NoSuchItemStateException,
                              ItemStateException

Return an item state, given its item id.

Specified by:

getItemState in interface ItemStateManager

Parameters:

id - item id

Returns:

item state

Throws:

NoSuchItemStateException - if the item does not exist

ItemStateException - if an error occurs

hasItemState

public boolean hasItemState(ItemId id)

Return a flag indicating whether an item state for a given item id exists.

Specified by:

hasItemState in interface ItemStateManager

Parameters:

id - item id

Returns:

true if an item state exists, otherwise false

getNodeReferences

public NodeReferences getNodeReferences(NodeReferencesId id)
                                 throws NoSuchItemStateException,
                                        ItemStateException

Return a node references object, given its target id

Specified by:

getNodeReferences in interface ItemStateManager

Parameters:

id - target id

Returns:

node references object

Throws:

NoSuchItemStateException - if the item does not exist

ItemStateException - if an error occurs

hasNodeReferences

public boolean hasNodeReferences(NodeReferencesId id)

Return a flag indicating whether a node references object for a given target id exists.

Specified by:

hasNodeReferences in interface ItemStateManager

Parameters:

id - target id

Returns:

true if a node reference object exists for the given id, otherwise false.

stateCreated

public void stateCreated(ItemState created)

Called when an ItemState has successfully been created (i.e. its underlying persistent state was created).

Notifications are received for items that this manager created itself or items that are managed by one of the virtual providers.

Specified by:

stateCreated in interface ItemStateListener

Parameters:

created - the ItemState that has been 'created'

stateModified

public void stateModified(ItemState modified)

Called when an ItemState has successfully been modified (i.e. its underlying persistent state has changed).

Notifications are received for items that this manager created itself or items that are managed by one of the virtual providers.

Specified by:

stateModified in interface ItemStateListener

Parameters:

modified - the ItemState that has been 'modified'

stateDestroyed

public void stateDestroyed(ItemState destroyed)

Called when an ItemState has successfully been removed (i.e. its underlying persistent state has been destroyed).

Notifications are received for items that this manager created itself or items that are managed by one of the virtual providers.

Specified by:

stateDestroyed in interface ItemStateListener

Parameters:

destroyed - the ItemState that has been 'destroyed'

stateDiscarded

public void stateDiscarded(ItemState discarded)

Called when an ItemState has been discarded (i.e. it has been rendered 'invalid').

Notifications are received for items that this manager created itself or items that are managed by one of the virtual providers.

Specified by:

stateDiscarded in interface ItemStateListener

Parameters:

discarded - the ItemState that has been discarded

See Also:

ItemState.discard()

dump

public void dump(PrintStream ps)

Dumps the state of this instance in a human readable format for diagnostic purposes.

Specified by:

dump in interface Dumpable

Parameters:

ps - stream to dump state to

dispose

public void dispose()

Disposes this SharedItemStateManager and frees resources.

addVirtualItemStateProvider

public void addVirtualItemStateProvider(VirtualItemStateProvider prov)

Adds a new virtual item state provider.

NOTE: This method is not synchronized, because it is called right after creation only by the same thread and therefore concurrency issues do not occur. Should this ever change, the synchronization status has to be re-examined.

Parameters:

prov -

beginUpdate

public org.apache.jackrabbit.core.state.SharedItemStateManager.Update beginUpdate(ChangeLog local,
                                                                                  EventStateCollectionFactory factory,
                                                                                  VirtualItemStateProvider virtualProvider)
                                                                           throws ReferentialIntegrityException,
                                                                                  StaleItemStateException,
                                                                                  ItemStateException

Begin update operation. This will return an object that can itself be ended/cancelled.

Throws:

ReferentialIntegrityException

StaleItemStateException

ItemStateException

update

public void update(ChangeLog local,
                   EventStateCollectionFactory factory)
            throws ReferentialIntegrityException,
                   StaleItemStateException,
                   ItemStateException

Store modifications registered in a ChangeLog. The items contained in the ChangeLog are not states returned by this item state manager but rather must be reconnected to items provided by this state manager.

After successfully storing the states the observation manager is informed about the changes, if an observation manager is passed to this method.

NOTE: This method is not synchronized, because all methods it invokes on instance members (such as PersistenceManager.store(org.apache.jackrabbit.core.state.ChangeLog) are considered to be thread-safe. Should this ever change, the synchronization status has to be re-examined.

Parameters:

local - change log containing local items

factory - event state collection factory

Throws:

ReferentialIntegrityException - if a new or modified REFERENCE property refers to a non-existent target or if a removed node is still being referenced

StaleItemStateException - if at least one of the affected item states has become stale

ItemStateException - if another error occurs

externalUpdate

public void externalUpdate(ChangeLog external,
                           EventStateCollection events)

Handle an external update.

Parameters:

external - external change containing only node and property ids.

events - events to deliver

doExternalUpdate

protected void doExternalUpdate(ChangeLog external)

Perform the external update. While executing this method, the writeLock on this manager is held.

Parameters:

external - external change containing only node and property ids.

addListener

public void addListener(ItemStateListener listener)

Add an ItemStateListener

Parameters:

listener - the new listener to be informed on modifications

removeListener

public void removeListener(ItemStateListener listener)

Remove an ItemStateListener

Parameters:

listener - an existing listener

updateReferences

protected void updateReferences(ChangeLog changes,
                                VirtualItemStateProvider virtualProvider)
                         throws ItemStateException

Updates the target node references collections based on the modifications in the change log (i.e. added/removed/modified REFERENCE properties).

Important node: For consistency reasons this method must only be called once per change log and the change log should not be modified anymore afterwards.

Parameters:

changes - change log

virtualProvider - virtual provider that may already contain a node references object

Throws:

ItemStateException - if an error occurs

checkReferentialIntegrity

protected void checkReferentialIntegrity(ChangeLog changes)
                                  throws ReferentialIntegrityException,
                                         ItemStateException

Verifies that

• no referenceable nodes are deleted if they are still being referenced
• targets of modified node references exist

Parameters:

changes - change log

Throws:

ReferentialIntegrityException - if a new or modified REFERENCE property refers to a non-existent target or if a removed node is still being referenced

ItemStateException - if another error occurs