Package javax.jcr

Interface Workspace

  • All Known Subinterfaces:
    JackrabbitWorkspace
    All Known Implementing Classes:
    AbstractWorkspace
    public interface Workspace
    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 Session.getWorkspace() on the associated Session object.

    • Method Summary

      All Methods Instance Methods Abstract Methods Deprecated Methods 
      Modifier and Type Method Description
      void clone​(java.lang.String srcWorkspace, java.lang.String srcAbsPath, java.lang.String destAbsPath, boolean removeExisting)
      Clones the subgraph at the node srcAbsPath in srcWorkspace to the new location at destAbsPath in this workspace.
      void copy​(java.lang.String srcAbsPath, java.lang.String destAbsPath)
      This method copies the subgraph rooted at, and including, the node at srcAbsPath to the new location at destAbsPath.
      void copy​(java.lang.String srcWorkspace, java.lang.String srcAbsPath, java.lang.String destAbsPath)
      This method copies the subgraph at srcAbsPath in srcWorkspace to destAbsPath in this workspace.
      void createWorkspace​(java.lang.String name)
      Creates a new Workspace with the specified name.
      void createWorkspace​(java.lang.String name, java.lang.String srcWorkspace)
      Creates a new Workspace with the specified name initialized with a clone of the content of the workspace srcWorkspace.
      void deleteWorkspace​(java.lang.String name)
      Deletes the workspace with the specified name from the repository, deleting all content within it.
      java.lang.String[] getAccessibleWorkspaceNames()
      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.
      org.xml.sax.ContentHandler getImportContentHandler​(java.lang.String parentAbsPath, int uuidBehavior)
      Returns an org.xml.sax.ContentHandler which can be used to push SAX events into the repository.
      LockManager getLockManager()
      Returns the LockManager object, through which locking methods are accessed.
      java.lang.String getName()
      Returns the name of the actual persistent workspace represented by this Workspace object.
      NamespaceRegistry getNamespaceRegistry()
      Returns the NamespaceRegistry object, which is used to access the mapping between prefixes and namespaces.
      NodeTypeManager getNodeTypeManager()
      Returns the NodeTypeManager through which node type information can be queried.
      ObservationManager getObservationManager()
      Returns the ObservationManager object.
      QueryManager getQueryManager()
      Returns the QueryManager object, through search methods are accessed.
      Session getSession()
      Returns the Session object through which this Workspace object was acquired.
      VersionManager getVersionManager()
      Returns the VersionManager object.
      void importXML​(java.lang.String parentAbsPath, java.io.InputStream in, int uuidBehavior)
      Deserializes an XML document and adds the resulting item subgraph as a child of the node at parentAbsPath.
      void move​(java.lang.String srcAbsPath, java.lang.String destAbsPath)
      Moves the node at srcAbsPath (and its entire subgraph) to the new location at destAbsPath.
      void restore​(Version[] versions, boolean removeExisting)
      Deprecated.
      As of JCR 2.0, VersionManager.restore(javax.jcr.version.Version[], boolean) should be used instead.

    • Field Detail

      • NAME_WORKSPACE_ROOT

        static final java.lang.String NAME_WORKSPACE_ROOT
        A constant for the name of the workspace root node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

      • PATH_WORKSPACE_ROOT

        static final java.lang.String PATH_WORKSPACE_ROOT
        A constant for the absolute path of the workspace root node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

      • NAME_SYSTEM_NODE

        static final java.lang.String NAME_SYSTEM_NODE
        A constant for the name of the system node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

      • PATH_SYSTEM_NODE

        static final java.lang.String PATH_SYSTEM_NODE
        A constant for the absolute path of the system node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

      • NAME_NODE_TYPES_NODE

        static final java.lang.String NAME_NODE_TYPES_NODE
        A constant for the name of the node type definition storage node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

      • PATH_NODE_TYPES_NODE

        static final java.lang.String PATH_NODE_TYPES_NODE
        A constant for the absolute path of the node type definition storage node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

      • NAME_VERSION_STORAGE_NODE

        static final java.lang.String NAME_VERSION_STORAGE_NODE
        A constant for the name of the version storage node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

      • PATH_VERSION_STORAGE_NODE

        static final java.lang.String PATH_VERSION_STORAGE_NODE
        A constant for the absolute path of the version storage node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

      • NAME_ACTIVITIES_NODE

        static final java.lang.String NAME_ACTIVITIES_NODE
        A constant for the name of the activities node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

      • PATH_ACTIVITIES_NODE

        static final java.lang.String PATH_ACTIVITIES_NODE
        A constant for the absolute path of the activities node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

      • NAME_CONFIGURATIONS_NODE

        static final java.lang.String NAME_CONFIGURATIONS_NODE
        A constant for the name of the configurations node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

      • PATH_CONFIGURATIONS_NODE

        static final java.lang.String PATH_CONFIGURATIONS_NODE
        A constant for the absolute path of the configurations node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

      • NAME_UNFILED_NODE

        static final java.lang.String NAME_UNFILED_NODE
        A constant for the name of the unfiled storage node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

      • PATH_UNFILED_NODE

        static final java.lang.String PATH_UNFILED_NODE
        A constant for the absolute path of the unfiled storage node.
        Since:
        JCR 2.0
        See Also:
        Constant Field Values

    • Method Detail

      • getSession

        Session getSession()
        Returns the Session object through which this Workspace object was acquired.
        Returns:
        a Session object.

      • getName

        java.lang.String getName()
        Returns the name of the actual persistent workspace represented by this Workspace object. This the name used in Repository.login.
        Returns:
        the name of this workspace.

      • copy

        void copy​(java.lang.String srcAbsPath,
          java.lang.String destAbsPath)
   throws ConstraintViolationException,
          VersionException,
          AccessDeniedException,
          PathNotFoundException,
          ItemExistsException,
          LockException,
          RepositoryException
        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.

        Parameters:
        srcAbsPath - the path of the node to be copied.
        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.
        VersionException - if the parent node of destAbsPath is read-only due to a checked-in node.
        AccessDeniedException - if the current session does not have sufficent access to complete the operation.
        PathNotFoundException - if the node at srcAbsPath or the parent of destAbsPath does not exist.
        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.
        LockException - if a lock prevents the copy.
        RepositoryException - if the last element of destAbsPath has an index or if another error occurs.

      • copy

        void copy​(java.lang.String srcWorkspace,
          java.lang.String srcAbsPath,
          java.lang.String destAbsPath)
   throws NoSuchWorkspaceException,
          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).

        Parameters:
        srcWorkspace - the name of the workspace from which the copy is to be made.
        srcAbsPath - the path of the node to be copied.
        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.
        ConstraintViolationException - if the operation would violate a node-type or other implementation-specific constraint
        VersionException - if the parent node of destAbsPath is read-only due to a checked-in node.
        AccessDeniedException - if the current session does have access to srcWorkspace but otherwise does not have sufficient access to complete the operation.
        PathNotFoundException - if the node at srcAbsPath in srcWorkspace or the parent of destAbsPath in this workspace does not exist.
        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.
        LockException - if a lock prevents the copy.
        RepositoryException - if the last element of destAbsPath has an index or if another error occurs.

      • clone

        void clone​(java.lang.String srcWorkspace,
           java.lang.String srcAbsPath,
           java.lang.String destAbsPath,
           boolean removeExisting)
    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.

        Parameters:
        srcWorkspace - The name of the workspace from which the node is to be copied.
        srcAbsPath - the path of the node to be copied in srcWorkspace.
        destAbsPath - the location to which the node at srcAbsPath is to be copied in this workspace.
        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.
        ConstraintViolationException - if the operation would violate a node-type or other implementation-specific constraint.
        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.
        AccessDeniedException - if the current session does not have sufficient access to complete the operation.
        PathNotFoundException - if the node at srcAbsPath in srcWorkspace or the parent of destAbsPath in this workspace does not exist.
        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.
        LockException - if a lock prevents the clone.
        RepositoryException - if the last element of destAbsPath has an index or if another error occurs.

      • move

        void move​(java.lang.String srcAbsPath,
          java.lang.String destAbsPath)
   throws 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 Session.move(java.lang.String, java.lang.String) 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.

        Parameters:
        srcAbsPath - the path of the node to be moved.
        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
        VersionException - if the parent node of destAbsPath is read-only due to a checked-in node.
        AccessDeniedException - if the current session does not have sufficient access to complete the operation.
        PathNotFoundException - if the node at srcAbsPath or the parent of destAbsPath does not exist.
        ItemExistsException - if a node already exists at destAbsPath and same-name siblings are not allowed.
        LockException - if a lock prevents the move.
        RepositoryException - if the last element of destAbsPath has an index or if another error occurs.

      • restore

        void restore​(Version[] versions,
             boolean removeExisting)
      throws ItemExistsException,
             UnsupportedRepositoryOperationException,
             VersionException,
             LockException,
             InvalidItemStateException,
             RepositoryException
        Deprecated.
        As of JCR 2.0, VersionManager.restore(javax.jcr.version.Version[], boolean) should be used instead.
        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.

        Parameters:
        versions - The set of versions to be restored
        removeExisting - governs what happens on identifier collision.
        Throws:
        ItemExistsException - if removeExisting is false and an identifier collision occurs with a node being restored.
        UnsupportedRepositoryOperationException - if one or more of the nodes to be restored is not versionable.
        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.
        LockException - if a lock prevents the restore.
        InvalidItemStateException - if this Session has pending unsaved changes.
        RepositoryException - if another error occurs.

      • getNamespaceRegistry

        NamespaceRegistry getNamespaceRegistry()
                                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.
        Returns:
        the NamespaceRegistry.
        Throws:
        RepositoryException - if an error occurs.

      • getNodeTypeManager

        NodeTypeManager getNodeTypeManager()
                            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.
        Returns:
        a NodeTypeManager object.
        Throws:
        RepositoryException - if an error occurs.

      • getAccessibleWorkspaceNames

        java.lang.String[] getAccessibleWorkspaceNames()
                                        throws 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 Repository.login(javax.jcr.Credentials, java.lang.String), specifying the name of the desired workspace, and receives a new Session object.

        Returns:
        string array of names of accessible workspaces.
        Throws:
        RepositoryException - if an error occurs

      • getImportContentHandler

        org.xml.sax.ContentHandler getImportContentHandler​(java.lang.String parentAbsPath,
                                                   int uuidBehavior)
                                            throws PathNotFoundException,
                                                   ConstraintViolationException,
                                                   VersionException,
                                                   LockException,
                                                   AccessDeniedException,
                                                   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:

        • ImportUUIDBehavior.IMPORT_UUID_CREATE_NEW: Incoming nodes are assigned newly created identifiers upon addition to the workspace. As a result identifier collisions never occur.
        • 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.
        • 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.
        • 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.

        Parameters:
        parentAbsPath - the absolute path of a node under which (as child) the imported subgraph will be built.
        uuidBehavior - a four-value flag that governs how incoming identifiers are handled.
        Returns:
        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.
        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 Session.getImportContentHandler(java.lang.String, int), 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.
        VersionException - if the node at parentAbsPath is read-only due to a checked-in node.
        LockException - if a lock prevents the addition of the subgraph.
        AccessDeniedException - if the session associated with this Workspace object does not have sufficient access to perform the import.
        RepositoryException - if another error occurs.

      • importXML

        void importXML​(java.lang.String parentAbsPath,
               java.io.InputStream in,
               int uuidBehavior)
        throws java.io.IOException,
               VersionException,
               PathNotFoundException,
               ItemExistsException,
               ConstraintViolationException,
               InvalidSerializedDataException,
               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:

        • ImportUUIDBehavior.IMPORT_UUID_CREATE_NEW: Incoming nodes are assigned newly created identifiers upon addition to the workspace. As a result identifier collisions never occur.
        • 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
        • 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.
        • 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.
        Parameters:
        parentAbsPath - the absolute path of the node below which the deserialized subgraph is added.
        in - The Inputstream from which the XML to be deserialized is read.
        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.
        PathNotFoundException - if no node exists at parentAbsPath.
        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.
        VersionException - if the node at parentAbsPath is read-only due to a checked-in node..
        InvalidSerializedDataException - if incoming stream is not a valid XML document.
        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.
        LockException - if a lock prevents the addition of the subgraph.
        AccessDeniedException - if the session associated with this Workspace object does not have sufficient access to perform the import.
        RepositoryException - if another error occurs.

      • createWorkspace

        void createWorkspace​(java.lang.String name,
                     java.lang.String srcWorkspace)
              throws AccessDeniedException,
                     UnsupportedRepositoryOperationException,
                     NoSuchWorkspaceException,
                     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.

        Parameters:
        name - A String, the name of the new workspace.
        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.
        UnsupportedRepositoryOperationException - if the repository does not support the creation of workspaces.
        NoSuchWorkspaceException - is srcWorkspace does not exist.
        RepositoryException - if another error occurs.
        Since:
        JCR 2.0