javax.jcr
Interface Node

All Superinterfaces:

Item

All Known Subinterfaces:

Version, VersionHistory

public interface Node

extends Item

The Node interface represents a node in the hierarchy that makes up the repository.

Method Summary

void	addMixin(java.lang.String mixinName) Adds the specified mixin node type to this node.
Node	addNode(java.lang.String relPath) Creates a new node at relPath.
Node	addNode(java.lang.String relPath, java.lang.String primaryNodeTypeName) Creates a new node at relPath of the specified node type.
boolean	canAddMixin(java.lang.String mixinName) Returns true if the specified mixin node type, mixinName, can be added to this node.
void	cancelMerge(Version version) Cancels the merge process with respect to this node and specified version.
Version	checkin() Creates a new version with a system generated version name and returns that version (which will be the new base version of this node).
void	checkout() Sets this versionable node to checked-out status by setting its jcr:isCheckedOut property to true and adds to the jcr:predecessors (multi-value) property a reference to the current base version (the same value as held in jcr:baseVersion).
void	doneMerge(Version version) Completes the merge process with respect to this node and the specified version.
Version	getBaseVersion() Returns the current base version of this versionable node.
java.lang.String	getCorrespondingNodePath(java.lang.String workspaceName) Returns the absolute path of the node in the specified workspace that corresponds to this node.
NodeDefinition	getDefinition() Returns the node definition that applies to this node.
int	getIndex() This method returns the index of this node within the ordered set of its same-name sibling nodes.
Lock	getLock() Returns the Lock object that applies to this node.
NodeType[]	getMixinNodeTypes() Returns an array of NodeType objects representing the mixin node types assigned to this node.
Node	getNode(java.lang.String relPath) Returns the node at relPath relative to this node.
NodeIterator	getNodes() Returns a NodeIterator over all child Nodes of this Node.
NodeIterator	getNodes(java.lang.String namePattern) Gets all child nodes of this node that match namePattern.
Item	getPrimaryItem() Returns the primary child item of this node.
NodeType	getPrimaryNodeType() Returns the primary node type of this node.
PropertyIterator	getProperties() Returns all properties of this node.
PropertyIterator	getProperties(java.lang.String namePattern) Gets all properties of this node that match namePattern.
Property	getProperty(java.lang.String relPath) Returns the property at relPath relative to this node.
PropertyIterator	getReferences() Returns all REFERENCE properties that refer to this node.
java.lang.String	getUUID() Returns the UUID of this node as recorded in this node's jcr:uuid property.
VersionHistory	getVersionHistory() Returns the VersionHistory object of this node.
boolean	hasNode(java.lang.String relPath) Indicates whether a node exists at relPath Returns true if a node exists at relPath and false otherwise.
boolean	hasNodes() Indicates whether this node has child nodes.
boolean	hasProperties() Indicates whether this node has properties.
boolean	hasProperty(java.lang.String relPath) Indicates whether a property exists at relPath Returns true if a property exists at relPath and false otherwise.
boolean	holdsLock() Returns true if this node holds a lock; otherwise returns false.
boolean	isCheckedOut() Returns true if this node is either versionable and currently checked-out, non-versionable and its nearest versionable ancestor is checked-out or non-versionable and it has no versionable ancestor.
boolean	isLocked() Returns true if this node is locked either as a result of a lock held by this node or by a deep lock on a node above this node; otherwise returns false.
boolean	isNodeType(java.lang.String nodeTypeName) Indicates whether this node is of the specified node type.
Lock	lock(boolean isDeep, boolean isSessionScoped) Places a lock on this node.
NodeIterator	merge(java.lang.String srcWorkspace, boolean bestEffort) This method can be thought of as a version-sensitive update (see 7.1.7 Updating and Cloning Nodes across Workspaces in the specification).
void	orderBefore(java.lang.String srcChildRelPath, java.lang.String destChildRelPath) If this node supports child node ordering, this method inserts the child node at srcChildRelPath before its sibling, the child node at destChildRelPath, in the child node list.
void	removeMixin(java.lang.String mixinName) Removes the specified mixin node type from this node.
void	restore(java.lang.String versionName, boolean removeExisting) Restores this node to the state defined by the version with the specified versionName.
void	restore(Version version, boolean removeExisting) Restores this node to the state defined by the specified version.
void	restore(Version version, java.lang.String relPath, boolean removeExisting) Restores the specified version to relPath, relative to this node.
void	restoreByLabel(java.lang.String versionLabel, boolean removeExisting) Restores the version of this node with the specified version label.
Property	setProperty(java.lang.String name, boolean value) Sets the specified property to the specified value.
Property	setProperty(java.lang.String name, java.util.Calendar value) Sets the specified property to the specified value.
Property	setProperty(java.lang.String name, double value) Sets the specified property to the specified value.
Property	setProperty(java.lang.String name, java.io.InputStream value) Sets the specified property to the specified value.
Property	setProperty(java.lang.String name, long value) Sets the specified property to the specified value.
Property	setProperty(java.lang.String name, Node value) Sets the specified (REFERENCE)property to refer to the specified Node.
Property	setProperty(java.lang.String name, java.lang.String value) Sets the specified property to the specified value.
Property	setProperty(java.lang.String name, java.lang.String[] values) Sets the specified property to the specified array of values.
Property	setProperty(java.lang.String name, java.lang.String[] values, int type) Sets the specified property to the specified array of values and to the specified type.
Property	setProperty(java.lang.String name, java.lang.String value, int type) Sets the specified (single-value) property to the specified value.
Property	setProperty(java.lang.String name, Value value) Sets the specified (single-value) property of this node to the specified value.
Property	setProperty(java.lang.String name, Value[] values) Sets the specified (multi-value) property to the specified array of values.
Property	setProperty(java.lang.String name, Value[] values, int type) Sets the specified (multi-value) property to the specified array of values.
Property	setProperty(java.lang.String name, Value value, int type) Sets the specified (single-value) property to the specified value.
void	unlock() Removes the lock on this node.
void	update(java.lang.String srcWorkspaceName) If this node does have a corresponding node in the workspace srcWorkspaceName, then this replaces this node and its subtree with a clone of the corresponding node and its subtree.

