Package com.day.cq.commons.jcr

Class JcrUtil

  • public class JcrUtil
extends java.lang.Object
    Utility for common JCR tasks

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String[] HYPHEN_LABEL_CHAR_MAPPING
      the list of replacement string for non-valid jcr characters.
      static java.lang.String NON_VALID_CHARS
      Non-valid name characters.
      static java.lang.String[] STANDARD_LABEL_CHAR_MAPPING
      the list of replacement string for non-valid jcr characters.

    • Constructor Summary

      Constructors 
      Constructor Description
      JcrUtil()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static Item copy​(Item src, Node dstParent, java.lang.String name)
      Copy the src item into the dstParent node.
      static Node copy​(Node src, Node dstParent, java.lang.String name)
      Copy the src node into the dstParent node.
      static Node copy​(Node src, Node dstParent, java.lang.String name, boolean bestEffort)
      Copy the src node into the dstParent node.
      static Property copy​(Property src, Node dstParent, java.lang.String name)
      Copy the src property into the dstParent node.
      static int copyResource​(Session session, java.lang.String path, java.io.Writer out)
      Copies the contents of the resource to the given writer.
      static Node createPath​(java.lang.String absolutePath, boolean createUniqueLeaf, java.lang.String intermediateNodeType, java.lang.String nodeType, Session session, boolean autoSave)
      Creates or gets the Node at the given Path.
      static Node createPath​(java.lang.String absolutePath, java.lang.String intermediateNodeType, java.lang.String nodeType, Session session, boolean autoSave)
      Creates or gets the Node at the given Path.
      static Node createPath​(java.lang.String absolutePath, java.lang.String nodeType, Session session)
      Creates or gets the Node at the given Path.
      static Node createPath​(Node baseNode, java.lang.String path, boolean createUniqueLeaf, java.lang.String intermediateNodeType, java.lang.String nodeType, Session session, boolean autoSave)
      Creates or gets the Node at the given path relative to the baseNode.
      static Node createUniqueNode​(Node parent, java.lang.String nodeNameHint, java.lang.String nodeType, Session session)
      Creates or gets the Node at the given Path.
      static Node createUniquePath​(java.lang.String pathHint, java.lang.String nodeType, Session session)
      Creates a Node at the given Path.
      static java.lang.String createValidChildName​(Node node, java.lang.String name)
      Create a valid name for a child of the node.
      static java.lang.String createValidName​(java.lang.String title)
      Create a valid label out of an arbitrary string.
      static java.lang.String createValidName​(java.lang.String title, java.lang.String[] labelCharMapping)
      Create a valid label out of an arbitrary string with a custom character mapping.
      static java.lang.String createValidName​(java.lang.String title, java.lang.String[] labelCharMapping, java.lang.String defaultReplacementCharacter)
      Create a valid label out of an arbitrary string with a custom character mapping.
      static Value createValue​(java.lang.Object value, Session session)
      Creates a JCR Value for the given object with the given Session.
      static java.lang.String escapeIllegalJcrChars​(java.lang.String name)
      Escapes all illegal JCR name characters of a string.
      static boolean isValidName​(java.lang.String name)
      Checks if the name is not empty and contains only valid chars.
      static boolean setChildNodeOrder​(Node parent, java.lang.String nameList)
      Restores the odering of the nodes according to the given comma seperated name list.
      static boolean setChildNodeOrder​(Node parent, java.lang.String[] names)
      Restores the odering of the nodes according to the given name list.
      static void setProperty​(Node node, java.lang.String propertyName, java.lang.Object propertyValue)
      Sets the value of the property.
      static java.lang.String unescapeIllegalJcrChars​(java.lang.String name)
      Unescapes previously escaped jcr chars.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • STANDARD_LABEL_CHAR_MAPPING

        public static final java.lang.String[] STANDARD_LABEL_CHAR_MAPPING
        the list of replacement string for non-valid jcr characters. illegal characters are replaced by an underscore ("_").

      • HYPHEN_LABEL_CHAR_MAPPING

        public static final java.lang.String[] HYPHEN_LABEL_CHAR_MAPPING
        the list of replacement string for non-valid jcr characters. illegal characters are replaced by a hyphen ("-").

      • NON_VALID_CHARS

        public static final java.lang.String NON_VALID_CHARS
        Non-valid name characters.
        See Also:
        Constant Field Values

    • Constructor Detail

      • JcrUtil

        public JcrUtil()

    • Method Detail

      • escapeIllegalJcrChars

        public static java.lang.String escapeIllegalJcrChars​(java.lang.String name)
        Escapes all illegal JCR name characters of a string. The encoding is loosely modeled after URI encoding, but only encodes the characters it absolutely needs to in order to make the resulting string a valid JCR name. Use unescapeIllegalJcrChars(String) for decoding.

        QName EBNF:

         simplename ::= onecharsimplename | twocharsimplename | threeormorecharname
 onecharsimplename ::= (* Any Unicode character except: '.', '/', ':', '[', ']', '*', ''', '"', '|' or any whitespace character *)
 twocharsimplename ::= '.' onecharsimplename | onecharsimplename '.' | onecharsimplename onecharsimplename
 threeormorecharname ::= nonspace string nonspace
 string ::= char | string char
 char ::= nonspace | ' '
 nonspace ::= (* Any Unicode character except: '/', ':', '[', ']', '*', ''', '"', '|' or any whitespace character *)
        Parameters:
        name - the name to escape
        Returns:
        the escaped name

      • unescapeIllegalJcrChars

        public static java.lang.String unescapeIllegalJcrChars​(java.lang.String name)
        Unescapes previously escaped jcr chars.

        Please note, that this does not exactly the same as the url related Text.unescape(String), since it handles the byte-encoding differently.

        Parameters:
        name - the name to unescape
        Returns:
        the unescaped name

      • createPath

        public static Node createPath​(java.lang.String absolutePath,
                              java.lang.String nodeType,
                              Session session)
                       throws RepositoryException
        Creates or gets the Node at the given Path. In case it has to create the Node all non-existent intermediate path-elements will be created with the given NodeType.

        Changes made are not saved by this method, so session.save() has to be called to persist them.

        Parameters:
        absolutePath - absolute path to create
        nodeType - to use for creation of nodes
        session - to use
        Returns:
        the Node at path
        Throws:
        RepositoryException - in case of exception accessing the Repository

      • createPath

        public static Node createPath​(java.lang.String absolutePath,
                              java.lang.String intermediateNodeType,
                              java.lang.String nodeType,
                              Session session,
                              boolean autoSave)
                       throws RepositoryException
        Creates or gets the Node at the given Path. In case it has to create the Node all non-existent intermediate path-elements will be created with the given intermediate node type and the returned node will be created with the given nodeType.
        Parameters:
        absolutePath - absolute path to create
        intermediateNodeType - to use for creation of intermediate nodes
        nodeType - to use for creation of the final node
        session - to use
        autoSave - Should save be called when a new node is created?
        Returns:
        the Node at absolutePath
        Throws:
        RepositoryException - in case of exception accessing the Repository

      • createUniquePath

        public static Node createUniquePath​(java.lang.String pathHint,
                                    java.lang.String nodeType,
                                    Session session)
                             throws RepositoryException
        Creates a Node at the given Path. In case it has to create the Node all non-existent intermediate path-elements will be created with the given intermediate node type and the returned node will be created with the given nodeType.

        If the path points to an existing node, the leaf node name will be regarded as a name hint and a unique node name will be created by appending a number to the given name (eg. /some/path/foobar2). Please note that the uniqueness check is not an atomic JCR operation, so it is possible that you get a RepositoryException (path already exists) if another concurrent session created the same node in the meantime.

        Changes made are not saved by this method, so session.save() has to be called to persist them.

        Parameters:
        pathHint - path to create
        nodeType - to use for creation of nodes
        session - to use
        Returns:
        the newly created Node
        Throws:
        RepositoryException - in case of exception accessing the Repository

      • createPath

        public static Node createPath​(java.lang.String absolutePath,
                              boolean createUniqueLeaf,
                              java.lang.String intermediateNodeType,
                              java.lang.String nodeType,
                              Session session,
                              boolean autoSave)
                       throws RepositoryException
        Creates or gets the Node at the given Path. In case it has to create the Node all non-existent intermediate path-elements will be created with the given intermediate node type and the returned node will be created with the given nodeType.

        If the parameter createUniqueLeaf is set, it will not get an existing node but rather try to create a unique node by appending a number to the last path element (leaf node). Please note that the uniqueness check is not an atomic JCR operation, so it is possible that you get a RepositoryException (path already exists) if another concurrent session created the same node in the meantime.

        Parameters:
        absolutePath - absolute path to create
        createUniqueLeaf - whether the leaf of the path should be regarded as a name hint and a unique node name should be created by appending a number to the given name (eg. /some/path/foobar2)
        intermediateNodeType - to use for creation of intermediate nodes
        nodeType - to use for creation of the final node
        session - to use
        autoSave - Should save be called when a new node is created?
        Returns:
        the Node at absolutePath
        Throws:
        RepositoryException - in case of exception accessing the Repository

      • createUniqueNode

        public static Node createUniqueNode​(Node parent,
                                    java.lang.String nodeNameHint,
                                    java.lang.String nodeType,
                                    Session session)
                             throws RepositoryException
        Creates or gets the Node at the given Path. In case it has to create the Node all non-existent intermediate path-elements will be created with the given intermediate node type and the returned node will be created with the given nodeType.

        If the node name points to an existing node, the node name will be regarded as a name hint and a unique node name will be created by appending a number to the given name (eg. /some/path/foobar2). Please note that the uniqueness check is not an atomic JCR operation, so it is possible that you get a RepositoryException (path already exists) if another concurrent session created the same node in the meantime.

        Changes made are not saved by this method, so session.save() has to be called to persist them.

        Parameters:
        parent - existing parent node for the new node
        nodeNameHint - name hint for the new node
        nodeType - to use for creation of the node
        session - to use
        Returns:
        the newly created Node
        Throws:
        RepositoryException - in case of exception accessing the Repository

      • createPath

        public static Node createPath​(Node baseNode,
                              java.lang.String path,
                              boolean createUniqueLeaf,
                              java.lang.String intermediateNodeType,
                              java.lang.String nodeType,
                              Session session,
                              boolean autoSave)
                       throws RepositoryException
        Creates or gets the Node at the given path relative to the baseNode. In case it has to create the Node all non-existent intermediate path-elements will be created with the given intermediate node type and the returned node will be created with the given nodeType.

        If the parameter createUniqueLeaf is set, it will not get an existing node but rather try to create a unique node by appending a number to the last path element (leaf node). Please note that the uniqueness check is not an atomic JCR operation, so it is possible that you get a RepositoryException (path already exists) if another concurrent session created the same node in the meantime.

        Parameters:
        baseNode - existing node that should be the base for the relative path
        path - relative path to create
        createUniqueLeaf - whether the leaf of the path should be regarded as a name hint and a unique node name should be created by appending a number to the given name (eg. /some/path/foobar2)
        intermediateNodeType - to use for creation of intermediate nodes
        nodeType - to use for creation of the final node
        session - to use
        autoSave - Should save be called when a new node is created?
        Returns:
        the Node at path
        Throws:
        RepositoryException - in case of exception accessing the Repository

      • createValidName

        public static java.lang.String createValidName​(java.lang.String title)
        Create a valid label out of an arbitrary string. Same as calling createValidName(String, String[]) using STANDARD_LABEL_CHAR_MAPPING.
        Parameters:
        title - title to convert into a name
        Returns:
        a valid label string

      • createValidName

        public static java.lang.String createValidName​(java.lang.String title,
                                               java.lang.String[] labelCharMapping)
        Create a valid label out of an arbitrary string with a custom character mapping.
        Parameters:
        title - title to convert into a name
        labelCharMapping - a mapping of chars (index of the array) to strings that should be used as replacement for the characters
        Returns:
        a valid label string

      • createValidName

        public static java.lang.String createValidName​(java.lang.String title,
                                               java.lang.String[] labelCharMapping,
                                               java.lang.String defaultReplacementCharacter)
        Create a valid label out of an arbitrary string with a custom character mapping.
        Parameters:
        title - title to convert into a name
        labelCharMapping - a mapping of chars (index of the array) to strings that should be used as replacement for the characters
        defaultReplacementCharacter - the default character to use for characters not mapped in the labelCharMapping parameter
        Returns:
        a valid label string

      • createValidChildName

        public static java.lang.String createValidChildName​(Node node,
                                                    java.lang.String name)
                                             throws RepositoryException
        Create a valid name for a child of the node. Generates a valid name and test if child already exists. If name is already existing, iterate until a unique one is found
        Parameters:
        node - parent node
        name - the name to check
        Returns:
        a valid label string
        Throws:
        RepositoryException - in case of error, accessing the Repository

      • isValidName

        public static boolean isValidName​(java.lang.String name)
        Checks if the name is not empty and contains only valid chars.
        Parameters:
        name - the name to check
        Returns:
        true if the name is valid

      • createValue

        public static Value createValue​(java.lang.Object value,
                                Session session)
                         throws RepositoryException
        Creates a JCR Value for the given object with the given Session. Selects the the PropertyType according the instance of the object's Class
        Parameters:
        value - object
        session - to create value for
        Returns:
        the value or null if not convertible to a valid PropertyType
        Throws:
        RepositoryException - in case of error, accessing the Repository

      • setProperty

        public static void setProperty​(Node node,
                               java.lang.String propertyName,
                               java.lang.Object propertyValue)
                        throws RepositoryException
        Sets the value of the property. Selects the PropertyType according to the instance of the object's class.
        Parameters:
        node - The node where the property will be set on.
        propertyName - The name of the property.
        propertyValue - The value for the property.
        Throws:
        RepositoryException - if a repository error occurs

      • copy

        public static Item copy​(Item src,
                        Node dstParent,
                        java.lang.String name)
                 throws RepositoryException
        Copy the src item into the dstParent node. The name of the newly created item is set to name.
        Parameters:
        src - The item to copy to the new location
        dstParent - The node into which the src node is to be copied
        name - The name of the newly created item. If this is null the new item gets the same name as the src item.
        Returns:
        the new item
        Throws:
        RepositoryException - May be thrown in case of any problem copying the content.
        See Also:
        copy(Node, Node, String), copy(Property , Node, String)

      • copy

        public static Node copy​(Node src,
                        Node dstParent,
                        java.lang.String name)
                 throws RepositoryException
        Copy the src node into the dstParent node. The name of the newly created node is set to name.

        This method does a recursive (deep) copy of the subtree rooted at the source node to the destination. Any protected child nodes and and properties are not copied.

        Parameters:
        src - The node to copy to the new location
        dstParent - The node into which the src node is to be copied
        name - The name of the newly created node. If this is null the new node gets the same name as the src node.
        Returns:
        the newly created node
        Throws:
        RepositoryException - May be thrown in case of any problem copying the content.

      • copy

        public static Node copy​(Node src,
                        Node dstParent,
                        java.lang.String name,
                        boolean bestEffort)
                 throws RepositoryException
        Copy the src node into the dstParent node. The name of the newly created node is set to name.

        This method does a recursive (deep) copy of the subtree rooted at the source node to the destination. Any protected child nodes and and properties are not copied. The bestEffort argument specifies whether or not copying is aborted when adding a mixin, creating a property or creating a child node fails with a RepositoryException.

        Parameters:
        src - The node to copy to the new location
        dstParent - The node into which the src node is to be copied
        name - The name of the newly created node. If this is null the new node gets the same name as the src node.
        bestEffort - true for best effort copying: skip mixins, properties and child nodes which cannot be added.
        Returns:
        the newly created node
        Throws:
        RepositoryException - May be thrown in case of any problem copying the content.

      • copy

        public static Property copy​(Property src,
                            Node dstParent,
                            java.lang.String name)
                     throws RepositoryException
        Copy the src property into the dstParent node. The name of the newly created property is set to name.

        If the source property is protected, this method does nothing.

        Parameters:
        src - The property to copy to the new location
        dstParent - The node into which the src property is to be copied
        name - The name of the newly created property. If this is null the new property gets the same name as the src property.
        Returns:
        the new property or null if nothing was copied
        Throws:
        RepositoryException - May be thrown in case of any problem copying the content.

      • setChildNodeOrder

        public static boolean setChildNodeOrder​(Node parent,
                                        java.lang.String nameList)
                                 throws RepositoryException
        Restores the odering of the nodes according to the given comma seperated name list. Please note, that no changes are saved.
        Parameters:
        parent - the parent node
        nameList - the list of names
        Returns:
        true if the nodes were reordered
        Throws:
        RepositoryException - if an error occurrs.

      • setChildNodeOrder

        public static boolean setChildNodeOrder​(Node parent,
                                        java.lang.String[] names)
                                 throws RepositoryException
        Restores the odering of the nodes according to the given name list. Please note, that no changes are saved.
        Parameters:
        parent - the parent node
        names - the list of names
        Returns:
        true if the nodes were reordered
        Throws:
        RepositoryException - if an error occurrs.

      • copyResource

        public static int copyResource​(Session session,
                               java.lang.String path,
                               java.io.Writer out)
                        throws java.io.IOException,
                               RepositoryException
        Copies the contents of the resource to the given writer. The resource at path needs to have a binary property at the relative path "jcr:content/jcr:data". the string is encoded using the optional "jcr:content/jcr:encoding" property.
        Parameters:
        session - session
        path - file node path
        out - the writer
        Returns:
        the number of writter characters
        Throws:
        java.io.IOException - if an I/O error occurs
        RepositoryException - if a repository error occurs