phpcr/src/PHPCR/Version/VersionHistoryInterface.php

This is less relevant in PHP (Java had it to avoid typecasting in the visitor). We leave it here, to allow sanity checks or other operations an implementation might wants to do.

If this node is already of type $mixinName (either due to a previously added mixin or due to its primary type, through inheritance) then this method has no effect. Otherwise $mixinName is added to this node's jcr:mixinTypes property.

Semantically, the new node type may take effect immediately, on dispatch or on persist. The behavior is adopted must be the same as the behavior adopted for NodeInterface::setPrimaryType() and the behavior that occurs when a node is first created.

A ConstraintViolationException is thrown either immediately or on save if a conflict with another assigned mixin or the primary node type occurs or for an implementation-specific reason. Implementations may differ on when this validation is done.

In some implementations it may only be possible to add mixin types before a a node is persisted for the first time. In such cases any later calls to $addMixin will throw a ConstraintViolationException either immediately, on dispatch or on persist.

This is session-write method, meaning that the addition of the new node is dispatched upon SessionInterface::save().

The $relPath provided must not have an index on its final element, otherwise a RepositoryException is thrown.

If ordering is supported by the node type of the parent node of the new node then the new node is appended to the end of the child node list.

If $primaryNodeTypeName is specified, this type will be used (or a ConstraintViolationException thrown if this child type is not allowed). Otherwise the new node's primary node type will be determined by the child node definitions in the node types of its parent. This may occur either immediately, on dispatch (save, whether within or without transactions) or on persist (save without transactions, commit within a transaction), depending on the implementation.

The name of the new node is a system-created JCR name that differs from the names of all currently persisted child nodes and properties of this node. If present, the nameHint is used as the basis for the name of the new node.

This is a session-write method, meaning that the addition of the new node is dispatched upon Session::save

For the method to successfully add the new child node, the effective node type of this node must permit residual child nodes (see section 3.7.2.1 of the JCR 2.1 specification). If this condition is not met, a ConstraintViolationException will be thrown either immediately, on dispatch (save, whether within or without transactions) or on persist (save without transactions, commit within a transaction). Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately, on dispatch (save, whether within or without transactions) or on persist (save without transactions, commit within a transaction), if the node to which the new child is being added is read-only due to a checked-in node. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately, on dispatch (save, whether within or without transactions) or on persist (save without transactions, commit within a transaction), if a lock prevents the addition of the node. Implementations may differ on when this validation is performed.

The new node's primary node type will be determined by the residual child node definitions in the node type of this node. This may occur either immediately, on dispatch (save, whether within or without transactions) or on persist (save without transactions, commit within a transaction), depending on the implementation.

If ordering is supported by the node type of this node then the new node is appended to the end of the child node list.

The behavior of name generation for the new node depends on the form of the $nameHint parameter. If $nameHint is:

1. null: The new node name will be generated entirely by the repository. The namespace used for the new name may depend on implementation-specific configuration.
2. "" (the empty string), ":" (colon) or "{}": The new node name will be in the empty namespace and the local part of the name will be generated by the repository.
3. "somePrefix:" where somePrefix is a syntactically valid namespace prefix: The repository will attempt to create a name in the namespace represented by that prefix. If the prefix specified does not exist, then a NameSpaceException is thrown either immediately, on dispatch (save, whether within or without transactions) or on persist (save without transactions, commit within a transaction). If the prefix does exist then the local part of the name is generated by the repository.
4. "{someURI}" where someURI is a syntactically valid namespace URI: The repository will attempt to create a name in the namespace specified. If that namespace has no existing local mapping to a prefix then one is automatically created (as per section 3.5.2 of the JCR specification). The local part of the name is generated by the repository.
5. "somePrefix:localNameHint" where somePrefix is a syntactically valid namespace prefix and localNameHint is syntactically valid local name: The repository will attempt to create a name in the namespace represented by that prefix as described in (3), above. The local part of the name is generated by the repository using localNameHint as a basis. The way in which the local name is constructed from the hint may vary across implementations.
6. "{someURI}localNameHint" where someURI is a syntactically valid namespace URI and localNameHint is syntactically valid local name: The repository will attempt to create a name in the namespace specified as described in (4), above. The local part of the name is generated by the repository using localNameHint as a basis. The way in which the local name is constructed from the hint may vary across implementations.