Methods inherited from interface javax.jcr.Item

accept, getAncestor, getDepth, getName, getParent, getPath, getSession, isModified, isNew, isNode, isSame, refresh, remove, save

Method Detail

addNode

public Node addNode(java.lang.String relPath)
             throws ItemExistsException,
                    PathNotFoundException,
                    VersionException,
                    ConstraintViolationException,
                    LockException,
                    RepositoryException

Creates a new node at relPath. The new node will only be persisted on save() if it meets the constraint criteria of the parent node's node type.

In order to save a newly added node, save must be called either on the Session, or on the new node's parent or higher-order ancestor (grandparent, etc.). An attempt to call save only on the newly added node will throw a RepositoryException.

In the context of this method the relPath provided must not have an index on its final element. If it does then a RepositoryException is thrown.

Strictly speaking, the parameter is actually a relative path to the parent node of the node to be added, appended with the name desired for the new node (if the a node is being added directly below this node then only the name need be specified). It does not specify a position within the child node ordering. If ordering is supported by the node type of the parent node then the new node is appended to the end of the child node list.

Since this signature does not allow explicit node type assignment, the new node's primary node type will be determined (either immediately or on save, depending on the implementation) by the child node definitions in the node types of its parent.

An ItemExistsException will be thrown either immediately (by this method), or on save, if an item at the specified path already exists and same-name siblings are not allowed. Implementations may differ on when this validation is performed.

A PathNotFoundException will be thrown either immediately, or on save, if the specified path implies intermediary nodes that do not exist. Implementations may differ on when this validation is performed.

A ConstraintViolationException will be thrown either immediately or on save if adding the node would violate a node type or implementation-specific constraint or if an attempt is made to add a node as the child of a property. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save, if the node to which the new child is being added is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately (by this method), or on save, if a lock prevents the addition of the node. Implementations may differ on when this validation is performed.

Parameters:

relPath - The path of the new node to be created.

Returns:

