4.7.2 Reference, Path and Name Property Types

Three of the property types listed above have special semantics: REFERENCE, PATH and NAME.

NAME properties are used for storing strings that are namespace-qualified, such as the names of node types or the names of repository items. A NAME property can be thought of as a namespace-aware STRING. It is set like a string (for example, setProperty("aNodeType", "nt:file")). However, the prefix is automatically mapped to its current URI and the value is stored using that full namespace URI. When the property is later read the mapping is reversed and if the URI in question has been remapped that remapping is reflected in the returned value.

A PATH property represents a path in a workspace (either relative or absolute) and therefore can also be used to refer to items elsewhere in the workspace. However, the PATH property does not enforce referential integrity; in other words it can point to a location where no item currently exists. Like a NAME property, a PATH is also namespace-aware in that its apparent value when read will always reflect the current prefix to URI mapping.

A REFERENCE property is used to provide a named reference to a node elsewhere in the workspace. The value of the property is the UUID of the node to which it refers. Consequently, only a referenceable node can be the target of a REFERENCE property (see 4.9 Referenceable Nodes). REFERENCE properties have the additional semantic feature of maintaining referential integrity by preventing the removal of any node that is currently the target of a reference property. To remove a node that is the target of a REFERENCE, one must first remove the REFERENCE. The check for referential integrity is done when an attempt is made to persist the removal of a node (that is, either on save, or, if the change was made within a transaction, on commit; in any case, the check is not done immediately on remove). The method Node.getReferences() can be used to find all REFERENCE properties that refer to a particular node. The method Node.setProperty(String name, Node value) can be used to set the value of a REFERENCE property to the UUID of the specified node.

In versioning repositories the version storage is exposed in the workspace tree as a protected subtree below jcr:system/jcr:versionStorage (see 8.2.2 Version Storage). Within this subtree, the referential integrity requirement is lifted for REFERENCE properties stored as part of the frozen state of a version (see Reference Properties within a Version).