Returns true if the specified mixin node type called $mixinName can be added to this node. Returns false otherwise. A result of false must be returned in each of the following cases:

• The mixin's definition conflicts with an existing primary or mixin node type of this node.
• This node is versionable and checked-in or is non-versionable and its nearest versionable ancestor is checked-in.
• This node is protected (as defined in this node's NodeDefinition, found in the node type of this node's parent).
• An access control restriction would prevent the addition of the mixin.
• A lock would prevent the addition of the mixin.
• An implementation-specific restriction would prevent the addition of the mixin.

This method may change the value of the jcr:currentLifecycleState property, in most cases it is expected that the implementation will change the value to that of the passed transition parameter, though this is an implementation-specific issue. If the jcr:currentLifecycleState property is changed the change is persisted immediately, there is no need to call save.

An ancestor of depth x is the Item that is x levels down along the path from the root node to this Item.

• depth = 0 returns the root node of a workspace.
• depth = 1 returns the child of the root node along the path to this Item.
• depth = 2 returns the grandchild of the root node along the path to this Item.
• And so on to depth = n, where n is the depth of this Item, which returns this Item itself.

If this node has more than one path (i.e., if it is a descendant of a shared node) then the path used to define the ancestor is implementaion- dependent.

In some cases there may appear to be more than one definition that could apply to this node. However, it is assumed that upon creation of this node, a single particular definition was used and it is that definition that this method returns. How this governing definition is selected upon node creation from among others which may have been applicable is an implementation issue and is not covered by this specification. The NodeDefinition returned when this method is called on the root node of a workspace is also up to the implementation.

• The root node returns 0.
• A property or child node of the root node returns 1.
• A property or child node of a child node of the root returns 2.
• And so on to this Item.

Applies to both referenceable and non-referenceable nodes.

This index is the one used to address same-name siblings using the square-bracket notation, e.g., /a[3]/b[4]. Note that the index always starts at 1 (not 0), for compatibility with XPath. As a result, for nodes that do not have same-name-siblings, this method will always return 1.

This includes only those mixin types explicitly assigned to this node. It does not include mixin types inherited through the addition of supertypes to the primary type hierarchy or through the addition of supertypes to the type hierarchy of any of the declared mixin types.

If this Item is the root node of the workspace, an empty string is returned.

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.

Does not include the names of the properties of this

Node

. If the child nodes of this node have an order then the names are returned in that order, otherwise the order is undefined.

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

The optional $filter follows the same semantics as the $filter parameter of NodeInterface::getNodes()

If $filter is a string: Gets all child nodes of this node accessible through the current Session that match namePattern (if no pattern is given, all accessible child nodes are returned). Does not include properties of this Node. 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 an iterator holding all accessible child nodes of N that are either called 'myapp:report', begin with the prefix 'jcr:' or are called 'my doc'.

The substrings within the pattern that are delimited by "|" characters and which may contain wildcard characters ("*") are called "globs".

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

If $filter is an array: Gets all child nodes of this node accessible through the current Session that match one or more of the $filter strings in the passed array.

A glob may be a full name or a partial name with one or more wildcard characters (""). For example, N->getNodes(array("jcr:", "myapp:report", "my doc")) would return an iterator holding all accessible child nodes of N that are either called 'myapp:report', begin with the prefix 'jcr:' or are called 'my doc'.

Note that unlike in the case of the getNodes() leading and trailing whitespace around a glob is not ignored.

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

If the child nodes of this node have an order then the names are returned in that order, otherwise the order is undefined.

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

The same reacquisition semantics apply as with getNode($relPath).

The primary node type of this node may specify one child item (child node or property) of this node as the primary child item. This method returns that item.

In cases where the primary child item specifies the name of a set same-name sibling child nodes, the node returned will be the one among the same-name siblings with index [1].

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

Which NodeType is returned when this method is called on the root node of a workspace is up to the implementation.

If $filter is a string: Gets all properties of this node accessible through the current Session that match namePattern (if no pattern is given, all accessible properties are returned). Does not include child nodes of this node. 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 an iterator holding all accessible properties of N that are either called 'myapp:name', begin with the prefix 'jcr:' or are called 'my doc'.

The substrings within the pattern that are delimited by "|" characters and which may contain wildcard characters ("*") are called globs.

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

If $filter is an array: Gets all properties of this node accessible through the current Session that match one or more of the $filter strings in the passed array.

