org.modeshape.graph.connector.base
Interface Transaction<NodeType extends Node,WorkspaceType extends Workspace>

Type Parameters:
NodeType - the type of node
WorkspaceType - the type of workspace
All Known Implementing Classes:
BaseTransaction, InfinispanTransaction, InMemoryTransaction, JBossCacheTransaction, JdbcMetadataRepository.JdbcMetadataTransaction, MapTransaction, PathTransaction

@NotThreadSafe
public interface Transaction<NodeType extends Node,WorkspaceType extends Workspace>

A transaction in which all read and write operations against a repository are performed. The actual transaction instance is obtained by calling Repository.startTransaction(ExecutionContext,boolean).

Note that implementations are not required to be thread-safe, since they (and their corresponding Connection) are expected to be used by a single thread.


Method Summary
 NodeType addChild(WorkspaceType workspace, NodeType parent, Name name, int index, UUID uuid, Iterable<Property> properties)
          Creates a new child node under the supplied parent, where the new child will have the specified name, properties, and (optionally) UUID.
 Location addChild(WorkspaceType workspace, NodeType parent, NodeType newChild, NodeType beforeOtherChild, Name desiredName)
          Inserts the specified child at the specified position in the list of children.
 NodeType cloneNode(WorkspaceType originalWorkspace, NodeType original, WorkspaceType newWorkspace, NodeType newParent, Name desiredName, Path.Segment desiredSegment, boolean removeExisting, Set<Location> removedExistingNodes)
          This should clone the subgraph given by the original node and place the cloned copy under the supplied new parent.
 void commit()
          Commit any changes that have been made to the repository.
 NodeType copyNode(WorkspaceType originalWorkspace, NodeType original, WorkspaceType newWorkspace, NodeType newParent, Name desiredName, boolean recursive)
          This should copy the subgraph given by the original node and place the new copy under the supplied new parent.
 boolean destroyWorkspace(WorkspaceType workspace)
          Destroy the workspace with the supplied name.
 NodeType getChild(WorkspaceType workspace, NodeType parent, Path.Segment childSegment)
          Find in the supplied parent node the child with the supplied name and same-name-sibling index.
 List<NodeType> getChildren(WorkspaceType workspace, NodeType node)
          Get the children for the supplied node.
 ExecutionContext getContext()
          Get the context in which this operator executes.
 NodeType getFirstChild(WorkspaceType workspace, NodeType parent, Name childName)
          Find in the supplied parent node the first child with the supplied name.
 NodeType getNode(WorkspaceType workspace, Location location)
          Find the node with the supplied unique identifier.
 NodeType getParent(WorkspaceType workspace, NodeType node)
          Returns the parent of the supplied node.
 NodeType getRootNode(WorkspaceType workspace)
          Get the root node of the repository workspace.
 WorkspaceType getWorkspace(String name, WorkspaceType originalToClone)
          Creates a new workspace with the given name containing only a root node.
 Set<String> getWorkspaceNames()
          Get the names of the existing workspaces.
 void lockNode(WorkspaceType workspace, NodeType node, LockBranchRequest.LockScope lockScope, long lockTimeoutInMillis)
          Attempts to lock the given node with the given timeout.
 Path pathFor(WorkspaceType workspace, NodeType node)
          Returns the path for the given node with this workspace if one exists, or a null if no node exists at the given path.
 QueryResults query(WorkspaceType workspace, AccessQueryRequest accessQuery)
          Perform a query of this workspace.
 void removeAllChildren(WorkspaceType workspace, NodeType node)
          Removes all of the children for this node in a single operation.
 Location removeNode(WorkspaceType workspace, NodeType node)
          Removes the given node from the repository.
 NodeType removeProperty(WorkspaceType workspace, NodeType node, Name propertyName)
          Removes the property with the given name
 void rollback()
          Rollback any changes that have been made to this repository.
 QueryResults search(WorkspaceType workspace, FullTextSearchRequest search)
          Perform a full-text search of this workspace.
 NodeType setProperties(WorkspaceType workspace, NodeType node, Iterable<Property> propertiesToSet, Iterable<Name> propertiesToRemove, boolean removeAllExisting)
          Sets the given properties in a single operation, overwriting any previous properties for the same name.
 void unlockNode(WorkspaceType workspace, NodeType node)
          Attempts to unlock the given node.
 

Method Detail

getContext

ExecutionContext getContext()
Get the context in which this operator executes.

Returns:
the execution context; never null

getWorkspaceNames

Set<String> getWorkspaceNames()
Get the names of the existing workspaces.

Returns:
the immutable set of workspace names; never null

getWorkspace

WorkspaceType getWorkspace(String name,
                           WorkspaceType originalToClone)
                                             throws InvalidWorkspaceException
Creates a new workspace with the given name containing only a root node. If the workspace already exists, it is left untouched and returned.

Parameters:
name - the name of the workspace; may not be null
originalToClone - the workspace that should be cloned, or null if the new workspace is to only contain a root node
Returns:
the newly created workspace; may not be null
Throws:
InvalidWorkspaceException - if the workspace could not be created