The node that was added.

Throws:

ItemExistsException - if an item at the specified path already exists, same-name siblings are not allowed and this implementation performs this validation immediately instead of waiting until save.

PathNotFoundException - if the specified path implies intermediary Nodes that do not exist or the last element of relPath has an index, and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if a node type or implementation-specific constraint is violated or if an attempt is made to add a node as the child of a property and this implementation performs this validation immediately instead of waiting until save.

VersionException - if the node to which the new child is being added is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the addition of the node and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - If the last element of relPath has an index or if another error occurs.

addNode

public Node addNode(java.lang.String relPath,
                    java.lang.String primaryNodeTypeName)
             throws ItemExistsException,
                    PathNotFoundException,
                    NoSuchNodeTypeException,
                    LockException,
                    VersionException,
                    ConstraintViolationException,
                    RepositoryException

Creates a new node at relPath of the specified node type. The same as addNode(String relPath) except that the primary node type of the new node is explictly specified.

An ItemExistsException will be thrown either immediately (by this method), or on save, if an item at the specified path already exists and same-name siblings are not allowed. Implementations may differ on when this validation is performed.

A PathNotFoundException will be thrown either immediately, or on save, if the specified path implies intermediary nodes that do not exist. Implementations may differ on when this validation is performed.

A NoSuchNodeTypeException will be thrown either immediately or on save, if the specified node type is not recognized. Implementations may differ on when this validation is performed.

A ConstraintViolationException will be thrown either immediately or on save if adding the node would violate a node type or implementation-specific constraint or if an attempt is made to add a node as the child of a property. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save, if the node to which the new child is being added is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately (by this method), or on save, if a lock prevents the addition of the node. Implementations may differ on when this validation is performed.

Parameters:

relPath - the path of the new node to be created.

primaryNodeTypeName - The name of the primary node type of the new node.

Returns:

the node that was added.

Throws:

ItemExistsException - if an item at the specified path already exists, same-name siblings are not allowed and this implementation performs this validation immediately instead of waiting until save.

PathNotFoundException - if the specified path implies intermediary Nodes that do not exist or the last element of relPath has an index, and this implementation performs this validation immediately instead of waiting until save.

NoSuchNodeTypeException - if the specified node type is not recognized and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if a node type or implementation-specific constraint is violated or if an attempt is made to add a node as the child of a property and this implementation performs this validation immediately instead of waiting until save.

VersionException - if the node to which the new child is being added is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the addition of the node and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - if the last element of relPath has an index or if another error occurs.

orderBefore

public void orderBefore(java.lang.String srcChildRelPath,
                        java.lang.String destChildRelPath)
                 throws UnsupportedRepositoryOperationException,
                        VersionException,
                        ConstraintViolationException,
                        ItemNotFoundException,
                        LockException,
                        RepositoryException

If this node supports child node ordering, this method inserts the child node at srcChildRelPath before its sibling, the child node at destChildRelPath, in the child node list.

To place the node srcChildRelPath at the end of the list, a destChildRelPath of null is used.

Note that (apart from the case where destChildRelPath is null) both of these arguments must be relative paths of depth one, in other words they are the names of the child nodes, possibly suffixed with an index.

If srcChildRelPath and destChildRelPath are the same, then no change is made.

Changes to ordering of child nodes are persisted on save of the parent node. But, if this node does not support child node ordering, then a UnsupportedRepositoryOperationException thrown.

If srcChildRelPath is not the relative path to a child node of this node then an ItemNotFoundException is thrown.

If destChildRelPath is neither the relative path to a child node of this node nor null, then an ItemNotFoundException is also thrown.

A ConstraintViolationException will be thrown either immediately or on save if this operation would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save, if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately (by this method), or on save, if a lock prevents the re-ordering. Implementations may differ on when this validation is performed.

Parameters:

srcChildRelPath - the relative path to the child node (that is, name plus possible index) to be moved in the ordering

destChildRelPath - the the relative path to the child node (that is, name plus possible index) before which the node srcChildRelPath will be placed.

Throws:

UnsupportedRepositoryOperationException - if ordering is not supported.

