org.apache.jackrabbit.core.persistence

Interface PersistenceManager

All Known Subinterfaces:

IterablePersistenceManager

All Known Implementing Classes:

AbstractBundlePersistenceManager, AbstractPersistenceManager, BundleDbPersistenceManager, BundleFsPersistenceManager, DatabasePersistenceManager, DerbyPersistenceManager, DerbyPersistenceManager, H2PersistenceManager, InMemBundlePersistenceManager, InMemPersistenceManager, JNDIDatabasePersistenceManager, MSSqlPersistenceManager, MSSqlPersistenceManager, MySqlPersistenceManager, ObjectPersistenceManager, Oracle9PersistenceManager, OraclePersistenceManager, OraclePersistenceManager, PostgreSQLPersistenceManager, SimpleDbPersistenceManager, XMLPersistenceManager

public interface PersistenceManager

Persistence manager interface. Persistence managers are internal Jackrabbit components that handle the persistent storage of content nodes and properties. A persistence manager knows how to retrieve the persistent states of content items and how to atomically save a set of changes to the persistent state.

Each workspace of a Jackrabbit content repository uses separate persistence manager to store the content in that workspace. Also the Jackrabbit version handler uses a separate persistence manager. The persistence managers in use are configured in the Jackrabbit XML configuration files. The configured persistence managers are instantiated and initialized using the JavaBeans conventions.

Persistence manager life cycle

The life cycle of a persistence manager instance contains four phases:

1. Instantiation, where the instance is created and possible configuration properties are set using the JavaBean conventions. During this phase the persistence manager should not attempt to reference any external resources.
2. Initialization, where the init method is invoked to bind the persistence manager with a given context.
3. Normal usage, where the various create, load, exists, and store methods of the persistence manager are used to manage the persistent content items.
4. Closing, where the close method is invoked to close the persistence manager and release all acquired resources.

Concurrency

A persistence manager instance should be thread-safe and guarantee that the store(ChangeLog) method calls are atomic. Any load() or exists() calls started after a store() call has returned must access the updated content. The client accessing a persistence manager must guarantee that no two concurrent store(ChangeLog) calls will modify the same items.

Method Summary

Modifier and Type	Method and Description
void	checkConsistency(String[] uuids, boolean recursive, boolean fix) Perform a consistency check of the data.
void	close() Closes the persistence manager.
NodeState	createNew(NodeId id) Creates a new node state instance with the given id.
PropertyState	createNew(PropertyId id) Creates a new property state instance with the given id.
boolean	exists(NodeId id) Checks whether the identified node exists.
boolean	exists(PropertyId id) Checks whether the identified property exists.
boolean	existsReferencesTo(NodeId targetId) Checks whether references of the identified target node exist.
void	init(PMContext context) Initializes the persistence manager.
NodeState	load(NodeId id) Load the persistent members of a node state.
PropertyState	load(PropertyId id) Load the persistent members of a property state.
NodeReferences	loadReferencesTo(NodeId id) Load the persisted references to the node with the given identifier.
void	store(ChangeLog changeLog) Atomically saves the given set of changes.

Method Detail

init

void init(PMContext context)
   throws Exception

Initializes the persistence manager. The persistence manager is permanently bound to the given context, and any required external resources are acquired.

An appropriate exception is thrown if the persistence manager initialization fails for whatever reason. In this case the state of the persistence manager is undefined and the instance should be discarded.

Parameters:

context - persistence manager context

Throws:

Exception - if the persistence manager initialization failed

close

void close()
    throws Exception

Closes the persistence manager. The consistency of the persistent storage is guaranteed and all acquired resources are released. It is an error to invoke any methods on a closed persistence manager, and implementations are free to enforce this constraint by throwing IllegalStateExceptions in such cases.

An appropriate exception is thrown if the persistence manager could not be closed properly. In this case the state of the persistence manager is undefined and the instance should be discarded.

Throws:

Exception - if the persistence manager failed to close properly

createNew

NodeState createNew(NodeId id)

Creates a new node state instance with the given id.

Parameters:

id - node id

Returns:

node state instance

createNew

PropertyState createNew(PropertyId id)

Creates a new property state instance with the given id.

Parameters:

id - property id

Returns:

property state instance

load

NodeState load(NodeId id)
        throws NoSuchItemStateException,
               ItemStateException

Load the persistent members of a node state.

Parameters:

id - node id

Returns:

loaded node state

Throws:

NoSuchItemStateException - if the node state does not exist

ItemStateException - if another error occurs

load

PropertyState load(PropertyId id)
            throws NoSuchItemStateException,
                   ItemStateException

Load the persistent members of a property state.

Parameters:

id - property id

Returns:

loaded property state

Throws:

NoSuchItemStateException - if the property state does not exist

ItemStateException - if another error occurs

loadReferencesTo

NodeReferences loadReferencesTo(NodeId id)
                         throws NoSuchItemStateException,
                                ItemStateException

Load the persisted references to the node with the given identifier.

Parameters:

id - reference target node id

Throws:

NoSuchItemStateException - if the target node does not exist

ItemStateException - if another error occurs

exists

boolean exists(NodeId id)
        throws ItemStateException

Checks whether the identified node exists.

Parameters:

id - node id

Returns:

true if the node exists, false otherwise

Throws:

ItemStateException - on persistence manager errors

exists

boolean exists(PropertyId id)
        throws ItemStateException

Checks whether the identified property exists.

Parameters:

id - property id

Returns:

true if the property exists, false otherwise

Throws:

ItemStateException - on persistence manager errors

existsReferencesTo

boolean existsReferencesTo(NodeId targetId)
                    throws ItemStateException

Checks whether references of the identified target node exist.

Parameters:

targetId - target node id

Returns:

true if the references exist, false otherwise

Throws:

ItemStateException - on persistence manager errors

store

void store(ChangeLog changeLog)
    throws ItemStateException

Atomically saves the given set of changes.

Parameters:

changeLog - change log containing states that were changed

Throws:

ItemStateException - if the changes could not be saved

checkConsistency

void checkConsistency(String[] uuids,
                      boolean recursive,
                      boolean fix)

Perform a consistency check of the data. An example are non-existent nodes referenced in a child node entry. The existence of this feature and the scope of the implementation can vary in different PersistenceManager implementations.

Parameters:

uuids - list of UUIDs of nodes to be checked. if null, all nodes will be checked

recursive - if true, the tree(s) below the given node(s) will be traversed and checked as well

fix - if true, any problems found that can be repaired will be repaired. if false, no data will be modified, instead all inconsistencies will only get logged