destroyWorkspace

boolean destroyWorkspace(WorkspaceType workspace)
                         throws InvalidWorkspaceException
Destroy the workspace with the supplied name.

Parameters:
workspace - the workspace that is to be destroyed; may not be null
Returns:
true if the workspace was destroyed, or false if the workspace did not exist
Throws:
InvalidWorkspaceException - if the workspace could not be destroyed

getRootNode

NodeType getRootNode(WorkspaceType workspace)
Get the root node of the repository workspace.

Parameters:
workspace - the workspace; may not be null
Returns:
the root node; never null

getNode

NodeType getNode(WorkspaceType workspace,
                 Location location)
Find the node with the supplied unique identifier.

Parameters:
workspace - the workspace; may not be null
location - of the node; may not be null
Returns:
the node, or null if there is no node with the supplied identifier
Throws:
PathNotFoundException - if the node at the given location could not be found

pathFor

Path pathFor(WorkspaceType workspace,
             NodeType node)
Returns the path for the given node with this workspace if one exists, or a null if no node exists at the given path.

Parameters:
workspace - the workspace; may not be null
node - the node for which the path should be retrieved; may not be null
Returns:
the path for the given node with this workspace if one exists or null if the node does not exist in this workspace

getParent

NodeType getParent(WorkspaceType workspace,
                   NodeType node)
Returns the parent of the supplied node. This method returns null if the supplied node is the root node.

Parameters:
workspace - the workspace; may not be null
node - the child node; may not be null
Returns:
the parent of this node; or null if the node is the root node for its workspace

getChild

NodeType getChild(WorkspaceType workspace,
                  NodeType parent,
                  Path.Segment childSegment)
Find in the supplied parent node the child with the supplied name and same-name-sibling index. This method returns null if the parent has no such child.

Parameters:
workspace - the workspace; may not be null
parent - the parent node; may not be null
childSegment - the segment of the child; may not be null
Returns:
the child of this node; or null if no such child exists

getFirstChild

NodeType getFirstChild(WorkspaceType workspace,
                       NodeType parent,
                       Name childName)
Find in the supplied parent node the first child with the supplied name. This method returns null if the parent has no such child.

Parameters:
workspace - the workspace; may not be null
parent - the parent node; may not be null
childName - the name of the child; may not be null
Returns:
the child of this node; or null if no such child exists

getChildren

List<NodeType> getChildren(WorkspaceType workspace,
                           NodeType node)
Get the children for the supplied node.

Parameters:
workspace - the workspace; may not be null
node - the node whose children are to be returned; may not be null
Returns:
the children, never null but possibly empty

removeAllChildren

void removeAllChildren(WorkspaceType workspace,
                       NodeType node)
Removes all of the children for this node in a single operation.

Parameters:
workspace - the workspace; may not be null
node - the node whose children are to be removed; may not be null

addChild

NodeType addChild(WorkspaceType workspace,
                  NodeType parent,
                  Name name,
                  int index,
                  UUID uuid,
                  Iterable<Property> properties)
Creates a new child node under the supplied parent, where the new child will have the specified name, properties, and (optionally) UUID. The child will be appended to the list of children, and will be given the appropriate same-name-sibling index.

Parameters:
workspace - the workspace; may not be null
parent - the parent node; may not be null
name - the name; may not be null
index - index at which the specified child is to be inserted, or -1 if the child is to be appended
uuid - the UUID of the node, or null if the UUID is to be generated
properties - the properties for the new node; may be null if there are no other properties
Returns:
the representation of the new node

addChild

Location addChild(WorkspaceType workspace,
                  NodeType parent,
                  NodeType newChild,
                  NodeType beforeOtherChild,
                  Name desiredName)
Inserts the specified child at the specified position in the list of children. Shifts the child currently at that position (if any) and any subsequent children to the right (adds one to their indices). The child is automatically removed from its existing parent (if it has one), though this method can be used to reorder a child within the same parent.

This method can also be used to rename an existing child by 'moving' the child node to the existing parent and a new desired name. However, if no 'beforeOtherChild' is supplied, then the node being renamed will also be moved to the end of the children.

Parameters:
workspace - the workspace; may not be null
parent - the parent node; may not be null
newChild - the node that is to be added as a child of the parent; may not be null
beforeOtherChild - the existing child before which the child is to be added; may be null if the child is to be added at the end
desiredName - the desired name for the node; may be null if the new child node's name is to be kept
Returns:
the actual location of the node, or null if the node didn't exist

removeNode

Location removeNode(WorkspaceType workspace,
                    NodeType node)
Removes the given node from the repository.

Parameters:
workspace - the workspace; may not be null
node - the node to be removed; may not be null
Returns:
the actual location of the node, or null if the node didn't exist

setProperties

NodeType setProperties(WorkspaceType workspace,
                       NodeType node,
                       Iterable<Property> propertiesToSet,
                       Iterable<Name> propertiesToRemove,
                       boolean removeAllExisting)