ConstraintViolationException - if an implementation-specific ordering restriction is violated and this implementation performs this validation immediately instead of waiting until save.

ItemNotFoundException - if either parameter is not the relative path of a child node of this node.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save..

LockException - if a lock prevents the re-ordering and this implementation performs this validation immediately instead of waiting until save..

RepositoryException - if another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            Value value)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified (single-value) property of this node to the specified value. If the property does not yet exist, it is created. The property type of the property will be that specified by the node type of this node.

If the property type of the supplied Value object is different from that required, then a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown. If another error occurs, a RepositoryException is thrown.

If the node type of this node does not indicate a specific property type, then the property type of the supplied Value object is used and if the property already exists it assumes both the new value and new property type.

If the property is multi-valued, a ValueFormatException is thrown.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (Value)null) would remove property called "P" of the node in N.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope, that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately or on save if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately or on save if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

Parameters:

name - The name of a property of this node

value - The value to be assigned

Returns:

The updated Property object

Throws:

ValueFormatException - if value cannot be converted to the type of the specified property or if the property already exists and is multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - if another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            Value value,
                            int type)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified (single-value) property to the specified value. If the property does not yet exist, it is created.

The type of the new property is determined by the type parameter specified.

If the property type of the supplied Value object is different from that required, then a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown.

If the property is not single-valued then a ValueFormatException is also thrown.

If the property already exists it assumes both the new value and the new property type.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (Value)null, type) would remove property called "P" of the node in N.

To persist the addition or removal of a property, save must be called on the Session, this Node, or an ancestor of this Node.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope, that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately or on save if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately or on save if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

Parameters:

name - the name of the property to be set.

value - a Value object.

type - the type of the property.

Returns:

the Property object set, or null if this method was used to remove a property (by setting its value to null).

Throws:

ValueFormatException - if value cannot be converted to the specified type or if the property already exists and is multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - if another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            Value[] values)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified (multi-value) property to the specified array of values. If the property does not yet exist, it is created. Same as setProperty(String name, Value value) except that an array of Value objects is assigned instead of a single Value.

The property type of the property will be that specified by the node type of this node. If the property type of the supplied Value objects is different from that required, then a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown.

All Value objects in the array must be of the same type, otherwise a ValueFormatException is thrown. If the property is not multi-valued then a ValueFormatException is also thrown. If another error occurs, a RepositoryException is thrown.

If the node type of this node does not indicate a specific property type, then the property type of the supplied Value objects is used and if the property already exists it assumes both the new values and the new property type.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (Value[])null) would remove property called "P" of the node in N.

Note that this is different from passing an array that contains null elements. In such a case, the array is compacted by removing the nulls. The resulting set of values never contains nulls. However, the set may be empty: N.setProperty("P", new Value[]{null}) would set the property to the empty set of values.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope, that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately or on save if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately or on save if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

Parameters:

name - the name of the property to be set.

values - an array of Value objects.

Returns:

the updated Property object.

Throws:

ValueFormatException - if value cannot be converted to the type of the specified property or if the property already exists and is not multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - if another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            Value[] values,
                            int type)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified (multi-value) property to the specified array of values. If the property does not yet exist, it is created. The type of the property is determined by the type parameter specified.

If the property type of the supplied Value objects is different from that specified, then a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown.

If the property already exists it assumes both the new values and the new property type.

All Value objects in the array must be of the same type, otherwise a ValueFormatException is thrown. If the property is not multi-valued then a ValueFormatException is also thrown. If another error occurs, a RepositoryException is thrown.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (Value[])null, type) would remove property called "P" of the node in N.

Note that this is different from passing an array that contains null elements. In such a case, the array is compacted by removing the nulls. The resulting set of values never contains nulls. However, the set may be empty: N.setProperty("P", new Value[]{null}, type) would set the property to the empty set of values.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope, that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately or on save if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately or on save if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

Parameters:

name - the name of the property to be set.

values - an array of Value objects.

type - the type of the property.

Returns:

the updated Property object.

Throws:

