javax.jcr.Workspace Maven / Gradle / Ivy
/*
* Copyright 2009 Day Management AG, Switzerland. All rights reserved.
*/
package javax.jcr;
import org.xml.sax.ContentHandler;
import javax.jcr.lock.LockException;
import javax.jcr.lock.LockManager;
import javax.jcr.nodetype.ConstraintViolationException;
import javax.jcr.nodetype.NodeTypeManager;
import javax.jcr.observation.ObservationManager;
import javax.jcr.query.QueryManager;
import javax.jcr.version.Version;
import javax.jcr.version.VersionException;
import javax.jcr.version.VersionManager;
import java.io.IOException;
import java.io.InputStream;
/**
* A Workspace object represents a view onto a persitent workspace
* within a repository. This view is defined by the authorization settings of
* the Session object associated with the Workspace
* object. Each Workspace object is associated one-to-one with a
* Session object. The Workspace object can be
* acquired by calling {@link Session#getWorkspace()} on the
* associated Session object.
*/
public interface Workspace {
/**
* A constant for the name of the workspace root node.
*
* @since JCR 2.0
*/
public static final String NAME_WORKSPACE_ROOT = "";
/**
* A constant for the absolute path of the workspace root node.
*
* @since JCR 2.0
*/
public static final String PATH_WORKSPACE_ROOT = "/";
/**
* A constant for the name of the system node.
*
* @since JCR 2.0
*/
public static final String NAME_SYSTEM_NODE = "{http://www.jcp.org/jcr/1.0}system";
/**
* A constant for the absolute path of the system node.
*
* @since JCR 2.0
*/
public static final String PATH_SYSTEM_NODE = "/" + NAME_SYSTEM_NODE;
/**
* A constant for the name of the node type definition storage node.
*
* @since JCR 2.0
*/
public static final String NAME_NODE_TYPES_NODE = "{http://www.jcp.org/jcr/1.0}nodeTypes";
/**
* A constant for the absolute path of the node type definition storage
* node.
*
* @since JCR 2.0
*/
public static final String PATH_NODE_TYPES_NODE = PATH_SYSTEM_NODE + "/" + NAME_NODE_TYPES_NODE;
/**
* A constant for the name of the version storage node.
*
* @since JCR 2.0
*/
public static final String NAME_VERSION_STORAGE_NODE = "{http://www.jcp.org/jcr/1.0}versionStorage";
/**
* A constant for the absolute path of the version storage node.
*
* @since JCR 2.0
*/
public static final String PATH_VERSION_STORAGE_NODE = PATH_SYSTEM_NODE + "/" + NAME_VERSION_STORAGE_NODE;
/**
* A constant for the name of the activities node.
*
* @since JCR 2.0
*/
public static final String NAME_ACTIVITIES_NODE = "{http://www.jcp.org/jcr/1.0}activities";
/**
* A constant for the absolute path of the activities node.
*
* @since JCR 2.0
*/
public static final String PATH_ACTIVITIES_NODE = PATH_SYSTEM_NODE + "/" + NAME_ACTIVITIES_NODE;
/**
* A constant for the name of the configurations node.
*
* @since JCR 2.0
*/
public static final String NAME_CONFIGURATIONS_NODE = "{http://www.jcp.org/jcr/1.0}configurations";
/**
* A constant for the absolute path of the configurations node.
*
* @since JCR 2.0
*/
public static final String PATH_CONFIGURATIONS_NODE = PATH_SYSTEM_NODE + "/" + NAME_CONFIGURATIONS_NODE;
/**
* A constant for the name of the unfiled storage node.
*
* @since JCR 2.0
*/
public static final String NAME_UNFILED_NODE = "{http://www.jcp.org/jcr/1.0}unfiled";
/**
* A constant for the absolute path of the unfiled storage node.
*
* @since JCR 2.0
*/
public static final String PATH_UNFILED_NODE = PATH_SYSTEM_NODE + "/" + NAME_UNFILED_NODE;
/**
* A constant for the name of the jcr:xmltext node produced on
* {@link #importXML}.
*
* @since JCR 2.0
*/
public static final String NAME_JCR_XMLTEXT = "{http://www.jcp.org/jcr/1.0}xmltext";
/**
* A constant for the name of the jcr:xmlcharacters property
* produced on {@link #importXML}.
*
* @since JCR 2.0
*/
public static final String NAME_JCR_XMLCHARACTERS = "{http://www.jcp.org/jcr/1.0}xmlcharacters";
/**
* A constant for the relative path from the node representing the imported
* XML element of the jcr:xmlcharacters property produced on
* {@link #importXML}.
*
* @since JCR 2.0
*/
public static final String RELPATH_JCR_XMLCHARACTERS = NAME_JCR_XMLTEXT + "/" + NAME_JCR_XMLCHARACTERS;
/**
* Returns the Session object through which this
* Workspace object was acquired.
*
* @return a {@link Session} object.
*/
public Session getSession();
/**
* Returns the name of the actual persistent workspace represented by this
* Workspace object. This the name used in
* Repository.login.
*
* @return the name of this workspace.
*/
public String getName();
/**
* This method copies the subgraph rooted at, and including, the node at
* srcAbsPath to the new location at destAbsPath.
*
* This is a workspace-write operation and therefore dispatches changes
* immediately and does not require a save.
*
* When a node N is copied to a path location where no node
* currently exists, a new node N' is created at that location.
* The subgraph rooted at and including N' (call it S')
* is created and is identical to the subgraph rooted at and including N
* (call it S) with the following exceptions:
*
* - Every node in
S' is given a new and distinct identifier.
* - The repository may automatically drop any mixin node type
T
* present on any node M in S. Dropping a mixin node type
* in this context means that while M remains unchanged, its copy
* M' will lack the mixin T and any child nodes and properties
* defined by T that are present on M. For example, a node
* M that is mix:versionable may be copied such that the
* resulting node M' will be a copy of N except that
* M' will not be mix:versionable and will not have any of the
* properties defined by mix:versionable. In order for a mixin node type to
* be dropped it must be listed by name in the jcr:mixinTypes property of
* M. The resulting jcr:mixinTypes property of M'
* will reflect any change.
* - If a node
M in S is referenceable and its
* mix:referenceable mixin is not dropped on copy, then the resulting
* jcr:uuid property of M' will reflect the new identifier
* assigned to M'.
* - Each
REFERENCE or WEAKEREFERENCE property R
* in S is copied to its new location R' in S'.
* If R references a node M within S then the value
* of R' will be the identifier of M', the new copy of
* M, thus preserving the reference within the subgraph.
*
* When a node N is copied to a location where a node N' already
* exists, the repository may either immediately throw an ItemExistsException
* or attempt to update the node N' by selectively replacing part of its subgraph
* with a copy of the relevant part of the subgraph of N. If the node types of
* N and N' are compatible, the implementation supports update-on-copy
* for these node types and no other errors occur, then the copy will succeed. Otherwise an
* ItemExistsException is thrown.
*
* Which node types can be updated on copy and the details of any such updates are
* implementation-dependent. For example, some implementations may support update-on-copy
* for mix:versionable nodes. In such a case the versioning-related properties
* of the target node would remain unchanged (jcr:uuid,
* jcr:versionHistory, etc.) while the substantive content part of the subgraph
* would be replaced with that of the source node.
*
* The destAbsPath provided must not have an index on its final
* element. If it does then a RepositoryException is thrown.
* Strictly speaking, the destAbsPath parameter is actually an
* absolute path to the parent node of the new location, appended
* with the new name desired for the copied node. It does not specify
* a position within the child node ordering. If ordering is supported by
* the node type of the parent node of the new location, then the new copy
* of the node is appended to the end of the child node list.
*
* This method cannot be used to copy an individual property by itself. It
* copies an entire node and its subgraph.
*
* @param srcAbsPath the path of the node to be copied.
* @param destAbsPath the location to which the node at
* srcAbsPath is to be copied.
* @throws ConstraintViolationException if the operation would violate a
* node-type or other implementation-specific constraint.
* @throws VersionException if the parent node of destAbsPath
* is read-only due to a checked-in node.
* @throws AccessDeniedException if the current session does not have
* sufficent access to complete the operation.
* @throws PathNotFoundException if the node at srcAbsPath or
* the parent of destAbsPath does not exist.
* @throws ItemExistsException if a node already exists at
* destAbsPath and either same-name siblings are not allowed or
* update on copy is not supported for the nodes involved.
* @throws LockException if a lock prevents the copy.
* @throws RepositoryException if the last element of
* destAbsPath has an index or if another error occurs.
*/
public void copy(String srcAbsPath, String destAbsPath) throws ConstraintViolationException, VersionException, AccessDeniedException, PathNotFoundException, ItemExistsException, LockException, RepositoryException;
/**
* This method copies the subgraph at srcAbsPath in
* srcWorkspace to destAbsPath in
* this workspace.
*
* When a node N is copied to a path location where no node
* currently exists, a new node N' is created at that location.
* The subgraph rooted at and including N' (call it S')
* is created and is identical to the subgraph rooted at and including N
* (call it S) with the following exceptions:
*
* - Every referenceable node in
S' is given a new and distinct identifier
* while every non-referenceable node in S' may be given a new and
* distinct identifier.
* - The repository may automatically drop any mixin node type
T
* present on any node M in S. Dropping a mixin node type
* in this context means that while M remains unchanged, its copy
* M' will lack the mixin T and any child nodes and properties
* defined by T that are present on M. For example, a node
* M that is mix:versionable may be copied such that the
* resulting node M' will be a copy of N except that
* M' will not be mix:versionable and will not have any of the
* properties defined by mix:versionable. In order for a mixin node type to
* be dropped it must be listed by name in the jcr:mixinTypes property of
* M. The resulting jcr:mixinTypes property of M'
* will reflect any change.
* - If a node
M in S is referenceable and its
* mix:referenceable mixin is not dropped on copy, then the resulting
* jcr:uuid property of M' will reflect the new identifier
* assigned to M'.
* - Each
REFERENCE or WEAKEREFERENCE property R
* in S is copied to its new location R' in S'.
* If R references a node M within S then the value
* of R' will be the identifier of M', the new copy of
* M, thus preserving the reference within the subgraph.
*
* When a node N is copied to a location where a node N' already
* exists, the repository may either immediately throw an ItemExistsException
* or attempt to update the node N' by selectively replacing part of its subgraph
* with a copy of the relevant part of the subgraph of N. If the node types of
* N and N' are compatible, the implementation supports update-on-copy
* for these node types and no other errors occur, then the copy will succeed. Otherwise an
* ItemExistsException is thrown.
*
* Which node types can be updated on copy and the details of any such updates are
* implementation-dependent. For example, some implementations may support update-on-copy
* for mix:versionable nodes. In such a case the versioning-related properties
* of the target node would remain unchanged (jcr:uuid,
* jcr:versionHistory, etc.) while the substantive content part of the subgraph
* would be replaced with that of the source node.
*
* The destAbsPath provided must not have an index on its final
* element. If it does then a RepositoryException is thrown.
* Strictly speaking, the destAbsPath parameter is actually an
* absolute path to the parent node of the new location, appended
* with the new name desired for the copied node. It does not specify
* a position within the child node ordering. If ordering is supported by
* the node type of the parent node of the new location, then the new copy
* of the node is appended to the end of the child node list.
*
* This method cannot be used to copy just an individual property by itself.
* It copies an entire node and its subgraph (including, of course, any
* properties contained therein).
*
* @param srcWorkspace the name of the workspace from which the copy is to
* be made.
* @param srcAbsPath the path of the node to be copied.
* @param destAbsPath the location to which the node at
* srcAbsPath is to be copied in this workspace.
* @throws NoSuchWorkspaceException if srcWorkspace does not
* exist or if the current Session does not have permission to
* access it.
* @throws ConstraintViolationException if the operation would violate a
* node-type or other implementation-specific constraint
* @throws VersionException if the parent node of destAbsPath
* is read-only due to a checked-in node.
* @throws AccessDeniedException if the current session does have access to
* srcWorkspace but otherwise does not have sufficient access
* to complete the operation.
* @throws PathNotFoundException if the node at srcAbsPath in
* srcWorkspace or the parent of destAbsPath in
* this workspace does not exist.
* @throws ItemExistsException if a node already exists at
* destAbsPath and either same-name siblings are not allowed or
* update on copy is not supported for the nodes involved.
* @throws LockException if a lock prevents the copy.
* @throws RepositoryException if the last element of
* destAbsPath has an index or if another error occurs.
*/
public void copy(String srcWorkspace, String srcAbsPath, String destAbsPath) throws NoSuchWorkspaceException, ConstraintViolationException, VersionException, AccessDeniedException, PathNotFoundException, ItemExistsException, LockException, RepositoryException;
/**
* Clones the subgraph at the node srcAbsPath in
* srcWorkspace to the new location at destAbsPath
* in this workspace.
*
* Unlike the signature of copy that copies between workspaces,
* this method does not assign new identifiers to the newly cloned
* nodes but preserves the identifiers of their respective source nodes.
* This applies to both referenceable and non-referenceable nodes.
*
* In some implementations there may be cases where preservation of a
* non-referenceable identifier is not possible, due to how
* non-referenceable identifiers are constructed in that implementation. In
* such a case this method will throw a RepositoryException.
*
* If removeExisting is true and an existing node in this
* workspace (the destination workspace) has the same identifier as a node
* being cloned from srcWorkspace, then the incoming node takes
* precedence, and the existing node (and its subgraph) is removed. If
* removeExisting is false then an identifier collision causes
* this method to throw a ItemExistsException and no changes
* are made.
*
* If successful, the change is persisted immediately, there is no need to
* call save.
*
* The destAbsPath provided must not have an index on its final
* element. If it does then a RepositoryException is thrown. If
* ordering is supported by the node type of the parent node of the new
* location, then the new clone of the node is appended to the end of the
* child node list.
*
* This method cannot be used to clone just an individual property; it
* clones an node and its subgraph.
*
* @param srcWorkspace The name of the workspace from which the node is to
* be copied.
* @param srcAbsPath the path of the node to be copied in
* srcWorkspace.
* @param destAbsPath the location to which the node at
* srcAbsPath is to be copied in this workspace.
* @param removeExisting if false then this method throws an
* ItemExistsException on identifier conflict with an incoming
* node. If true then a identifier conflict is resolved by
* removing the existing node from its location in this workspace and
* cloning (copying in) the one from srcWorkspace.
* @throws NoSuchWorkspaceException if destWorkspace does not
* exist.
* @throws ConstraintViolationException if the operation would violate a
* node-type or other implementation-specific constraint.
* @throws VersionException if the parent node of destAbsPath
* is read-only due to a checked-in node. This exception will also be thrown
* if removeExisting is true, and an identifier
* conflict occurs that would require the moving and/or altering of a node
* that is checked-in.
* @throws AccessDeniedException if the current session does not have
* sufficient access to complete the operation.
* @throws PathNotFoundException if the node at srcAbsPath in
* srcWorkspace or the parent of destAbsPath in
* this workspace does not exist.
* @throws ItemExistsException if a node already exists at
* destAbsPath and same-name siblings are not allowed or if
* removeExisting is false and an identifier
* conflict occurs.
* @throws LockException if a lock prevents the clone.
* @throws RepositoryException if the last element of
* destAbsPath has an index or if another error occurs.
*/
public void clone(String srcWorkspace, String srcAbsPath, String destAbsPath, boolean removeExisting) throws NoSuchWorkspaceException, ConstraintViolationException, VersionException, AccessDeniedException, PathNotFoundException, ItemExistsException, LockException, RepositoryException;
/**
* Moves the node at srcAbsPath (and its entire subgraph) to
* the new location at destAbsPath.
*
* If successful, the change is persisted immediately, there is no need to
* call save. Note that this is in contrast to {@link
* Session#move} which operates within the transient space and hence
* requires a save.
*
* The identifiers of referenceable nodes must not be changed by a
* move. The identifiers of non-referenceable nodes may
* change.
*
* The destAbsPath provided must not have an index on its final
* element. If it does then a RepositoryException is thrown.
* Strictly speaking, the destAbsPath parameter is actually an
* absolute path to the parent node of the new location, appended
* with the new name desired for the moved node. It does not specify
* a position within the child node ordering. If ordering is supported by
* the node type of the parent node of the new location, then the newly
* moved node is appended to the end of the child node list.
*
* This method cannot be used to move just an individual property by itself.
* It moves an entire node and its subgraph (including, of course, any
* properties contained therein).
*
* The identifiers of referenceable nodes must not be changed by a
* move. The identifiers of non-referenceable nodes may
* change.
*
* A ConstraintViolationException is thrown if the operation
* would violate a node-type or other implementation-specific constraint.
*
* A VersionException is thrown if the parent node of
* destAbsPath or the parent node of srcAbsPath is
* versionable and checked-in, or is non-versionable but its nearest
* versionable ancestor is checked-in.
*
* An AccessDeniedException is thrown if the current session
* (i.e. the session that was used to acquire this Workspace
* object) does not have sufficient access rights to complete the
* operation.
*
* A PathNotFoundException is thrown if the node at
* srcAbsPath or the parent of destAbsPath does
* not exist.
*
* An ItemExistException is thrown if a node already exists at
* destAbsPath and same-name siblings are not allowed.
*
* Note that if a property already exists at destAbsPath, the
* operation succeeds, since a node may have a child node and property with
* the same name
*
* A LockException if a lock prevents the move.
*
* @param srcAbsPath the path of the node to be moved.
* @param destAbsPath the location to which the node at
* srcAbsPath is to be moved.
* @throws ConstraintViolationException if the operation would violate a
* node-type or other implementation-specific constraint
* @throws VersionException if the parent node of destAbsPath
* is read-only due to a checked-in node.
* @throws AccessDeniedException if the current session does not have
* sufficient access to complete the operation.
* @throws PathNotFoundException if the node at srcAbsPath or
* the parent of destAbsPath does not exist.
* @throws ItemExistsException if a node already exists at
* destAbsPath and same-name siblings are not allowed.
* @throws LockException if a lock prevents the move.
* @throws RepositoryException if the last element of
* destAbsPath has an index or if another error occurs.
*/
public void move(String srcAbsPath, String destAbsPath) throws ConstraintViolationException, VersionException, AccessDeniedException, PathNotFoundException, ItemExistsException, LockException, RepositoryException;
/**
* Restores a set of versions at once. Used in cases where a "chicken and
* egg" problem of mutually referring REFERENCE properties
* would prevent the restore in any serial order.
*
* If the restore succeeds the changes made to this node are
* persisted immediately, there is no need to call save.
*
* The following restrictions apply to the set of versions specified:
*
* If S is the set of versions being restored simultaneously,
*
- For every version
V in S that
* corresponds to a missing node, there must also be a parent of V in
* S. -
S must contain at least one version that
* corresponds to an existing node in the workspace. - No
*
V in S can be a root version
* (jcr:rootVersion).
If any of these restrictions
* does not hold, the restore will fail because the system will be unable to
* determine the path locations to which one or more versions are to be
* restored. In this case a VersionException is thrown.
*
* The versionable nodes in this workspace that correspond to the versions
* being restored define a set of (one or more) subgraphs. An identifier
* collision occurs when this workspace contains a node outside these
* subgraphs that has the same identifier as one of the nodes that would
* be introduced by the restore operation into one of these
* subgraphs. The result in such a case is governed by the
* removeExisting flag. If removeExisting is
* true then the incoming node takes precedence, and the
* existing node (and its subgraph) is removed. If removeExisting
* is false then a ItemExistsException is thrown
* and no changes are made. Note that this applies not only to cases where
* the restored node itself conflicts with an existing node but also to
* cases where a conflict occurs with any node that would be introduced into
* the workspace by the restore operation. In particular, conflicts
* involving subnodes of the restored node that have
* OnParentVersion settings of COPY or
* VERSION are also governed by the removeExisting
* flag.
*
* @param versions The set of versions to be restored
* @param removeExisting governs what happens on identifier collision.
* @throws ItemExistsException if removeExisting is
* false and an identifier collision occurs with a node being
* restored.
* @throws UnsupportedRepositoryOperationException
* if one or more of the
* nodes to be restored is not versionable.
* @throws VersionException if the set of versions to be restored is such
* that the original path location of one or more of the versions cannot be
* determined or if the restore would change the state of a
* existing versionable node that is currently checked-in or if a root
* version (jcr:rootVersion) is among those being restored.
* @throws LockException if a lock prevents the restore.
* @throws InvalidItemStateException if this Session has
* pending unsaved changes.
* @throws RepositoryException if another error occurs.
* @deprecated As of JCR 2.0, {@link javax.jcr.version.VersionManager#restore}
* should be used instead.
*/
public void restore(Version[] versions, boolean removeExisting) throws ItemExistsException, UnsupportedRepositoryOperationException, VersionException, LockException, InvalidItemStateException, RepositoryException;
/**
* Returns the LockManager object, through which locking
* methods are accessed.
*
* @return the LockManager object.
* @throws UnsupportedRepositoryOperationException
* if the implementation
* does not support locking.
* @throws RepositoryException if an error occurs.
* @since JCR 2.0
*/
public LockManager getLockManager() throws UnsupportedRepositoryOperationException, RepositoryException;
/**
* Returns the QueryManager object, through search methods are
* accessed.
*
* @return the QueryManager object.
* @throws RepositoryException if an error occurs.
*/
public QueryManager getQueryManager() throws RepositoryException;
/**
* Returns the NamespaceRegistry object, which is used to
* access the mapping between prefixes and namespaces. In level 2
* repositories the NamespaceRegistry can also be used to
* change the namespace mappings.
*
* @return the NamespaceRegistry.
* @throws RepositoryException if an error occurs.
*/
public NamespaceRegistry getNamespaceRegistry() throws RepositoryException;
/**
* Returns the NodeTypeManager through which node type
* information can be queried. There is one node type registry per
* repository, therefore the NodeTypeManager is not
* workspace-specific; it provides introspection methods for the global,
* repository-wide set of available node types. In repositories that support
* it, the NodeTypeManager can also be used to register new
* node types.
*
* @return a NodeTypeManager object.
* @throws RepositoryException if an error occurs.
*/
public NodeTypeManager getNodeTypeManager() throws RepositoryException;
/**
* Returns the ObservationManager object.
*
* @return an ObservationManager object.
* @throws UnsupportedRepositoryOperationException
* if the implementation
* does not support observation.
* @throws RepositoryException if an error occurs.
*/
public ObservationManager getObservationManager() throws UnsupportedRepositoryOperationException, RepositoryException;
/**
* Returns the VersionManager object.
*
* @return an VersionManager object.
* @throws UnsupportedRepositoryOperationException
* if the implementation
* does not support versioning.
* @throws RepositoryException if an error occurs.
* @since JCR 2.0
*/
public VersionManager getVersionManager() throws UnsupportedRepositoryOperationException, RepositoryException;
/**
* Returns a string array containing the names of all workspaces in this
* repository that are accessible to this user, given the
* Credentials that were used to get the Session
* to which this Workspace is tied.
*
* In order to access one of the listed workspaces, the user performs
* another {@link Repository#login}, specifying the name of the desired
* workspace, and receives a new Session object.
*
* @return string array of names of accessible workspaces.
* @throws RepositoryException if an error occurs
*/
public String[] getAccessibleWorkspaceNames() throws RepositoryException;
/**
* Returns an org.xml.sax.ContentHandler which can be used to
* push SAX events into the repository. If the incoming XML stream (in the
* form of SAX events) does not appear to be a JCR system view XML document
* then it is interpreted as a document view XML document.
*
* The incoming XML is deserialized into a subgraph of items immediately
* below the node at parentAbsPath.
*
* This method simply returns the ContentHandler without
* altering the state of the repository; the actual deserialization is done
* through the methods of the ContentHandler. Invalid XML data
* will cause the ContentHandler to throw a
* SAXException.
*
* As SAX events are fed into the ContentHandler, changes are
* made directly at the workspace level, without going through the
* Session. As a result, there is not need to call
* save. The advantage of this direct-to-workspace method is
* that a large import will not result in a large cache of pending nodes in
* the Session. The disadvantage is that structures that
* violate node type constraints cannot be imported, fixed and then saved.
* Instead, a constraint violation will cause the ContentHandler
* to throw a SAXException. See Session.getImportContentHandler
* for a version of this method that does go through the
* Session.
*
* The flag uuidBehavior governs how the identifiers of
* incoming (deserialized) nodes are handled. There are four options:
* - {@link ImportUUIDBehavior#IMPORT_UUID_CREATE_NEW}: Incoming nodes are
* assigned newly created identifiers upon addition to the workspace. As a
* result identifier collisions never occur.
- {@link
* ImportUUIDBehavior#IMPORT_UUID_COLLISION_REMOVE_EXISTING}: If an incoming
* node has the same identifier as a node already existing in the workspace,
* then the already existing node (and its subgraph) is removed from
* wherever it may be in the workspace before the incoming node is added.
* Note that this can result in nodes "disappearing" from locations in the
* workspace that are remote from the location to which the incoming
* subgraph is being written.
- {@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_REPLACE_EXISTING}:
* If an incoming node has the same identifier as a node already existing in
* the workspace then the already existing node is replaced by the incoming
* node in the same position as the existing node. Note that this may result
* in the incoming subgraph being disaggregated and "spread around" to
* different locations in the workspace. In the most extreme case this
* behavior may result in no node at all being added as child of
*
parentAbsPath. This will occur if the topmost element of the
* incoming XML has the same identifier as an existing node elsewhere in the
* workspace. - {@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_THROW}: If
* an incoming node has the same identifier as a node already existing in
* the workspace then a
SAXException is thrown by the returned
* ContentHandler during deserialization.
A
* SAXException will be thrown by the returned
* ContentHandler during deserialization if the top-most
* element of the incoming XML would deserialize to a node with the same
* name as an existing child of parentAbsPath and that child
* does not allow same-name siblings.
*
* A SAXException will also be thrown by the returned
* ContentHandler during deserialization if
* uuidBehavior is set to IMPORT_UUID_COLLISION_REMOVE_EXISTING
* and an incoming node has the same identifier as the node at
* parentAbsPath or one of its ancestors.
*
* @param parentAbsPath the absolute path of a node under which (as child)
* the imported subgraph will be built.
* @param uuidBehavior a four-value flag that governs how incoming
* identifiers are handled.
* @return an org.xml.sax.ContentHandler whose methods may be called to feed
* SAX events into the deserializer.
* @throws PathNotFoundException if no node exists at
* parentAbsPath.
* @throws ConstraintViolationException if the new subgraph cannot be added
* to the node at parentAbsPath due to node-type or other
* implementation-specific constraints, and this can be determined before
* the first SAX event is sent. Unlike {@link Session#getImportContentHandler},
* this method also enforces node type constraints by throwing
* SAXExceptions during deserialization. However, which node
* type constraints are enforced depends upon whether node type information
* in the imported data is respected, and this is an implementation-specific
* issue.
* @throws VersionException if the node at parentAbsPath is
* read-only due to a checked-in node.
* @throws LockException if a lock prevents the addition of the subgraph.
* @throws AccessDeniedException if the session associated with this
* Workspace object does not have sufficient access to perform
* the import.
* @throws RepositoryException if another error occurs.
*/
public ContentHandler getImportContentHandler(String parentAbsPath, int uuidBehavior) throws PathNotFoundException, ConstraintViolationException, VersionException, LockException, AccessDeniedException, RepositoryException;
/**
* Deserializes an XML document and adds the resulting item subgraph as a
* child of the node at parentAbsPath.
*
* If the incoming XML stream does not appear to be a JCR system view XML
* document then it is interpreted as a document view XML document.
*
* The passed InputStream is closed before this method returns
* either normally or because of an exception.
*
* Changes are made directly at the workspace level, without going through
* the Session. As a result, there is not need to call
* save. The advantage of this direct-to-workspace method is
* that a large import will not result in a large cache of pending nodes in
* the Session. The disadvantage is that invalid data cannot be
* imported, fixed and then saved. Instead, invalid data will cause this
* method to throw an InvalidSerializedDataException. See
* Session.importXML for a version of this method that
* does go through the Session.
*
* The flag uuidBehavior governs how the identifiers of
* incoming (deserialized) nodes are handled. There are four options:
* - {@link ImportUUIDBehavior#IMPORT_UUID_CREATE_NEW}: Incoming nodes are
* assigned newly created identifiers upon addition to the workspace. As a
* result identifier collisions never occur.
- {@link
* ImportUUIDBehavior#IMPORT_UUID_COLLISION_REMOVE_EXISTING}: If an incoming
* node has the same identifier as a node already existing in the workspace
* then the already existing node (and its subgraph) is removed from
* wherever it may be in the workspace before the incoming node is added.
* Note that this can result in nodes "disappearing" from locations in the
* workspace that are remote from the location to which the incoming
* subgraph is being written. If an incoming node has the same identifier as
* the existing root node of this workspace then
- {@link
* ImportUUIDBehavior#IMPORT_UUID_COLLISION_REPLACE_EXISTING}: If an
* incoming node has the same identifier as a node already existing in the
* workspace then the already existing node is replaced by the incoming node
* in the same position as the existing node. Note that this may result in
* the incoming subgraph being disaggregated and "spread around" to
* different locations in the workspace. In the most extreme edge case this
* behavior may result in no node at all being added as child of
*
parentAbsPath. This will occur if the topmost element of the
* incoming XML has the same identifier as an existing node elsewhere in the
* workspace. - {@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_THROW}: If
* an incoming node has the same identifier as a node already existing in
* the workspace then an
ItemExistsException is thrown.
* An ItemExistsException will be thrown if the top-most
* element of the incoming XML would deserialize to a node with the same
* name as an existing child of parentAbsPath and that child
* does not allow same-name siblings.
*
* @param parentAbsPath the absolute path of the node below which the
* deserialized subgraph is added.
* @param in The Inputstream from which the XML to be
* deserialized is read.
* @param uuidBehavior a four-value flag that governs how incoming
* identifiers are handled.
* @throws java.io.IOException if an error during an I/O operation occurs.
* @throws PathNotFoundException if no node exists at
* parentAbsPath.
* @throws ConstraintViolationException if node-type or other
* implementation-specific constraints prevent the addition of the subgraph
* or if uuidBehavior is set to IMPORT_UUID_COLLISION_REMOVE_EXISTING
* and an incoming node has the same identifier as the node at
* parentAbsPath or one of its ancestors.
* @throws VersionException if the node at parentAbsPath is
* read-only due to a checked-in node..
* @throws InvalidSerializedDataException if incoming stream is not a valid
* XML document.
* @throws ItemExistsException if the top-most element of the incoming XML
* would deserialize to a node with the same name as an existing child of
* parentAbsPath and that child does not allow same-name
* siblings, or if a uuidBehavior is set to
* IMPORT_UUID_COLLISION_THROW and an identifier collision
* occurs.
* @throws LockException if a lock prevents the addition of the subgraph.
* @throws AccessDeniedException if the session associated with this
* Workspace object does not have sufficient access to perform
* the import.
* @throws RepositoryException if another error occurs.
*/
public void importXML(String parentAbsPath, InputStream in, int uuidBehavior) throws IOException, VersionException, PathNotFoundException, ItemExistsException, ConstraintViolationException, InvalidSerializedDataException, LockException, AccessDeniedException, RepositoryException;
/**
* Creates a new Workspace with the specified
* name. The new workspace is empty, meaning it contains only
* root node.
*
* The new workspace can be accessed through a login specifying
* its name.
*
* @param name A String, the name of the new workspace.
* @throws AccessDeniedException if the session through which this
* Workspace object was acquired does not have permission to
* create the new workspace.
* @throws UnsupportedRepositoryOperationException
* if the repository does
* not support the creation of workspaces.
* @throws RepositoryException if another error occurs.
* @since JCR 2.0
*/
public void createWorkspace(String name) throws AccessDeniedException, UnsupportedRepositoryOperationException, RepositoryException;
/**
* Creates a new Workspace with the specified name
* initialized with a clone of the content of the workspace
* srcWorkspace. Semantically, this method is equivalent to
* creating a new workspace and manually cloning srcWorkspace
* to it; however, this method may assist some implementations in optimizing
* subsequent Node.update and Node.merge calls
* between the new workspace and its source.
*
* The new workspace can be accessed through a login specifying
* its name.
*
* @param name A String, the name of the new workspace.
* @param srcWorkspace The name of the workspace from which the new
* workspace is to be cloned.
* @throws AccessDeniedException if the session through which this
* Workspace object was acquired does not have sufficient
* access to create the new workspace.
* @throws UnsupportedRepositoryOperationException
* if the repository does
* not support the creation of workspaces.
* @throws NoSuchWorkspaceException is srcWorkspace does not
* exist.
* @throws RepositoryException if another error occurs.
* @since JCR 2.0
*/
public void createWorkspace(String name, String srcWorkspace)
throws AccessDeniedException, UnsupportedRepositoryOperationException, NoSuchWorkspaceException, RepositoryException;
/**
* Deletes the workspace with the specified name from the
* repository, deleting all content within it.
*
* @param name A String, the name of the workspace to be
* deleted.
* @throws AccessDeniedException if the session through which this
* Workspace object was acquired does not have sufficent access
* to remove the workspace.
* @throws UnsupportedRepositoryOperationException
* if the repository does
* not support the removal of workspaces.
* @throws NoSuchWorkspaceException is srcWorkspace does not
* exist.
* @throws RepositoryException if another error occurs.
* @since JCR 2.0
*/
public void deleteWorkspace(String name) throws AccessDeniedException, UnsupportedRepositoryOperationException, NoSuchWorkspaceException, RepositoryException;
}