Sets the given properties in a single operation, overwriting any previous properties for the same name. This bulk mutator should be used when multiple properties are being set in order to allow underlying implementations to optimize their access to their respective persistent storage mechanism. The implementation should not change the identification properties.

Parameters:
workspace - the workspace; may not be null
node - the node; may not be null
propertiesToSet - the properties to set; may be null or empty if there are no properties being added or set
propertiesToRemove - the names of the properties that are to be removed; may be null or empty if no properties are being removed
removeAllExisting - true if all existing, non-identification properties should be removed, or false otherwise
Returns:
this map node

removeProperty

NodeType removeProperty(WorkspaceType workspace,
                        NodeType node,
                        Name propertyName)
Removes the property with the given name

Parameters:
workspace - the workspace; may not be null
node - the node; may not be null
propertyName - the name of the property to remove; may not be null
Returns:
this map node

cloneNode

NodeType cloneNode(WorkspaceType originalWorkspace,
                   NodeType original,
                   WorkspaceType newWorkspace,
                   NodeType newParent,
                   Name desiredName,
                   Path.Segment desiredSegment,
                   boolean removeExisting,
                   Set<Location> removedExistingNodes)
                                throws UuidAlreadyExistsException
This should clone the subgraph given by the original node and place the cloned copy under the supplied new parent. Note that internal references between nodes within the original subgraph must be reflected as internal nodes within the new subgraph.

Parameters:
originalWorkspace - the workspace containing the original node that is being cloned; may not be null
original - the node to be cloned; may not be null
newWorkspace - the workspace containing the new parent node; may not be null
newParent - the parent where the clone is to be placed; may not be null
desiredName - the desired name for the node; if null, the name will be calculated from desiredSegment; Exactly one of desiredSegment and desiredName must be non-null
desiredSegment - the exact segment at which the clone should be rooted; if null, the name will be inferred from desiredName; Exactly one of desiredSegment and desiredName must be non-null
removeExisting - true if existing nodes in the new workspace with the same UUIDs as nodes in the branch rooted at original should be removed; if false, a UuidAlreadyExistsException will be thrown if a UUID conflict is detected
removedExistingNodes - the set into which should be placed all of the existing nodes that were removed as a result of this clone operation, or null if these nodes need not be collected
Returns:
the new node, which is the top of the new subgraph
Throws:
UuidAlreadyExistsException - if removeExisting is true and and a UUID in the source tree already exists in the new workspace

copyNode

NodeType copyNode(WorkspaceType originalWorkspace,
                  NodeType original,
                  WorkspaceType newWorkspace,
                  NodeType newParent,
                  Name desiredName,
                  boolean recursive)
This should copy the subgraph given by the original node and place the new copy under the supplied new parent. Note that internal references between nodes within the original subgraph must be reflected as internal nodes within the new subgraph.

Parameters:
originalWorkspace - the workspace containing the original node that is being cloned; may not be null
original - the node to be copied; may not be null
newWorkspace - the workspace containing the new parent node; may not be null
newParent - the parent where the copy is to be placed; may not be null
desiredName - the desired name for the node; if null, the name will be obtained from the original node
recursive - true if the copy should be recursive
Returns:
the new node, which is the top of the new subgraph

query

QueryResults query(WorkspaceType workspace,
                   AccessQueryRequest accessQuery)
Perform a query of this workspace.

Parameters:
workspace - the workspace to be searched; may not be null
accessQuery - the access query; may not be null
Returns:
the query results, or null if the query is not supported

search

QueryResults search(WorkspaceType workspace,
                    FullTextSearchRequest search)
Perform a full-text search of this workspace.

Parameters:
workspace - the workspace to be searched; may not be null
search - the full-text search; may not be null
Returns:
the query results, or null if the query is not supported

lockNode

void lockNode(WorkspaceType workspace,
              NodeType node,
              LockBranchRequest.LockScope lockScope,
              long lockTimeoutInMillis)
              throws LockFailedException
Attempts to lock the given node with the given timeout. If the lock attempt fails, a LockFailedException will be thrown.

Parameters:
workspace - the workspace; may not be null
node - the node to be locked; may not be null
lockScope - the scope of the lock (i.e., whether descendants of node should be included in the lock
lockTimeoutInMillis - the maximum lifetime of the lock in milliseconds; zero (0) indicates that the connector default should be used
Throws:
LockFailedException - if the implementing connector supports locking but the lock could not be acquired.

unlockNode

void unlockNode(WorkspaceType workspace,
                NodeType node)
Attempts to unlock the given node.

Parameters:
workspace - the workspace; may not be null
node - the node to be unlocked; may not be null

commit

void commit()
Commit any changes that have been made to the repository. This method may throw runtime exceptions if there are failures committing the changes, but the transaction is still expected to be closed.

See Also:
rollback()

rollback

void rollback()
Rollback any changes that have been made to this repository. This method may throw runtime exceptions if there are failures rolling back the changes, but the transaction is still expected to be closed.

See Also:
commit()


Copyright © 2008-2010 JBoss, a division of Red Hat. All Rights Reserved.