com.day.cq.commons.jcr

Class JcrUtil

java.lang.Object

com.day.cq.commons.jcr.JcrUtil

public class JcrUtil
extends java.lang.Object

Utility for common JCR tasks

Field Summary

Fields

Modifier and Type	Field and 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 and Description
JcrUtil()

Method Summary

Modifier and Type	Method and 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(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	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 nodeType, Session session) 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	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