org.priha.providers
Interface RepositoryProvider

All Known Implementing Classes:
EhCachingProvider, FileProvider, JdbcProvider, MemoryProvider

public interface RepositoryProvider

A few ground rules:

Priha RepositoryManager ensures that methods which modify the repository (addNode(), close(), copy(), move(), open(), putPropertyValue(), remove(), start(), stop(), storeFinished(), storeStarted()) are single-threaded. However, the rest of the methods which are supposed to read from the repository, are protected by a read lock, and therefore they can be accessed at the same time from multiple threads. If you do any modifications anywhere, make sure these are thread-safe.

The RepositoryProvider lifecycle is as follows.

  1. When Priha first starts up and parses its configuration, it locates each RepositoryProvider from the configuration, and calls its start() method to notify that it exists.
  2. Once the user then grabs a Session object, the RepositoryProvider is notified via the open() method.
  3. The user now uses all of the other methods from the repo.
  4. Once the user chooses to logout, then the close() method is called.
  5. Then, finally, when Priha closes down, the stop() method will be called. Priha installs its own shutdown hook for this case.


Method Summary
 void addNode(StoreTransaction tx, Path path, QNodeDefinition definition)
          Adds a new Node to the repository to the given Path.
 void close(WorkspaceImpl ws)
          The repository will no longer be used by a session, so any session-specific things can now be deallocated.
 Path findByUUID(WorkspaceImpl ws, java.lang.String uuid)
          If an item by this UUID exists, returns a Path.
 java.util.List<Path> findReferences(WorkspaceImpl ws, java.lang.String uuid)
          Finds all the Property paths which are of type REFERENCE and whose content is equal to the UUID given.
 ValueContainer getPropertyValue(WorkspaceImpl ws, Path path)
          Returns the value of a property.
 boolean itemExists(WorkspaceImpl ws, Path path, ItemType type)
          Returns true, if the Item exists and is of given type.
 java.util.List<Path> listNodes(WorkspaceImpl ws, Path parentpath)
          Lists all the Nodes from the repository which belong to this parent.
 java.util.List<QName> listProperties(WorkspaceImpl ws, Path path)
          Returns a list of properties for a Node.
 java.util.Collection<java.lang.String> listWorkspaces()
          Lists all workspaces which are available in this Repository.
 void open(RepositoryImpl rep, javax.jcr.Credentials credentials, java.lang.String workspaceName)
          Opens a repository.
 void putPropertyValue(StoreTransaction tx, Path path, ValueContainer property)
          Sets or adds a new Property to the repository.
 void remove(StoreTransaction tx, Path path)
          Removes a node or a property from the repository.
 void reorderNodes(StoreTransaction tx, Path path, java.util.List<Path> childOrder)
           
 void start(RepositoryImpl repository, java.util.Properties properties)
          Starts access to a repository.
 void stop(RepositoryImpl rep)
          Stops a given repository.
 void storeCancelled(StoreTransaction tx)
          If the store has been cancelled and changes need to be rolled back.
 void storeFinished(StoreTransaction tx)
          This method is called when the repository-changing operation is complete.
 StoreTransaction storeStarted(WorkspaceImpl ws)
          This method is called whenever Priha starts a transaction which will save the contents of the repository.
 

Method Detail

open

void open(RepositoryImpl rep,
          javax.jcr.Credentials credentials,
          java.lang.String workspaceName)
          throws javax.jcr.RepositoryException,
                 javax.jcr.NoSuchWorkspaceException
Opens a repository. Called whenever a session login() is performed.

Parameters:
rep - The Repository which owns this Provider.
credentials - The Credentials object passed to the Session.open() call. May be null, if there were no credentials.
workspaceName - The workspace which will be accessed.
Throws:
javax.jcr.NoSuchWorkspaceException - if no such workspace exists.
javax.jcr.RepositoryException

start

void start(RepositoryImpl repository,
           java.util.Properties properties)
           throws ConfigurationException
Starts access to a repository. This is called only once per RepositoryProvider lifecycle.

Parameters:
repository - The Repository which owns this provider.
properties - A set of filtered properties for this provider.
Throws:
ConfigurationException - If the repository cannot be started due to a faulty configuration.
See Also:
ProviderManager.filterProperties(RepositoryImpl, String)

stop

void stop(RepositoryImpl rep)
Stops a given repository. This may be called without a preceding call to close(). All allocated resources can now be deallocated.

This method will only be called when the Repository shuts down.

Parameters:
rep - The Repository object.

close

void close(WorkspaceImpl ws)
The repository will no longer be used by a session, so any session-specific things can now be deallocated.

Parameters:
ws - The Workspace attached to the Session.

listWorkspaces

java.util.Collection<java.lang.String> listWorkspaces()
                                                      throws javax.jcr.RepositoryException
Lists all workspaces which are available in this Repository. This method is called after start() but before open().

Returns:
The workspace names.
Throws:
javax.jcr.RepositoryException

listProperties

java.util.List<QName> listProperties(WorkspaceImpl ws,
                                     Path path)
                                     throws javax.jcr.PathNotFoundException,
                                            javax.jcr.RepositoryException