ValueFormatException - if value cannot be converted to the specified type or if the property already exists and is not multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - if another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            java.lang.String[] values)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified property to the specified array of values. Same as setProperty(String name, Value[] values) except that the values are specified as String objects instead of Value objects.

Parameters:

name - the name of the property to be set.

values - an array of Value objects.

Returns:

the updated Property object.

Throws:

ValueFormatException - if value cannot be converted to the type of the specified property or if the property already exists and is not multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - if another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            java.lang.String[] values,
                            int type)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified property to the specified array of values and to the specified type. Same as setProperty(String name, Value[] values, int type) except that the values are specified as String objects instead of Value objects.

Parameters:

name - the name of the property to be set.

values - an array of Value objects.

type - the type of the property.

Returns:

the updated Property object.

Throws:

ValueFormatException - if value cannot be converted to the specified type or if the property already exists and is not multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - if another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            java.lang.String value)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified property to the specified value. If the property does not yet exist, it is created. The property type of the property being set is determined by the node type of this node (the one on which this method is being called). If this is something other than PropertyType.STRING, a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown. If the property is multi-valued, a ValueFormatException is also thrown. If another error occurs, a RepositoryException is thrown.

If the node type of this node does not specify a particular property type for the property being set then PropertyType.STRING is used and, if the property already exists, it assumes both the new value and type PropertyType.STRING.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (String)null) would remove property called "P" of the node in N.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope, that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately or on save if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately or on save if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

Parameters:

name - The name of a property of this node

value - The value to assigned

Returns:

The updated Property object

Throws:

ValueFormatException - if value cannot be converted to the type of the specified property or if the property already exists and is multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - If another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            java.lang.String value,
                            int type)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified (single-value) property to the specified value. If the property does not yet exist, it is created.

The type of the property is determined by the type parameter specified.

If the property type specified is not PropertyType.STRING, then a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown.

If the property is not single-valued then a ValueFormatException is also thrown.

If the property already exists it assumes both the new value and the new property type.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (Value)null, type) would remove property called "P" of the node in N.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope, that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately or on save if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately or on save if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

Parameters:

name - the name of the property to be set.

value - a String object.

type - the type of the property.

Returns:

the Property object set, or null if this method was used to remove a property (by setting its value to null).

Throws:

ValueFormatException - if value cannot be converted to the specified type or if the property already exists and is multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - if another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            java.io.InputStream value)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified property to the specified value. If the property does not yet exist, it is created. The property type of the property being set is determined by the node type of this node (the one on which this method is being called). If this is something other than PropertyType.BINARY, a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown. If the property is multi-valued, a ValueFormatException is also thrown. If another error occurs, a RepositoryException is thrown.

If the node type of this node does not specify a particular property type for the property being set then PropertyType.BINARY is used and, if the property already exists, it assumes both the new value and type PropertyType.BINARY.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (InputStream)null) would remove property called "P" of the node in N.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope, that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately or on save if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately or on save if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

Parameters:

name - The name of a property of this node

value - The value to assigned

Returns:

The updated Property object

Throws:

ValueFormatException - if value cannot be converted to the type of the specified property or if the property already exists and is multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - If another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            boolean value)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified property to the specified value. If the property does not yet exist, it is created. The property type of the property being set is determined by the node type of this node (the one on which this method is being called). If this is something other than PropertyType.BOOLEAN, a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown. If the property is multi-valued, a ValueFormatException is also thrown. If another error occurs, a RepositoryException is thrown.

If the node type of this node does not specify a particular property type for the property being set then PropertyType.BOOLEAN is used and, if the property already exists, it assumes both the new value and type PropertyType.BOOLEAN.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope, that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately or on save if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately or on save if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

Parameters:

name - The name of a property of this node

value - The value to assigned

Returns:

The updated Property object

Throws:

ValueFormatException - if value cannot be converted to the type of the specified property or if the property already exists and is multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - If another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            double value)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified property to the specified value. If the property does not yet exist, it is created. The property type of the property being set is determined by the node type of this node (the one on which this method is being called). If this is something other than PropertyType.DOUBLE, a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown. If the property is multi-valued, a ValueFormatException is also thrown. If another error occurs, a RepositoryException is thrown.

