7.1.11 Ordering Child Nodes

If a node supports orderable child nodes then the following method can be used to arrange the order of its child nodes.

javax.jcr.
Node

void

orderBefore(String srcChildRelPath,
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. 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 (see 4.6.1 Names vs. Paths).

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.

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 (by this method), or on save, if this operation would violate a implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately (by this method), 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.

If another error occurs a RepositoryException is thrown.


If a node type returns true on a call to NodeType.hasOrderableChildNodes(), then all nodes of that node type must support the method Node.orderBefore. If a node type returns false on a call to this method, then nodes of that node type may support Node.orderBefore. Only the primary node type of a node controls that node's status in this regard. This setting on a mixin node type will not have any effect on the node.

If a node has orderable child nodes then at any time the current order of its child nodes is reflected in the order of nodes in the iterator returned by Node.getNodes.

If a node does not have orderable child nodes then the order of nodes returned by Node.getNodes is not guaranteed and may change at any time.

Note that the order of properties returned by Node.getProperties is never client-controllable.

See 4.4 Orderable Child Nodes.