Returns a list of properties for a Node.

Parameters:
ws - The Workspace in which the properties should be located.
path - The path of the Node.
Returns:
A List of the names of the properties under this Node.
Throws:
javax.jcr.PathNotFoundException - If the path given does not exist.
javax.jcr.RepositoryException - If something goes wrong.

getPropertyValue

ValueContainer getPropertyValue(WorkspaceImpl ws,
                                Path path)
                                throws javax.jcr.PathNotFoundException,
                                       javax.jcr.RepositoryException
Returns the value of a property.

Parameters:
ws - The workspace in which the property value should be located.
path - The path to the Property
Returns:
Either a ValueImpl or ValueImpl[], depending on whether this is a multi-valued thing
Throws:
javax.jcr.RepositoryException - If something goes wrong.
javax.jcr.PathNotFoundException - If there is nothing at the end of this Path, i.e. the object could not be found.

itemExists

boolean itemExists(WorkspaceImpl ws,
                   Path path,
                   ItemType type)
                   throws javax.jcr.RepositoryException
Returns true, if the Item exists and is of given type.

Parameters:
ws - The workspace in which the existence of the Node is checked.
path - The path to the Node.
type - Type to check for
Returns:
True, if the item exists. False otherwise (like when it's actually of a different type)
Throws:
javax.jcr.RepositoryException

listNodes

java.util.List<Path> listNodes(WorkspaceImpl ws,
                               Path parentpath)
                               throws javax.jcr.RepositoryException
Lists all the Nodes from the repository which belong to this parent.

Parameters:
ws - The Workspace.
parentpath - The path to the Node whose children should be listed.
Returns:
A List of Path objects with the full paths to the children.
Throws:
javax.jcr.RepositoryException - If the children cannot be found.

findByUUID

Path findByUUID(WorkspaceImpl ws,
                java.lang.String uuid)
                throws javax.jcr.ItemNotFoundException,
                       javax.jcr.RepositoryException
If an item by this UUID exists, returns a Path.

Parameters:
ws -
uuid -
Returns:
Throws:
javax.jcr.ItemNotFoundException - If the repository does not contain an UUID by this name.
javax.jcr.RepositoryException

findReferences

java.util.List<Path> findReferences(WorkspaceImpl ws,
                                    java.lang.String uuid)
                                    throws javax.jcr.RepositoryException
Finds all the Property paths which are of type REFERENCE and whose content is equal to the UUID given.

Parameters:
ws -
uuid -
Returns:
A list of paths to properties which reference the node by the given UUID.
Throws:
javax.jcr.RepositoryException

addNode

void addNode(StoreTransaction tx,
             Path path,
             QNodeDefinition definition)
             throws javax.jcr.RepositoryException
Adds a new Node to the repository to the given Path. The properties of the Node will be stored separately using successive putPropertyValue() calls. This includes also system things like the jcr:primaryType, so this method really exists just to ensure that the Node can be added to the repository.

Parameters:
ws - The workspace.
path - Path to the node in this workspace.
Throws:
javax.jcr.RepositoryException - If the Node cannot be added.

putPropertyValue

void putPropertyValue(StoreTransaction tx,
                      Path path,
                      ValueContainer property)
                      throws javax.jcr.RepositoryException
Sets or adds a new Property to the repository. Note that a Property may be multi-valued. It is up to the provider to decide how it serializes the data.

Parameters:
ws - The workspace
property - The Property content to store.
Throws:
javax.jcr.RepositoryException - If the property cannot be stored.

remove

void remove(StoreTransaction tx,
            Path path)
            throws javax.jcr.RepositoryException
Removes a node or a property from the repository. If the removed entity is a Node, all of its children and properties MUST also be removed from the repository.

In addition, it MUST NOT be an error if remove() is called on a path which is already removed. In such a case, remove() shall fail silently.

Parameters:
ws -
path -
Throws:
javax.jcr.RepositoryException

storeStarted

StoreTransaction storeStarted(WorkspaceImpl ws)
                              throws javax.jcr.RepositoryException
This method is called whenever Priha starts a transaction which will save the contents of the repository. You could, for example, use this to start a transaction.

Parameters:
ws - The workspace
Returns:
An arbitrary StoreTransaction object. May be null.
Throws:
javax.jcr.RepositoryException

storeFinished

void storeFinished(StoreTransaction tx)
                   throws javax.jcr.RepositoryException
This method is called when the repository-changing operation is complete. For example, you could close the transaction at this stage.

Parameters:
tx - The same StoreTransaction object which was returned from storeStarted().
Throws:
javax.jcr.RepositoryException

storeCancelled

void storeCancelled(StoreTransaction tx)
                    throws javax.jcr.RepositoryException
If the store has been cancelled and changes need to be rolled back. A RepositoryProvider should use this opportunity to make sure it is in a consistent state.

Parameters:
tx - The transaction from storeStarted().
Throws:
javax.jcr.RepositoryException

reorderNodes

void reorderNodes(StoreTransaction tx,
                  Path path,
                  java.util.List<Path> childOrder)
                  throws javax.jcr.RepositoryException
Throws:
javax.jcr.RepositoryException