org.argeo.jcr

Class JcrUtils

java.lang.Object

org.argeo.jcr.JcrUtils

public class JcrUtils
extends java.lang.Object

Utility methods to simplify common JCR operations.

Field Summary

Fields

Modifier and Type	Field and Description
static char[]	INVALID_NAME_CHARACTERS Not complete yet.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	accessControlListSummary(AccessControlList acl) Returns a human-readable summary of this access control list.
static void	addListener(Session session, EventListener listener, int eventTypes, java.lang.String basePath, java.lang.String nodeType) Convenient method to add a listener.
static void	addPrivilege(Session session, java.lang.String path, java.lang.String principal, java.lang.String privilege) Convenience method for adding a single privilege to a principal (user or role), typically jcr:all
static java.lang.Boolean	addPrivileges(Session session, java.lang.String path, java.security.Principal principal, java.util.List<Privilege> privs) Add privileges on a path to a Principal.
static java.lang.Boolean	allPropertiesEquals(Node reference, Node observed, java.lang.Boolean onlyCommonProperties) Check whether all first-level properties (except jcr:* properties) are equal.
static java.lang.Boolean	check(Node node, java.lang.String propertyName) Concisely get the boolean value of a property
static java.lang.String	checksumFile(Node fileNode, java.lang.String algorithm) Deprecated. use separate digest utilities
static void	clearAccessControList(Session session, java.lang.String path, java.lang.String username) Clear authorizations for a user at this path
static void	closeQuietly(Binary binary) Cleanly disposes a Binary even if it is null.
static void	copy(Node fromNode, Node toNode) Copies recursively the content of a node to another one.
static Node	copyBytesAsFile(Node folderNode, java.lang.String fileName, byte[] bytes) Copy bytes as an nt:file
static Node	copyFile(Node folderNode, java.io.File file) Copy a file as an nt:file, assuming an nt:folder hierarchy.
static java.lang.Long	copyFiles(Node fromNode, Node toNode, java.lang.Boolean recursive, JcrMonitor monitor, boolean onlyAdd) Copy only nt:folder and nt:file, without their additional types and properties.
static Node	copyStreamAsFile(Node folderNode, java.lang.String fileName, java.io.InputStream in) Copy a stream as an nt:file, assuming an nt:folder hierarchy.
static java.lang.Long	countFiles(Node node) Iteratively count all file nodes in subtree, inefficient but can be useful when query are poorly supported, such as in remoting.
static java.lang.String	dateAsPath(java.util.Calendar cal) The provided data as a path ('/' at the end, not the beginning)
static java.lang.String	dateAsPath(java.util.Calendar cal, java.lang.Boolean addHour) The provided data as a path ('/' at the end, not the beginning)
static void	debug(Node node) Recursively outputs the contents of the given node.
static void	debug(Node node, org.apache.commons.logging.Log log) Recursively outputs the contents of the given node.
static java.util.Map<java.lang.String,PropertyDiff>	diffProperties(Node reference, Node observed)
static java.util.Map<java.lang.String,PropertyDiff>	diffProperties(Node reference, Node observed, java.util.List<java.lang.String> properties) Compare only a restricted list of properties of two nodes.
static void	discardQuietly(Session session) Discards the current changes in a session by calling Session.refresh(boolean) with false, only logging potential errors when doing so.
static void	discardUnderlyingSessionQuietly(Node node) Discards the current changes in the session attached to this node.
static java.lang.String	firstCharsToPath(java.lang.String str, java.lang.Integer nbrOfChars) Creates depth from a string (typically a username) by adding levels based on its first characters: "aBcD",2 becomes a/aB
static java.lang.String	get(Node node, java.lang.String propertyName) Concisely get the string value of a property or null if this node doesn't have this property
static AccessControlList	getAccessControlList(AccessControlManager acm, java.lang.String path) Gets the first available access control list for this path, throws exception if not found
static byte[]	getBinaryAsBytes(Property property) Retrieve a Binary as a byte array
static byte[]	getBytes(Node node, java.lang.String propertyName) Concisely get the bytes array value of a property
static java.io.InputStream	getFileAsStream(Node fileNode) Read an an nt:file as an InputStream.
static java.lang.String	getNameQuietly(Node node) Call Item.getName() without exceptions (useful in super constructors).
static long	getNodeApproxSize(Node node) Estimate the sub tree size from current node.
static Node	getOrAdd(Node parent, java.lang.String childName) Routine that get the child with this name, adding id it does not already exist
static Node	getOrAdd(Node parent, java.lang.String childName, java.lang.String childPrimaryNodeType) Routine that get the child with this name, adding id it does not already exist
static java.lang.String	getPath(Node node) Concisely get the path of the given node.
static java.lang.String	getPropertyDefinitionAsString(Property prop) Returns a String representing the short version (see Node type Notation attributes grammar) of the main business attributes of this property definition
static java.lang.String	getStringPropertyQuietly(Node node, java.lang.String propertyName) Call Node.getProperty(String) without exceptions (useful in super constructors).
static java.lang.String	hostAsPath(java.lang.String host) Creates a path from a FQDN, inverting the order of the component: www.argeo.org becomes org.argeo.www
static java.lang.String	lastPathElement(java.lang.String path) The last element of a path.
static void	logEffectiveAccessPolicies(Node node) Logs the effective access control policies
static void	logEffectiveAccessPolicies(Session session, java.lang.String path) Logs the effective access control policies
static Session	loginOrCreateWorkspace(Repository repository, java.lang.String workspaceName) Login to a workspace with implicit credentials, creates the workspace with these credentials if it does not already exist.
static Session	loginOrCreateWorkspace(Repository repository, java.lang.String workspaceName, Credentials credentials) Login to a workspace with implicit credentials, creates the workspace with these credentials if it does not already exist.
static void	logoutQuietly(Session session) Logs out the session, not throwing any exception, even if it is null.
static Node	mkdirs(Node parentNode, java.lang.String relativePath) Create sub nodes relative to a parent node
static Node	mkdirs(Node parentNode, java.lang.String relativePath, java.lang.String nodeType) Create sub nodes relative to a parent node
static Node	mkdirs(Node parentNode, java.lang.String relativePath, java.lang.String nodeType, java.lang.String intermediaryNodeType) Create sub nodes relative to a parent node
static Node	mkdirs(Session session, java.lang.String path) Creates the nodes making path, if they don't exist.
static Node	mkdirs(Session session, java.lang.String path, java.lang.String type)
static Node	mkdirs(Session session, java.lang.String path, java.lang.String type, java.lang.String intermediaryNodeType, java.lang.Boolean versioning) Creates the nodes making path, if they don't exist.
static Node	mkdirsSafe(Session session, java.lang.String path)
static Node	mkdirsSafe(Session session, java.lang.String path, java.lang.String type) Synchronized and save is performed, to avoid race conditions in initializers leading to duplicate nodes.
static Node	mkfolders(Session session, java.lang.String path) Creates the nodes making the path as NodeType.NT_FOLDER
static java.util.List<Node>	nodeIteratorToList(NodeIterator nodeIterator) Convert a NodeIterator to a list of Node
static java.lang.String	nodeNameFromPath(java.lang.String path) Retrieves the node name from the provided path
static java.lang.String	normalize(java.lang.String name) Normalizes a name so that it can be stored in contexts not supporting names with ':' (typically databases).
static java.lang.String	normalizePath(java.lang.String path) Make sure that: starts with '/', do not end with '/', do not have '//'
static java.lang.String	parentPath(java.lang.String path) Retrieves the parent path of the provided path
static java.util.Calendar	parseCalendar(java.text.DateFormat dateFormat, java.lang.String value) Converts in one call a string into a gregorian calendar.
static Node	querySingleNode(Query query) Queries one single node.
static void	registerNamespaceSafely(NamespaceRegistry nr, java.lang.String prefix, java.lang.String uri) Safe and repository implementation independent registration of a namespace.
static void	registerNamespaceSafely(Session session, java.lang.String prefix, java.lang.String uri) Safe and repository implementation independent registration of a namespace.
static void	removeListenerQuietly(Session session, EventListener listener) Removes a listener without throwing exception
static java.lang.String	replaceInvalidChars(java.lang.String name) Replaces characters which are invalid in a JCR name by '_'.
static java.lang.String	replaceInvalidChars(java.lang.String name, char replacement) Replaces characters which are invalid in a JCR name.
static void	setBinaryAsBytes(Node node, java.lang.String property, byte[] bytes) Writes a Binary from a byte array
static void	setBinaryAsBytes(Property prop, byte[] bytes) Writes a Binary from a byte array
static java.util.List<java.lang.String>	tokenize(java.lang.String path) Convert a path to the list of its tokens
static void	unregisterQuietly(Node node, EventListener eventListener) Quietly unregisters an EventListener from the udnerlying workspace of this node.
static void	unregisterQuietly(Workspace workspace, EventListener eventListener) Quietly unregisters an EventListener from this workspace
static void	updateLastModified(Node node) If this node is has the NodeType.MIX_LAST_MODIFIED mixin, it updates the Property.JCR_LAST_MODIFIED property with the current time and the Property.JCR_LAST_MODIFIED_BY property with the underlying session user id.
static void	updateLastModifiedAndParents(Node node, java.lang.String untilPath) Update lastModified recursively until this parent.
static java.lang.String	urlAsPath(java.lang.String url) Creates a deep path based on a URL: http://subdomain.example.com/to/content?args becomes com/example/subdomain/to/content
static java.lang.String	urlFromAddressProperties(Node node) Build URL based on the NodeType.NT_ADDRESS properties.
static void	urlToAddressProperties(Node node, java.lang.String url) Set the NodeType.NT_ADDRESS properties based on this URL.
static java.lang.String	uuidAsPath(java.lang.String uuid) Creates a path from a UUID (e.g.

Methods inherited from class java.lang.Object

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

Field Detail

INVALID_NAME_CHARACTERS

public static final char[] INVALID_NAME_CHARACTERS

Not complete yet. See http://www.day.com/specs/jcr/2.0/3_Repository_Model.html#3.2.2%20Local %20Names

Method Detail

querySingleNode

public static Node querySingleNode(Query query)

Queries one single node.

Returns:

one single node or null if none was found

Throws:

ArgeoJcrException - if more than one node was found

nodeNameFromPath

public static java.lang.String nodeNameFromPath(java.lang.String path)

Retrieves the node name from the provided path

parentPath

public static java.lang.String parentPath(java.lang.String path)

Retrieves the parent path of the provided path

dateAsPath

public static java.lang.String dateAsPath(java.util.Calendar cal)

The provided data as a path ('/' at the end, not the beginning)

urlAsPath

public static java.lang.String urlAsPath(java.lang.String url)

Creates a deep path based on a URL: http://subdomain.example.com/to/content?args becomes com/example/subdomain/to/content

urlToAddressProperties

public static void urlToAddressProperties(Node node,
                                          java.lang.String url)

Set the NodeType.NT_ADDRESS properties based on this URL.

urlFromAddressProperties

public static java.lang.String urlFromAddressProperties(Node node)

Build URL based on the NodeType.NT_ADDRESS properties.

normalizePath

public static java.lang.String normalizePath(java.lang.String path)

Make sure that: starts with '/', do not end with '/', do not have '//'

hostAsPath

public static java.lang.String hostAsPath(java.lang.String host)

Creates a path from a FQDN, inverting the order of the component: www.argeo.org becomes org.argeo.www

uuidAsPath

public static java.lang.String uuidAsPath(java.lang.String uuid)

Creates a path from a UUID (e.g. 6ebda899-217d-4bf1-abe4-2839085c8f3c becomes 6ebda899-217d/4bf1/abe4/2839085c8f3c/). '/' at the end, not the beginning

dateAsPath

public static java.lang.String dateAsPath(java.util.Calendar cal,
                                          java.lang.Boolean addHour)

The provided data as a path ('/' at the end, not the beginning)

Parameters:

cal - the date

addHour - whether to add hour as well

parseCalendar

public static java.util.Calendar parseCalendar(java.text.DateFormat dateFormat,
                                               java.lang.String value)

Converts in one call a string into a gregorian calendar.

lastPathElement

public static java.lang.String lastPathElement(java.lang.String path)

The last element of a path.

getNameQuietly

public static java.lang.String getNameQuietly(Node node)

Call Item.getName() without exceptions (useful in super constructors).

getStringPropertyQuietly

public static java.lang.String getStringPropertyQuietly(Node node,
                                                        java.lang.String propertyName)

Call Node.getProperty(String) without exceptions (useful in super constructors).

getOrAdd

public static Node getOrAdd(Node parent,
                            java.lang.String childName,
                            java.lang.String childPrimaryNodeType)
                     throws RepositoryException

Routine that get the child with this name, adding id it does not already exist

Throws:

RepositoryException

getOrAdd

public static Node getOrAdd(Node parent,
                            java.lang.String childName)
                     throws RepositoryException

Routine that get the child with this name, adding id it does not already exist

Throws:

RepositoryException

nodeIteratorToList

public static java.util.List<Node> nodeIteratorToList(NodeIterator nodeIterator)

Convert a NodeIterator to a list of Node

get

public static java.lang.String get(Node node,
                                   java.lang.String propertyName)

Concisely get the string value of a property or null if this node doesn't have this property

getPath

public static java.lang.String getPath(Node node)

Concisely get the path of the given node.

check

public static java.lang.Boolean check(Node node,
                                      java.lang.String propertyName)

Concisely get the boolean value of a property

getBytes

public static byte[] getBytes(Node node,
                              java.lang.String propertyName)

Concisely get the bytes array value of a property

mkdirs

public static Node mkdirs(Node parentNode,
                          java.lang.String relativePath)

Create sub nodes relative to a parent node

mkdirs

public static Node mkdirs(Node parentNode,
                          java.lang.String relativePath,
                          java.lang.String nodeType)

Create sub nodes relative to a parent node

Parameters:

nodeType - the type of the leaf node

mkdirs

public static Node mkdirs(Node parentNode,
                          java.lang.String relativePath,
                          java.lang.String nodeType,
                          java.lang.String intermediaryNodeType)

Create sub nodes relative to a parent node

Parameters:

nodeType - the type of the leaf node

mkdirsSafe

public static Node mkdirsSafe(Session session,
                              java.lang.String path,
                              java.lang.String type)

Synchronized and save is performed, to avoid race conditions in initializers leading to duplicate nodes.

mkdirsSafe

public static Node mkdirsSafe(Session session,
                              java.lang.String path)

mkdirs

public static Node mkdirs(Session session,
                          java.lang.String path)

Creates the nodes making path, if they don't exist.

mkdirs

public static Node mkdirs(Session session,
                          java.lang.String path,
                          java.lang.String type)

Parameters:

type - the type of the leaf node

mkdirs

public static Node mkdirs(Session session,
                          java.lang.String path,
                          java.lang.String type,
                          java.lang.String intermediaryNodeType,
                          java.lang.Boolean versioning)

Creates the nodes making path, if they don't exist. This is up to the caller to save the session. Use with caution since it can create duplicate nodes if used concurrently. Requires read access to the root node of the workspace.

tokenize

public static java.util.List<java.lang.String> tokenize(java.lang.String path)

Convert a path to the list of its tokens

registerNamespaceSafely

public static void registerNamespaceSafely(Session session,
                                           java.lang.String prefix,
                                           java.lang.String uri)

Safe and repository implementation independent registration of a namespace.

registerNamespaceSafely

public static void registerNamespaceSafely(NamespaceRegistry nr,
                                           java.lang.String prefix,
                                           java.lang.String uri)

Safe and repository implementation independent registration of a namespace.

debug

public static void debug(Node node)

Recursively outputs the contents of the given node.

debug

public static void debug(Node node,
                         org.apache.commons.logging.Log log)

Recursively outputs the contents of the given node.

logEffectiveAccessPolicies

public static void logEffectiveAccessPolicies(Node node)

Logs the effective access control policies

logEffectiveAccessPolicies

public static void logEffectiveAccessPolicies(Session session,
                                              java.lang.String path)

Logs the effective access control policies

accessControlListSummary

public static java.lang.String accessControlListSummary(AccessControlList acl)

Returns a human-readable summary of this access control list.

copy

public static void copy(Node fromNode,
                        Node toNode)

Copies recursively the content of a node to another one. Do NOT copy the property values of NodeType.MIX_CREATED and NodeType.MIX_LAST_MODIFIED, but update the Property.JCR_LAST_MODIFIED and Property.JCR_LAST_MODIFIED_BY properties if the target node has the NodeType.MIX_LAST_MODIFIED mixin.

allPropertiesEquals

public static java.lang.Boolean allPropertiesEquals(Node reference,
                                                    Node observed,
                                                    java.lang.Boolean onlyCommonProperties)

Check whether all first-level properties (except jcr:* properties) are equal. Skip jcr:* properties

diffProperties

public static java.util.Map<java.lang.String,PropertyDiff> diffProperties(Node reference,
                                                                          Node observed)

diffProperties

public static java.util.Map<java.lang.String,PropertyDiff> diffProperties(Node reference,
                                                                          Node observed,
                                                                          java.util.List<java.lang.String> properties)

Compare only a restricted list of properties of two nodes. No recursivity.

normalize

public static java.lang.String normalize(java.lang.String name)

Normalizes a name so that it can be stored in contexts not supporting names with ':' (typically databases). Replaces ':' by '_'.

replaceInvalidChars

public static java.lang.String replaceInvalidChars(java.lang.String name)

Replaces characters which are invalid in a JCR name by '_'. Currently not exhaustive.

See Also:

INVALID_NAME_CHARACTERS

replaceInvalidChars

public static java.lang.String replaceInvalidChars(java.lang.String name,
                                                   char replacement)

Replaces characters which are invalid in a JCR name. Currently not exhaustive.

See Also:

INVALID_NAME_CHARACTERS

closeQuietly

public static void closeQuietly(Binary binary)

Cleanly disposes a Binary even if it is null.

getBinaryAsBytes

public static byte[] getBinaryAsBytes(Property property)

Retrieve a Binary as a byte array

setBinaryAsBytes

public static void setBinaryAsBytes(Node node,
                                    java.lang.String property,
                                    byte[] bytes)

Writes a Binary from a byte array

setBinaryAsBytes

public static void setBinaryAsBytes(Property prop,
                                    byte[] bytes)

Writes a Binary from a byte array

firstCharsToPath

public static java.lang.String firstCharsToPath(java.lang.String str,
                                                java.lang.Integer nbrOfChars)

Creates depth from a string (typically a username) by adding levels based on its first characters: "aBcD",2 becomes a/aB

discardUnderlyingSessionQuietly

public static void discardUnderlyingSessionQuietly(Node node)

Discards the current changes in the session attached to this node. To be used typically in a catch block.

See Also:

discardQuietly(Session)

discardQuietly

public static void discardQuietly(Session session)

Discards the current changes in a session by calling Session.refresh(boolean) with false, only logging potential errors when doing so. To be used typically in a catch block.

loginOrCreateWorkspace

public static Session loginOrCreateWorkspace(Repository repository,
                                             java.lang.String workspaceName)
                                      throws RepositoryException

Login to a workspace with implicit credentials, creates the workspace with these credentials if it does not already exist.

Throws:

RepositoryException

loginOrCreateWorkspace

public static Session loginOrCreateWorkspace(Repository repository,
                                             java.lang.String workspaceName,
                                             Credentials credentials)
                                      throws RepositoryException

Login to a workspace with implicit credentials, creates the workspace with these credentials if it does not already exist.

Throws:

RepositoryException

logoutQuietly

public static void logoutQuietly(Session session)

Logs out the session, not throwing any exception, even if it is null. Jcr.logout(Session) should rather be used.

addListener

public static void addListener(Session session,
                               EventListener listener,
                               int eventTypes,
                               java.lang.String basePath,
                               java.lang.String nodeType)

Convenient method to add a listener. uuids passed as null, deep=true, local=true, only one node type

removeListenerQuietly

public static void removeListenerQuietly(Session session,
                                         EventListener listener)

Removes a listener without throwing exception

unregisterQuietly

public static void unregisterQuietly(Node node,
                                     EventListener eventListener)

Quietly unregisters an EventListener from the udnerlying workspace of this node.

unregisterQuietly

public static void unregisterQuietly(Workspace workspace,
                                     EventListener eventListener)

Quietly unregisters an EventListener from this workspace

updateLastModified

public static void updateLastModified(Node node)

If this node is has the NodeType.MIX_LAST_MODIFIED mixin, it updates the Property.JCR_LAST_MODIFIED property with the current time and the Property.JCR_LAST_MODIFIED_BY property with the underlying session user id. In Jackrabbit 2.x, these properties are not automatically updated, hence the need for manual update. The session is not saved.

updateLastModifiedAndParents

public static void updateLastModifiedAndParents(Node node,
                                                java.lang.String untilPath)

Update lastModified recursively until this parent.

Parameters:

node - the node

untilPath - the base path, null is equivalent to "/"

getPropertyDefinitionAsString

public static java.lang.String getPropertyDefinitionAsString(Property prop)

Returns a String representing the short version (see Node type Notation attributes grammar) of the main business attributes of this property definition

Parameters:

prop -

getNodeApproxSize

public static long getNodeApproxSize(Node node)

Estimate the sub tree size from current node. Computation is based on the Jcr Property.getLength() method. Note : it is not the exact size used on the disk by the current part of the JCR Tree.

addPrivilege

public static void addPrivilege(Session session,
                                java.lang.String path,
                                java.lang.String principal,
                                java.lang.String privilege)
                         throws RepositoryException

Convenience method for adding a single privilege to a principal (user or role), typically jcr:all

Throws:

RepositoryException

addPrivileges

public static java.lang.Boolean addPrivileges(Session session,
                                              java.lang.String path,
                                              java.security.Principal principal,
                                              java.util.List<Privilege> privs)
                                       throws RepositoryException

Add privileges on a path to a Principal. The path must already exist. Session is saved. Synchronized to prevent concurrent modifications of the same node.

Throws:

RepositoryException

getAccessControlList

public static AccessControlList getAccessControlList(AccessControlManager acm,
                                                     java.lang.String path)
                                              throws RepositoryException

Gets the first available access control list for this path, throws exception if not found

Throws:

RepositoryException

clearAccessControList

public static void clearAccessControList(Session session,
                                         java.lang.String path,
                                         java.lang.String username)
                                  throws RepositoryException

Clear authorizations for a user at this path

Throws:

RepositoryException

mkfolders

public static Node mkfolders(Session session,
                             java.lang.String path)

Creates the nodes making the path as NodeType.NT_FOLDER

copyFiles

public static java.lang.Long copyFiles(Node fromNode,
                                       Node toNode,
                                       java.lang.Boolean recursive,
                                       JcrMonitor monitor,
                                       boolean onlyAdd)

Copy only nt:folder and nt:file, without their additional types and properties.

Parameters:

recursive - if true copies folders as well, otherwise only first level files

Returns:

how many files were copied

countFiles

public static java.lang.Long countFiles(Node node)

Iteratively count all file nodes in subtree, inefficient but can be useful when query are poorly supported, such as in remoting.

copyFile

public static Node copyFile(Node folderNode,
                            java.io.File file)

Copy a file as an nt:file, assuming an nt:folder hierarchy. The session is NOT saved.

Returns:

the created file node

copyBytesAsFile

public static Node copyBytesAsFile(Node folderNode,
                                   java.lang.String fileName,
                                   byte[] bytes)

Copy bytes as an nt:file

copyStreamAsFile

public static Node copyStreamAsFile(Node folderNode,
                                    java.lang.String fileName,
                                    java.io.InputStream in)

Copy a stream as an nt:file, assuming an nt:folder hierarchy. The session is NOT saved.

Returns:

the created file node

getFileAsStream

public static java.io.InputStream getFileAsStream(Node fileNode)
                                           throws RepositoryException

Read an an nt:file as an InputStream.

Throws:

RepositoryException

checksumFile

@Deprecated
public static java.lang.String checksumFile(Node fileNode,
                                                        java.lang.String algorithm)

Deprecated. use separate digest utilities

Computes the checksum of an nt:file.