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, DiskTransaction, 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.
List<Location>	getChildrenLocations(WorkspaceType workspace, NodeType node) Get the locations for all children of 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.
Location	verifyNodeExists(WorkspaceType workspace, Location location) Verify that the supplied node exists.

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

verifyNodeExists

Location verifyNodeExists(WorkspaceType workspace,
                          Location location)

Verify that the supplied node exists.

Parameters:

workspace - the workspace; may not be null

location - of the node; may not be null

Returns:

the actual location of the node; never null

Throws:

PathNotFoundException - if the node at the given location does not exist

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

getChildrenLocations

List<Location> getChildrenLocations(WorkspaceType workspace,
                                    NodeType node)

Get the locations for all children of 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 locations of all 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()