A glob may be a full name or a partial name with one or more wildcard characters (""). For example, N->getProperties(array("jcr:", "myapp:report", "my doc")) would return an iterator holding all accessible properties of N that are either called 'myapp:report', begin with the prefix 'jcr:' or are called 'my doc'.

Note that unlike in the case of getProperties() leading and trailing whitespace around a glob is not ignored.

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

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

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

Apart from returning php native values instead of properties, this method has the same semantics as getProperties()

To improve performance, implementations should avoid instantiating the property objects for this method

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

If $type is set, attempts to convert the value to the specified type. This is a shortcut for getProperty()->getXX()

If no property is found at the specified $relPath, then $defaultValue is returned.

The same reacquisition semantics apply as with getProperty()

If the name parameter is null then all referring REFERENCES are returned regardless of name.

Some implementations may only return properties that have been persisted. Some may return both properties that have been persisted and those that have been dispatched but not persisted (for example, those saved within a transaction but not yet committed) while others implementations may return these two categories of property as well as properties that are still pending and not yet dispatched.

In implementations that support versioning, this method does not return properties that are part of the frozen state of a version in version storage.

If this node has no referring properties with the specified name, an empty iterator is returned.

If this node is not shared then the returned iterator contains only this node.

If the name parameter is null then all referring WEAKREFERENCE are returned regardless of name.

Some level 2 implementations may only return properties that have been saved (in a transactional setting this includes both those properties that have been saved but not yet committed, as well as properties that have been committed). Other level 2 implementations may additionally return properties that have been added within the current Session but are not yet saved.

In implementations that support versioning, this method does not return properties that are part of the frozen state of a version in version storage.

If this node has no referring properties with the specified name, an empty iterator is returned.

Returns true if a node accessible through the current Session exists at relPath and false otherwise.

Returns true if this node has one or more child nodes accessible through the current Session; false otherwise.

Returns true if this node has one or more properties accessible through the current Session; false otherwise.

Returns true if a property accessible through the current Session exists at relPath and false otherwise.

Returns false if this node is currently in the checked-in state (either due to its own status as a versionable node or due to the effect of a versionable node being checked in above it). Otherwise this method returns true. This includes the case where the repository does not support versioning (and therefore all nodes are always "checked-out", by default).

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. This includes the case where a repository does not support locking (in which case all nodes are "unlocked" by default).

Returns true if this Item has been saved but has subsequently been modified through the current session and therefore the state of this item as recorded in the session differs from the state of this item as saved. Within a transaction, isModified on an Item may return false (because the Item has been saved since the modification) even if the modification in question is not in persistent storage (because the transaction has not yet been committed).

Note that in read-only implementations, this method will always return false.

Returns true if this is a new item, meaning that it exists only in transient storage on the Session and has not yet been saved. Within a transaction, isNew on an Item may return false (because the item has been saved) even if that Item is not in persistent storage (because the transaction has not yet been committed).

Note that if an item returns true on isNew, then by definition is parent will return true on isModified.

Note that in read-only implementations, this method will always return false.

Returns true if this Item is a Node; Returns false if this Item is a Property.

Returns false otherwise. This method respects the effective node type of the node.

Two Item objects represent the same workspace item if all the following are true:

• Both objects were acquired through Session objects that were created by the same Repository object.
• Both objects were acquired through Session objects bound to the same repository workspace.
• The objects are either both Node objects or both Property objects.
• If they are Node objects, they have the same identifier.
• If they are Property objects they have identical names and isSame() is true of their parent nodes.

This method does not compare the states of the two items. For example, if two Item objects representing the same actual workspace item have been retrieved through two different sessions and one has been modified, then this method will still return true when comparing these two objects. Note that if two Item objects representing the same workspace item are retrieved through the same session they will always reflect the same state.

If this node supports child node ordering, this method inserts the child node at srcChildRelPath into the child node list at the position immediately before destChildRelPath.

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.

This is session-write method, meaning that a change made by this method is dispatched on save.

To persist a removal, a save must be performed that includes the (former) parent of the removed item within its scope.

If a node with same-name siblings is removed, this decrements by one the indices of all the siblings with indices greater than that of the removed node. In other words, a removal compacts the array of same-name siblings and causes the minimal re-numbering required to maintain the original order but leave no gaps in the numbering.

Both the semantic change in effective node type and the persistence of the change to the jcr:mixinTypes property occur on persist.