If the node type of this node does not specify a particular property type for the property being set then PropertyType.DOUBLE is used and, if the property already exists, it assumes both the new value and type PropertyType.DOUBLE.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope, that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately or on save if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately or on save if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

Parameters:

name - The name of a property of this node

value - The value to assigned

Returns:

The updated Property object

Throws:

ValueFormatException - if value cannot be converted to the type of the specified property or if the property already exists and is multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - If another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            long value)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified property to the specified value. If the property does not yet exist, it is created. The property type of the property being set is determined by the node type of this node (the one on which this method is being called). If this is something other than PropertyType.LONG, a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown. If the property is multi-valued, a ValueFormatException is also thrown. If another error occurs, a RepositoryException is thrown.

If the node type of this node does not specify a particular property type for the property being set then PropertyType.LONG is used and, if the property already exists, it assumes both the new value and type PropertyType.LONG.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope, that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately or on save if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately or on save if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

Parameters:

name - The name of a property of this node

value - The value to assigned

Returns:

The updated Property object

Throws:

ValueFormatException - if value cannot be converted to the type of the specified property or if the property already exists and is multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - If another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            java.util.Calendar value)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified property to the specified value. If the property does not yet exist, it is created. The property type of the property being set is determined by the node type of this node (the one on which this method is being called). If this is something other than PropertyType.DATE, a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown. If the property is multi-valued, a ValueFormatException is also thrown. If another error occurs, a RepositoryException is thrown.

If the node type of this node does not specify a particular property type for the property being set then PropertyType.DATE is used and, if the property already exists, it assumes both the new value and type PropertyType.DATE.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (Calendar)null) would remove property called "P" of the node in N.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope, that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately or on save if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately or on save if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

Parameters:

name - The name of a property of this node

value - The value to assigned

Returns:

The updated Property object

Throws:

ValueFormatException - if value cannot be converted to the type of the specified property or if the property already exists and is multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - If another error occurs.

setProperty

public Property setProperty(java.lang.String name,
                            Node value)
                     throws ValueFormatException,
                            VersionException,
                            LockException,
                            ConstraintViolationException,
                            RepositoryException

Sets the specified (REFERENCE)property to refer to the specified Node. If the property does not yet exist, it is created. The property type of the property being set is determined by the node type of this node (the one on which this method is being called). If the property type of this property is something other than either PropertyType.REFERENCE or undefined then a ValueFormatException is thrown. If the property is multi-valued, a ValueFormatException is also thrown. If another error occurs, a RepositoryException is thrown.

If the node type of this node does not specify a particular property type for the property being set then PropertyType.REFERENCE is used and, if the property already exists, it assumes both the new value and type PropertyType.REFERENCE.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (Node)null) would remove property called "P" of the node in N.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope, that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately or on save if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately or on save if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately or on save if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

Parameters:

name - The name of a property of this node

value - The value to assigned

Returns:

The updated Property object

Throws:

ValueFormatException - if value cannot be converted to the type of the specified property or if the property already exists and is multi-valued.

VersionException - if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the setting of the property and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if the change would violate a node-type or other constraint and this implementation performs this validation immediately instead of waiting until save.

RepositoryException - If another error occurs.

getNode

public Node getNode(java.lang.String relPath)
             throws PathNotFoundException,
                    RepositoryException

Returns the node at relPath relative to this node.

If relPath contains a path element that refers to a node with same-name sibling nodes without explicitly including an index using the array-style notation ([x]), then the index [1] is assumed (indexing of same name siblings begins at 1, not 0, in order to preserve compatibility with XPath).

Within the scope of a single Session object, if a Node object has been acquired, any subsequent call of getNode reacquiring the same node must return a Node object reflecting the same state as the earlier Node object. Whether this object is actually the same Node instance, or simply one wrapping the same state, is up to the implementation.

Parameters:

relPath - The relative path of the node to retrieve.

