A repository maysupportshareable nodes. This section describes the syntaxand behavior of the Java API for shareable nodes. For details on theshareable nodes model see §3.9Shareable Nodes Model.
Whether animplementation supports shareable nodes can be determined byquerying the repository descriptor table with
.
A return value ofindicates support (see §24.2Repository Descriptors).
Cloning anode into the same workspace is the standard way of creating ashared node.
Given workspace,and an existingnode at,the call
will create a new nodeatthat shares with.
Note that if theflag is set to,thedoes not create a shared node, but instead behaves identically to a.
If,,oris called and this call would create a node with the same identifieras that of an existingnode in the same workspace without at the same time removing thatexisting node (that is,is set to),then the new node is created and is added to the shared set of theexistingnode.
During import thebehavior of theindicates that if an incoming referenceable node has the sameidentifier as an existingnode in the workspace, the incoming node is created and added to theshared set of the existingnode (see §3.9.1mix:shareable). Note that if the import inquestion is aimport (see §11.6.2Session Event-Based Import and §11.7.2Session Stream-Based Import) new shared transient nodes willbe created. These nodes are not considered to benew, in thesense thatwill return.
Theshared setof a node consists of all nodes (including itself) with which itshares. This set is retrieved with
.
The method
removes the node fromits shared set without affecting the other nodes in the set. Themethod
removes the node andall the members of its shared set.
In the first case,assuming more than one member in the shared set, the children of theremoved node are unaffected since they still have at least one othernode as parent. In the second case, however, the children of theshared set are removed.
In cases where theshared set consists of a single node, or when these methods arecalled on a non-shareable node, their behavior is identical to.
When applied to ashared node with at least one other member in its shared set, themethod
or
may behave asor as.Which behavior is adopted is an implementation issue.
The behavior ofis permitted to vary across repositories because the details of theunderlying implementation will make one or the other of thebehaviors more natural for that repository. In particular if arepository implements a shared set by one “primary” parent (thatcontrols the lifetime of the child) and zero or more “secondary”parents (that reference that child), thenis most naturally interpreted differently on the primary parent andone of the secondary parents. To force that repository to do aon the primary parent would require that implementation to pick oneof the secondary parents as the new primary parent, and change allof the other secondary parents to refer to that new primary parent.
For all three methods,the removal is dispatched on.
When a change is madeto a shared node in the transient layer,becomesand that change is visible in all nodes in the shared set of thatnode. After a transient shared node is dispatched,becomesfor all nodes in the shared set of that node.
The new nodes createdby aare never in the shared set of any node that existed before the,but if two nodesandin the source of aare in the same shared set,then the two resulting nodesandin the destination of themust both be in the same shared set,whereandare disjoint.
In an implementationthat forbids share cycles, any session-write method that can createa shared node will cause ato be thrown either immediately or on,if persisting the change would result in a share cycle.
Similarly, anyworkspace-write method that can create a shared node will throw aif completion of the operation would result in a share cycle.
In an implementationthat does not prevent share cycles, checking for cycles is left tothe repository user.
When more than oneshared node in a given shared set is exported to an XML document,the first node in that shared set is exported in the normal fashion(with all of its properties and children), but any subsequent sharednode in that shared set is exported as a special node of type,which contains only theproperty of the shared node and theproperty indicating the type.Note thatonly appears in a serialization document, and never appears as anode type of a node in a repository.
When an XML elementwith node typeis imported into a repository that does not support shared nodes,the import must fail (will throw a,whilewill throw an.
When a property of ashared node is modified, or when a child item is added to or deletedfrom a shared node, although that property or child nodemodification is performed on every node in the shared set of thatnode, only one event is fired for the shared set. Which node in theshared set is identified in the event is implementation-defined.
When a lock is addedor removed from a shared node, it is automatically added or removedfrom every node in the shared set of that node.
If at least oneshare-ancestor of a nodeholds a deep locked then that lock applies to,resulting inbeing locked.
All the nodes in ashared set always have the same declared primary node type and thesame set of assigned mixin node types. Since different nodes in theshared set may have different parents, those parents must be of anappropriate node type to have a child of with these types.
If the members of ashared set correspond to child node definitions (in their respectiveparents) with conflictingprotected settings, the effectiveprotected value of all the members of the shared set will be thelogicalof the protected settings of the set of child node definitions.
If a node isversionable then all nodes within its shared set share the sameversion history. Under full versioning this follows logically fromthe fact that the nodes all share the samereference (see §3.13.2.2mix:versionable), pointing to asingle commonnode (see §3.13.5.1nt:versionHistory).
On check-in of a nodeN within the shared set, its versionable state is determinedjust as in the non-shared case, but because the node is shared, theresulting version will also reflect the versionable state of anynodeN' in the shared set ofN.
On check-in of aparentM of a shared nodeN the contribution ofNto the versionable state ofM is determined according to theOPV ofN. Note that the OPV of two nodesN andN'in the same shared set (with parent nodeM andM',respectively) maydiffer because the OPV ofN isdetermined by the node type ofM, while that ofN' isdetermined by the node type ofM'.
The effect of sharednodes onfalls into three cases:
Athat causes the creation of a new shared node (see §14.1.1SharedNode Creation on Restore).
Athat causes the removal of a shared node: In this case theparticular shared node is removed but its descendants continue toexist below the remaining members of the shared set.
Acauses a change to the state of a shared node: Any change isreflected in all nodes in its shared set.
Athat causes a change below a shared node: The subgraph is changedas usual and the change is visible through many paths.
If nodeshares with nodethen these two nodes are considered “the same” according to themethod. Additionally, if the shared nodes have a property, thenandare also considered “the same”. If they have a child nodethen, similarly,andare also the “the same”.
If an attempt is madeto remove themixin node type from a node in a shared set the implementation mayeither throw aor allow the removal and change the subgraph in someimplementation-specific manner. One possibility is to replace thenode with a copy that has no children (if this does not violate thenode type restrictions of that node). Another possibility is to givethe node a copy of all of its descendants (unless the resulting copyoperation would be unfeasible, as would be the case if a share cyclewere involved).
If a query matches twoor more nodes in a shared set, whether all of these nodes or justone is returned in the query result is an implementation issue.
This variability isallowed since different implementations might have different“natural” behaviors, and it would be expensive for animplementation to compute the answer that is “unnatural” forthat implementation.
If a query matches adescendant node of a shared set, it appears in query results onlyonce.