This removal must be done atomically, i.e., if one of the nodes cannot be removed, the method throws the exception NodeInterface::remove() would have thrown in that case, and none of the nodes are removed.

If this node is not shared this method removes only this node.

The ordering (if any) of this node among it siblings remains unchanged.

This is a session-write method, meaning that the name change is dispatched upon Session::save.

The $newName provided must not have an index, otherwise a RepositoryException is thrown.

An ItemExistsException will be thrown either immediately, on dispatch (save, whether within or without transactions) or on persist (save without transactions, commit within a transaction), if there already exists a sibling item of this node with the specified name and same-name-siblings are not allowed. Implementations may differ on when this validation is performed.

A ConstraintViolationException will be thrown either immediately, on dispatch (save, whether within or without transactions) or on persist (save without transactions, commit within a transaction), if changing the name 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, on dispatch (save, whether within or without transactions) or on persist (save without transactions, commit within a transaction), if this node is read-only due to a checked-in node. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately, on dispatch (save, whether within or without transactions) or on persist (save without transactions, commit within a transaction), if a lock prevents the name change of the node. Implementations may differ on when this validation is performed.

This method discards all pending changes currently recorded in this

Session

that apply to this Item or any of its child nodes and properties and returns these items to reflect the current saved state. Outside a transaction this state is simply the current state of persistent storage. Within a transaction, this state will reflect persistent storage as modified by changes that have been saved but not yet committed.

Any previous mixins are removed.

Semantically, the new node type may take effect immediately, on dispatch or on persist. The behavior adopted must be the same as the behavior adopted for setPrimaryType and the behavior that occurs when a node is first created.

This method adds (and if necessary removes) mixins in a single atomic step, avoiding constraint violations that might occur if the steps were done individually. This can be useful when changing node types while preserving existing content.

A

ConstraintViolationException

is thrown either immediately, on dispatch or on persist, if a conflict occurs within the set of assigned mixins or the primary node type or for an implementation-specific reason. Implementations may differ on when this validation is done.

In some implementations it may only be possible to set mixin types before a node is persisted for the first time. In such cases any later calls to setMixins will throw a ConstraintViolationException either immediately, on dispatch or on persist.

A NoSuchNodeTypeException is thrown either immediately, on dispatch or on persist, if one or more of the specified $mixinNames are not recognized. Implementations may differ on when this validation is done.

A VersionException is thrown either immediately, on dispatch or on persist, if this node is read-only due to a checked-in node. Implementations may differ on when this validation is done.

A LockException is thrown either immediately, on dispatch or on persist, if a lock prevents the assignment of the mixins. Implementations may differ on when this validation is done.

Also immediately changes this node's jcr:primaryType property appropriately. Semantically, the new node type may take effect immediately or on dispatch but must take effect on persist. Whichever behavior is adopted it must be the same as the behavior adopted for addMixin() (see below) and the behavior that occurs when a node is first created.

Sets the property of this node called $name to the specified value. This method works as factory method to create new properties and as a shortcut for PropertyInterface::setValue()

The type detection logic is exactly the same as in PropertyInterface::setValue

If the property does not yet exist, it is created and its property type determined by the node type of this node. If, based on the name and value passed, there is more than one property definition that applies, the repository chooses one definition according to some implementation- specific criteria.

Once property with name P has been created, the behavior of a subsequent setProperty($p,$v) may differ across implementations. Some repositories may allow P to be dynamically re-bound to a different property definition (based for example, on the new value being of a different type than the original value) while other repositories may not allow such dynamic re-binding.

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", null) would remove property called "P" of the node $n.

This is a session-write method, meaning that changes made through this method are dispatched on SessionInterface::save().

If $type is given: The behavior of this method is identical to that of setProperty($name, $value) except that the intended property type is explicitly specified.

Note: Have a look at the JSR-283 spec and/or API documentation for more details on what is supposed to happen for different types of values being passed to this method.

If this node does have a corresponding node in the workspace srcWorkspace, then this replaces this node and its subgraph with a clone of the corresponding node and its subgraph. If this node does not have a corresponding node in the workspace srcWorkspace, then the update method has no effect.

If the update succeeds the changes made are persisted immediately, there is no need to call save.

Note that update does not respect the checked-in status of nodes. An update may change a node even if it is currently checked-in (This fact is only relevant in an implementation that supports versioning).