Returns:

The node at relPath.

Throws:

PathNotFoundException - If no node exists at the specified path.

RepositoryException - If another error occurs.

getNodes

public NodeIterator getNodes()
                      throws RepositoryException

Returns a NodeIterator over all child Nodes of this Node. Does not include properties of this Node. The same reacquisition semantics apply as with getNode(String). If this node has no child nodes, then an empty iterator is returned.

Returns:

A NodeIterator over all child Nodes of this Node.

Throws:

RepositoryException - If an error occurs.

getNodes

public NodeIterator getNodes(java.lang.String namePattern)
                      throws RepositoryException

Gets all child nodes of this node that match namePattern. The pattern may be a full name or a partial name with one or more wildcard characters ("*"), or a disjunction (using the "|" character to represent logical OR) of these. For example,

N.getNodes("jcr:* | myapp:report | my doc")

would return a NodeIterator holding all child nodes of N that are either called 'myapp:report', begin with the prefix 'jcr:' or are called 'my doc'.

Note that leading and trailing whitespace around a disjunct is ignored, but whitespace within a disjunct forms part of the pattern to be matched.

The EBNF for namePattern is:

namePattern ::= disjunct {'|' disjunct}
disjunct ::= name [':' name]
name ::= '*' | ['*'] fragment {'*' fragment} ['*']
fragment ::= char {char}
char ::= nonspace | ' '
nonspace ::= (* Any Unicode character except: '/', ':', '[', ']', '*', ''', '"', '|' or any whitespace character *)

The pattern is matched against the names (not the paths) of the immediate child nodes of this node.

If this node has no matching child nodes, then an empty iterator is returned.

The same reacquisition semantics apply as with getNode(String).

Parameters:

namePattern - a name pattern

Returns:

a NodeIterator

Throws:

RepositoryException - If an unexpected error occurs.

getProperty

public Property getProperty(java.lang.String relPath)
                     throws PathNotFoundException,
                            RepositoryException

Returns the property at relPath relative to this node. The same reacquisition semantics apply as with getNode(String).

Parameters:

relPath - The relative path of the property to retrieve.

Returns:

The property at relPath.

Throws:

PathNotFoundException - If no property exists at the specified path.

RepositoryException - If another error occurs.

getProperties

public PropertyIterator getProperties()
                               throws RepositoryException

Returns all properties of this node. Returns a PropertyIterator over all properties of this node. Does not include child nodes of this node. The same reacquisition semantics apply as with getNode(String). If this node has no properties, then an empty iterator is returned.

Returns:

A PropertyIterator.

Throws:

RepositoryException - If an error occurs.

getProperties

public PropertyIterator getProperties(java.lang.String namePattern)
                               throws RepositoryException

Gets all properties of this node that match namePattern. The pattern may be a full name or a partial name with one or more wildcard characters ("*"), or a disjunction (using the "|" character to represent logical OR) of these. For example,

N.getProperties("jcr:* | myapp:name | my doc")

would return a PropertyIterator holding all properties of N that are either called 'myapp:name', begin with the prefix 'jcr:' or are called 'my doc'.

Note that leading and trailing whitespace around a disjunct is ignored, but whitespace within a disjunct forms part of the pattern to be matched.

The EBNF for namePattern is:

namePattern ::= disjunct {'|' disjunct}
disjunct ::= name [':' name]
name ::= '*' | ['*'] fragment {'*' fragment} ['*']
fragment ::= char {char}
char ::= nonspace | ' '
nonspace ::= (* Any Unicode character except: '/', ':', '[', ']', '*', ''', '"', '|' or any whitespace character *)

The pattern is matched against the names (not the paths) of the immediate child properties of this node.

If this node has no matching properties, then an empty iterator is returned.

The same reacquisition semantics apply as with getNode(String).

Parameters:

namePattern - a name pattern

Returns:

a PropertyIterator

Throws:

RepositoryException - If an unexpected error occurs.

getPrimaryItem

public Item getPrimaryItem()
                    throws ItemNotFoundException,
                           RepositoryException

Returns the primary child item of this no