A repository maysupportsimple versioning orfull versioning. Thissection describes the syntax and behavior of the Java API for bothtypes of versioning. Details on the underlying concepts, datastructures and node types can be found in §3.13VersioningModel.
Whether animplementation supports simple versioning can be determined byquerying the repository descriptor table with
.
Whether it supportsfull versioning can be determined by querying
.
A return value ofindicates support (see §24.2Repository Descriptors).
A new versionable nodeis created by assigning it the appropriate mixin type:under simple versioning orunder full versioning. This may be done either to an existing node,through aor at node creation, through assignment of a primary type thatinherits from the mixin. Some repositories may also automaticallyassign a versionable mixin on creation of certain nodes (see §3.7.6Node Type Inheritance and §10.10Node Type Assignment).
Under both simple andfull versioning, on persist of a new versionable nodethat neither corresponds nor shares withan existing node:
Theproperty ofis set toand
A new()is created for.contains one,the root version ()(see §3.13.5.2Root Version).
Additionally, underfull versioning:
A newnode is created and bound to theobject.
Theproperty ofis set to the identifier of.
Ifis the result of a copy operation then theproperty ofis set as described in §15.1.4Copying Versionable Nodes andVersion Lineage. Otherwise this property is not added.
A newnode ()is created as thechild node of.
A newnode is created and bound to.This node becomes thechild node of.
A newnode ()is created as thechild node of.does not hold any state information aboutexcept the node type and identifier information found in,,andproperties (see §3.13.4Frozen Nodes).
Thepropertyofis initialized to the identifier of.This constitutes a reference fromto its version history.
Thepropertyofis initialized to the identifier of.This constitutes a reference fromto its current base version.
The multi-valuepropertyofis initialized to contain a single identifier, that of(the same as).
The version history ofa versionable node is represented by aobject acquired through
or
whereis the absolute path to the node.
Conversely, given a,the versionable node to which it belongs can be found through
which returns theidentifier of the versionable node, which can then be used to getthe node itself (see §5.1.4Getting a Node by Identifier).
The root version of aversion history is accessed through
.
Under full versioningthe root version can also be accessed through aor an equivalent standard content access method, since it alsoexists as anchild node of thenode, called
The full set ofversions within a version history can be retrieved through
.
If the version graphof this history is linear then the versions are returned in order ofcreation date, from oldest to newest. Otherwise the order of thereturned versions is implementation-dependent.
Alternatively, themethod
returns an iteratorover all the versions in theline of descent from the rootversion to the base version that is bound to the workspace throughwhich thiswas acquired.
Within a versionhistory,is the base version bound to workspaceif and only if there exists a versionable nodeinwhose version history isandis the base version of.
The line of descentfrom versionto,whereis an eventual successor of,is the ordered list of versions starting withand proceeding through each direct successor to.
The versions arereturned in order of creation date, from oldest to newest.
Note that in a simpleversioning repository the behavior of this method is equivalent toreturning all versions in the version history in order from oldestto newest.
Versions can also beretrieved directly by name, using
,
or by label, using,
(see §15.4VersionLabels).
The frozen nodeswithin each of the versions within the history can be accesseddirectly from thethrough
and
.
These methods returnthe frozen nodes within the version history corresponding to, and inthe same order as, theobjects returned byand,respectively.
Theinterface extends.Under simple versioning version histories are not represented bynodes in content, so the methods inherited fromare not required to function and may instead throw a.Under full versioning theobject represents the correspondingnode and itsmethods must function accordingly.
The method
returns the currentbase version of the versionable node at.
When an existingversionable node is moved to a new location withor,it maintains the same version history and no changes are made tothat history.
Under both simple andfull versioning, when an existing versionable nodeis copied to a new location either in the same workspace or another,and the repository preserves the versionable mixin (see §10.7.4Dropping Mixins on Copy):
A copy of,call it,is created, as usual.
A new, empty,version history for,call it,is also created.
Under full versioning:
The properties,andofare not copied frombut are initialized as usual.
Theproperty ofis set to point to the base version of.
Theproperty allows an application to determine thelineage of aversion across version histories that were produced by copying aversionable node to a new location.
Under both simple andfull versioning, when a versionable nodeis cloned to another workspace:
A clone of,call it,is created, as usual.
is initialized to have the same version history and base version as.
Under full versioning:
The,andproperties ofare copied tounchanged
Under both simple andfull versioning, when a new nodeis added to the shared set of a shareable, versionable node:
The shared nodeis created, as usual.
is initialized to have the same version history and base version as.Unlike in the case of cloning (see §15.1.5Cloning VersionableNodes) the base versions ofandwill always remain identical.
Under full versioning:
Because nodes inthe same shared set have identical properties,nodes in the same shared set will necessarily have identical,andproperties.
A newversionof a versionable node is created using
whereis the absolute path of the node.
On check-in of aversionable nodewith version history:
Ifis notor,anis thrown, otherwise,
ifhas unsaved changes pending, anis thrown, otherwise,
ifis alreadychecked-in, this method has no effect and returnsthebase version (see §3.13.6.2Base Version) of,otherwise,
ifhas aproperty present, ais thrown (notice that this is enforced in any case due to thesetting of theproperty'sattribute).
Otherwise:
The subgraphrooted atis maderead-only (see §15.2.2Read-Only on Check-In).
A new,,is created with a system-determinedversion name (see§15.2.1.1Version Name) and acreated date (see§15.2.1.2Created Date) as part of its state. Under fullversioning, a newnode is bound toand added as a child node of,with the version name as its node name and the created date as thevalue of itsproperty.
Theversionablestate ofis recorded in thefrozen nodeofas described in §3.13.9Versionable State. Under fullversioning,is added as thechild node of.
is added to the version history ofas the direct successor of thebase version of.Under full versioning:
Theproperty ofis copied to theproperty of.
Theproperty ofis set to the empty array.
A reference tois added to theproperty of each of thenodes referred to by theproperty of.
The base versionofis changed to.Under full versioning, theproperty ofis changed to refer to.
Theproperty ofis set to.This change is a workspace-write and therefore does not require a.
is nowchecked-in.
is returned.
A version isrepresented by aobject.
The name given to aversion is automatically generated and must be unique within itsversion history. How the name is generated is up to theimplementation. The name of a version is retrieved with the method
,
inherited by.Under simple versioning this is the only inherited method that isrequired to function (see §15.2.1.7Version Extends Node).
.
returns the directpredecessors of this.Under simple versioning this set will be at most of size 1. Underfull versioning, this set maybe of size greater than 1, indicating amerge within the version graph.
The method
returns the directpredecessor of thisalong the same line of descent returned byin the current workspace (see §3.1.8.2Current Session andWorkspace), orif no such direct predecessor exists. Note that under simpleversioning the behavior of this method is equivalent to getting theunique direct predecessor (if any) of this version.
returns the directsuccessors of this.Under simple versioning this set will be at most of size 1. Underfull versioning, this set maybe of size greater than 1, indicating abranch within the version graph.
The method
returns the directsuccessor of thisalong the same line of descent returned byin the current workspace (see §3.1.8.2Current Session andWorkspace), orif no such direct successor exists. Note that under simpleversioning the behavior of this method is equivalent to getting theunique direct successor (if any) of this version.
The frozen node of aversion is access with
.
Under simpleversioning without in-content version store the frozen node has noparent and therefore methods that depend on a node being within theworkspace tree (,,etc.) throw.Under full versioning a frozen node is the child of anwithin the in-content version store and so has all thecharacteristics of a normal node.
Theinterface extends.Under simple versioning, however, versions are not represented bynodes in content, consequently the inherited methods, other than(see §15.2.1.1Version Name), are not required to function.These methods may throw a.Under full versioning the methods ofinherited fromfunction on the actual node in content that backs that version (see§3.13.3.1nt:version).
When a versionablenode is checked in, it and its subgraph becomeread-only. Theeffect of read-only status on a node depends on theon-parent-version (OPV) status of each of its child items.
When a nodebecomes read-only:
No property ofcan be added, removed or have its value changedunless ithas anon-parent-version setting of.
No child node ofcan be added or removedunless it has anon-parent-versionsetting of.
Every existingchild node ofbecomes read-only unless it has anon-parent-version settingofor has anon-parent-version setting ofand is itself versionable.
These restrictionsapply to all methods with the exception of (see §15.7Restoring a Version),(see §15.9Merge) and(see §10.8.3Updating Nodes Across Workspaces).These operations do not respectchecked-in status.
Note thatof a read-only node is possible, as long as its parent is notread-only, since removal is an alteration of the parent node.
A checked-in node ischecked-out using
,
whereis the absolute path of the node.
The checked-out stateindicates to the repository and other clients that the latestversion ofis “being worked on” and will typically be checked-in again atsome point in the future, thus creating a new version.
Onof a node:
Ifis already checked-out, this method has no effect.
Ifis not versionable, anis thrown.
Otherwise,
Theproperty ofis set to.
and all nodes and properties in the subgraph oflose their read-only status.
Under fullversioning, the current value of theproperty ofis copied to theproperty of.
This method is aworkspace-write. There is no need to call.
Only the actualversionable node has aproperty, however, the checked-in read-only effect extends into thesubgraph of the versionable node (see §15.2.2Read-Only onCheck-In). The method
returnsif the node atis read-only due to a check-in operation. The method returnsotherwise.
Alternatively, themethod
can also be useddirectly on the node in question.
The method
is a shortcut forfollowed immediately by.
A version label is aJCR name (see §3.2Names) associated with a version. Aversion may have zero or more labels. Within a given versionhistory, a particular label may appear a maximum of once. Labels aretypically used to add application-level information to a storedversion.
Under simpleversioning labels are added, accessed and removed only through theversion-label-specific API.
Under full versioningversion labels are also exposed in content. Eachnode has a subnode calledof type:
Each version label isstored as aproperty whose name is the label name and whose target is thenode within theto which the label applies. Dereferencing a label property isequivalent to calling.
The method
.
adds the specifiedto the version with the specified.Themust be a JCR name in either qualified or expanded form andtherefore must conform to the syntax restrictions that apply to suchnames. In particular a colon (“”)should not be used unless it is intended as a prefix delimiter in aqualified name (see §3.2.5Lexical Form of JCR Names).
In a full versioningsystem,adds the appropriateto thenode. The addition of a label is a workspace-write and thereforedoes not require a.
If the specified labelis already assigned to a version in this history andisthen the label is removed from its current location and added to theversion with the specified.Ifis,then an attempt to add a label that already exists in this versionhistory will throw a.
The method
returnsif any version in the version history has the given.The method
returnsif the specifiedhas the specified.
The method
returns all theversion labels on all the versions in the version history. Themethod
returns all versionlabels on the specified.
The method
removes the specifiedfrom this version history.
In a full versioningsystem,removes the appropriatefrom the.The change is a workspace-write and therefore does not require a.
In simple versioning,version histories are not searchable from within the JCR API. Inorder to make version histories searchable under JCR, versionstorage must be exposed in content. Since simple versioningrepositoriesmay expose version storage (it is simply notrequired), searchable versions are effectively an optionalextension of simple versioning (see §3.13.7Version Storageand §6Query).
Under full versioning,the exposure of version storage as content in the workspace allowsthe stored versions and their associated version meta-data to besearched or traversed just like any other part of the workspace.
When anornode is acquired through a query or directly through a,the actual Java type of the returned object must be(in the casenodes) or(in the case ofnodes). This allows the application to cast the returned object toeitherorand use it in methods that take those types.
Restoring aversionable node to the state recorded in an earlier version can bedone with
.
Given a versionand a boolean flag,and lettingbe the versionable node in this workspace of whichis a version andbe the frozen node of,on, ifhas unsaved changes pending, anis thrown, otherwise:
Under simpleversioning, ifis checked-in then it is automatically checked-out before theis performed.
Under full versioningthemethods work regardless of whether the node in question ischecked-out or checked-in.
Under both simple andfull versioning, the changes are made through workspace-write andtherefore do not require.
Theprimary type, mixin types and identifier ofare set as follows:
Theproperty of(and, semantically, the actual primary node type of)is set to the value recorded in theof
Theproperty of(and, semantically, the actual mixin node types of) is set to the value(s) recorded in theof.
Theproperty of(and, semantically, the actual identifier of)is set to the value recorded in theof.
For each propertypresent on(other than,and):
Ifhas an OPV oforthenis copied to,replacing any existing.
will never have a property with an OPV of,,or(see §15.2Check-In: Creating a Version).
For each propertypresent onbut not on:
Ifhas an OPV of,orthenis removed. Note that while a node with a child item of OPVcannot be versioned, it is legal for apreviously versioned node to have such a child item added to it andthen for it to be restored to the state that it had before thatitem was added, as this step indicates.
Ifhas an OPV ofthen no change is made to.
Ifhas an OPV ofthen, ifhas a default value (either defined in the node type ofor implementation-defined) its value is changed to that defaultvalue. Ifhas no default value then it is left unchanged.
Ifhas an OPV ofthen the value ofmay be changed according to an implementation-specific mechanism.
An identifiercollision occurs when a node exists outside the subgraph rooted atwith the same identifier as a node that would be introduced by therestore operation. The result in such a case is governed by theflag. Ifis,then the incoming node takes precedence, and the existing node (andits subgraph) is removed (if possible; otherwise ais thrown). Ifis,then anis thrown and no changes are made.
Each child nodeofwherehas an OPV ofandis,is represented innot as a copy ofbut as special node containing a reference to the version history of.On restore, the following occurs.
If the workspacecurrently has an already existing node corresponding to’sversion history and theflag of theis set to,then that instance ofbecomes the child of the restored.
If the workspacecurrently has an already existing node corresponding to’sversion history and theflag of theis set tothen anis thrown.
If the workspacedoes not have an instance ofthen one is restored from’sversion history:
If the restorewas initiated through awhereis the specified label and there is a version ofwith the labelthen that version is restored.
If the versionhistory ofdoes not contain a version with the labelor the restore was initiated by a method call that does notspecify a label then the workspace in which the restore is beingperformed will determine which particular version ofwill be restored. This determination depends on the configurationof the workspace and is outside the scope of this specification.
For each child nodepresent on:
Ifhas an OPV ofor:
is true, thenand its subgraph is copied to,replacing any existingand its subgraphand any node in the workspace with thesame identifier asor a node in the subgraph ofis removed.
is,thenand its subgraph is copied to,replacing any existingand its subgraphunless there exists a node in theworkspace with the same identifier as,or a node in the subgraph of,in which case anis thrown , all changes made by theare rolled back leavingunchanged.
Underfull versioning each child nodeofwherehas an OPV ofandis versionable, is represented innot as a copy ofbut as special node of typecontaining a reference to the version history of.On restore,in the workspace is replaced by a version of.The determination of which version ofto use is implementation-dependent (see §15.7.5Chained Versionson Restore).
In arepository that supports orderable child nodes, the relativeordering of the set of child nodes C that are copied from F ispreserved.
will never have a child node with an OPV of,,or(see §15.2Check-In: Creating a Version).
For each child nodepresent onbut not on:
Ifhas an OPV of,orthenis removed. Note that while a node with a child item of OPVcannot be versioned, it is legal for apreviously versioned node to have such a child item added to it andthen for it to be restored to the state that it had before thatitem was added, as this step indicates.
Ifhas an OPV ofthen no change is made to.
Ifhas an OPV ofthenis re-initialized as if it were newly created, as defined in itsnode type.
Ifhas an OPV ofthenmay be re-initialized according to an implementation-specificmechanism.
Under simpleversioningis automatically checked-in.
Under full versioning theproperty ofis set to(though the other elements of a check-in are not performed).Additionally, theproperty ofis set to.Note that after the next check-out (see §15.3Check-Out) andsubsequent check-in ofthe versionwill acquire an additional direct successor, forming a branch.
The method
takes theobject and a target path. This method only works in cases where nonode exists at.It is used to restore nodes that have been removed or to introducenew subgraphs into a workspace based on state stored in a version.
The method
takes a version nameinstead of the actualobject. The version to be restored is identified by name from withinthe version history of the node at.This method requires that the node atexist and be a versionable node.
Themethod
takes a version labelinstead of aobject (see §15.2.1Version Object). The version to berestored is identified by label from within the version history ofthe node at.This method requires that the node atexist and be a versionable node.
The method
is used tosimultaneously restore multiple versions. This may be necessary incases where sequential restoration is impossible due to a cycle ofproperties in the nodes to be restored.
In someimplementations it may be possible to remove versions from within aversion history using.In such cases the version graph must be automatically repaired sothat the direct successor of the removed version becomes the directsuccessor of the direct predecessor of the removed version.
The method
removes the namedversion from this version history and automatically repairs theversion graph. If the version to be removed is,'sdirect predecessor set isand'sdirect successor set is,then the version graph is repaired s follows:
For each memberof,remove the reference tofrom its direct successor list and add references to each member of.
For each memberof,remove the reference tofrom its direct predecessor list and add references to each memberof.
This change is aworkspace-write; there is no need to call.
The method
performs the firststep in amerge of two corresponding nodes:
Themethod can be called on a versionable or non-versionable node.
Like,does not respect the checked-in status of nodes. Amay change a node even if it is currently checked-in.
Ifnode (the one on whichis called) does not have a corresponding node in the indicatedworkspace, then themethod returns quietly and no changes are made.
Ifisandnode, despite having a corresponding node, is neverthelessnon-versionable then the merge method also returns quietly and nochanges are made.
Otherwise, thefollowing happens:
Ifisthen a merge test is performed onnode, call it.If isthen a merge test is performed recursively on each versionable node,within the subgraph rooted atnode.
The merge test is performed bycomparingwith its corresponding node in,call it.
The merge test is done by comparingthe base version of(call it)andthe base version of(call it).
For any versionable nodethere are three possible outcomes of the merge test:update,leave orfailed.
Ifdoes not have a corresponding node then the merge result forisleave.
Ifis currently checked-in then:
Ifis an eventual successor of,then the merge result forisupdate.
Ifis an eventual predecessor ofor ifandare identical (i.e., are actually the same version), then the mergeresult forisleave.
Ifis neither an eventual successor of, eventual predecessor of, noridentical with,then the merge result forisfailed. This is the case whereandrepresent divergent branches of the version graph.
Ifis currently checked-out then:
Ifis an eventual predecessor ofor ifandare identical (i.e., are actually the same version), then the mergeresult forisleave.
If any otherrelationship holds betweenand,then the merge result forisfail.
Ifisthen the first time a merge result offail occurs, the entiremerge operation on this subgraph is aborted, no changes are made tothe subgraph and ais thrown. If no merge result offail occurs then:
Each versionablenodewith resultupdate is updated to reflect the state of.The state of a node in this context refers to its set of propertiesand child node links.
Each versionablenodewith resultleave is left unchanged,unlessis the child of a node with statusupdate anddoes not have a corresponding node in,in which case it is removed.
Ifisthen:
Each versionablenodewith resultupdate is updated to reflect the state of.The state of a node in this context refers to its set of propertiesand child node links.
Each versionablenodewith resultleave is left unchanged, unlessis the child of a node with statusupdate anddoes not have a corresponding node in.I such a case,is removed.
Each versionablenodewith resultfailed is left unchanged except that theidentifier of(which is, in some sense, the “offending” version; the one thatcaused the merge to fail on that)is added to the multi-valuepropertyof.If the identifier ofis already in,it is not added again. Theproperty never contains repeated references to the same version. Iftheproperty does not yet exist then it is created. If present, theproperty will always contain at least one value. If not present ona node, this indicates that no merge failure has occurred on thatnode. Note that the presence of this property on a node will in anycase prevent it from being checked-in because thesetting ofis.
This property canlater be used by the application to find those nodes in thesubgraph that have failed to merge and thus require specialattention (see §15.9.2Merging Branches). This property ismulti-valued so that a record of successive failed merges can bekept.
In either case, (regardless of whetherisor)for each non-versionable node (including both referenceable andnon-referenceable), if the merge result of itsnearestversionable ancestor isupdate,or if it hasnoversionable ancestor, then it is updated to reflect the state ofits corresponding node. Otherwise, it is left unchanged. Thedefinition of corresponding node in this context is the same asusual: the match is done by identifier.
Note that a deepperformed on a subgraph with no versionable nodes at all (or indeedin a repository that does not support versioning in the first place)will be equivalent to an update.
Themethod returns aover all versionable nodes in the subgraph that received a mergeresult of fail.
Note that ifis,then merge will either return an empty iterator (since no mergefailure occurred) or throw a(on the first merge failure that was encountered).
Ifis,then the iterator will contain all nodes that received a fail duringthe course of this merge operation.
All changes made byare workspace-write, and therefore this method does not require a.
The above declarativedescription can also be expressed in pseudo-code as follows:
letbe the workspace against which theis done.
letbe the flag passed to.
letbe the flag passed to.
letbe a set of identifiers, initially empty.
letbe the node on whichwas called.
.
returnthe nodes with the identifiers in.
letbe the corresponding node ofin.
if no such.
else ifis not versionable.
else ifis not versionable.
letbe base version of.
letbe base version of.
ifis an eventual successor ofand
is not checked-in.
else ifis equal to or an eventual predecessor of.
else.
if=throw. else add identifier of(if not already present) to the
property of,
add identifier ofto,
if=
for each versionable child nodeof.
if=
for each child nodeof.
replace set of properties ofwith those of.
letbe the set of child nodes of.
letbe the set of child nodes of.
judging by the name of the child node:
letbe the set of nodes inand in
letbe the set of nodes inbut not in.
letbe the set of nodes inbut not in.
remove fromall child nodes in.
for each child node ofincopy it (and its subgraph) to as a new child node (if an incoming node has the same
identifier as a node already existing in this workspace,
the already existing node is removed).
for each child nodeofin.
When a merge test on anodefails, this indicates that the two base versionsandare on separate branches of the version graph. Consequently,determining the result of the merge is not simply a matter ofdetermining which version is the eventual successor of the other interms of version history. Instead, the subgraph ofmust be merged into the subgraph ofaccording to some domain specific criteria which must be performedat the application level, for example, through a merge tool providedto the user.
Theproperty is used to tag nodes that fail the merge test so that anapplication can find them and deal appropriately with them. Theproperty is multi-valued so that information about merge failures isnot lost if more than one successive merge is attempted before beingdealt with by the application.
After the subgraph ofis merged into,the application must also merge the two branches of the versiongraph. This is done by callingwhereis retrieved by following the reference stored in theproperty of.This has the effect of moving the reference-to-from theproperty ofto itsproperty.
If, on the other hand,the application chooses not to join the two branches, thenis performed. This has the effect of removing the reference tofrom theproperty ofwithout adding it to.
Once the lastreference inhas been either moved to(with)or just removed from(with)theproperty is automatically removed, thus enabling this node to bechecked-in, creating a new version (note that before theis removed, itssetting ofprevents check-in). This new version will have a direct predecessorconnection to each version for whichwas called, thus joining those branchesof the version graph.
All changes made byandare workspace-write and therefore do not require.
In repositories thatsupport activities (see §15.12Activities) merging anactivity into another workspace is done with the method
.
(see §15.12.7Mergingan Activity into Another Workspace).
Serialization ofversion information can be done in the same way as normalserialization by serializing the subgraph below.The special status of these nodes with respect to versioning istransparent to the serialization mechanism.
The serialized contentof the source version storage can be imported as “normal”content on the target repository, but it will not actually beinterpreted and integrated into the repository as version storagedata unless it is integrated into or used to replace the targetrepository's own version storage.
Methods for doing thiskind of “behind the scenes” alteration to an existing versionstorage (whether based on the serialized version storage of anotherrepository, or otherwise) are beyond the scope of thisspecification.
In a repository thatsupports both versioning and transactions, all versioning operationsmust be fully transactional, meaning that they can be bracketedwithin a transaction and rolled-back just like any other set ofoperations.
Activities provide away of grouping together a set of logically related changesperformed in a workspace and then later merging this set of changesinto another workspace.
Before starting tomake a particular set of changes, the user sets the currentactivity. Each subsequentmade within the scope of that activity will associate that activitywith that checked-out versionable, and will create a version that istagged with the specified activity when that versionable issubsequently checked-in.
Abstractly, therefore,an activity is a set of changes that produce new versions. However,if that set includes changes that produce more than one versionwithin a particular version history, then those versions must all beon the same line of descent, that is, there must be a non-branchingsequence of direct successor relationships beginning at the rootversion of the version history that reaches every version in theset. This ensures that there is always at most one “latest”version that contains all changes in a given version history for agiven activity.
Support for activitiesis an optional addition to the full versioning feature. Animplementation that supports versioningmay supportactivities.
Whether a particularimplementation supports activities can be determined by querying therepository descriptor table with
.
A return value ofindicates support for activities (see §24.2RepositoryDescriptors).
Activities arerepresented by nodes of node type:
mandatoryautocreated protected
The relationshipbetween version and activity is modeled by the property,in theandnode types:
Activities arepersisted as nodes of typeunder system-generated node names in activity storage below.
The organization ofthis subgraph is left up to the implementation (for example, theremay be intervening nodes structuring the activity storage).
Similar to thesubgraph, the activity storage is a single repository wide store,but is reflected into each workspace. However access control may beemployed so that different sessions see different parts of the tree.
The activity storagesubgraph is not writable through the core write methods (see §10.2Core Write Methods). It can only be altered through theactivity-specific write methods described in this section.
Activities are createdusing:
creates a newnode at an implementation-determined location in subgraph andreturns it.
The name of thenode is automatically generated by the repository. The repositorymay use theparameter as a hint to give a value to theproperty of the new node. The new node addition is dispatchedimmediately and therefore does not require a.
is called by the userto set the current activity on the session by specifying apreviously creatednode. Changing the current activity is done by callingagain. Cancelling the current activity is done by callingand results in the session having no current activity. The methodreturns thepreviously setnode orif no such node exists.
Assuming,
the currentactivity of sessionis represented by nodeand
nodeis a versionable node with version history,
then eachof nodemade throughwhileis in effect causes the following:
If there exists another workspacewith nodewherealso has version history,is checked out and theproperty ofreferences,then the check-out fails with anindicating which workspace currently has the check-out.
If there is a version inthat is not an eventual predecessor ofbut whosereferences,then the check-out fails with an.
Otherwise, theproperty ofis set to referenceand whenis subsequently checked in, theproperty of the new version is set to reference,and theproperty ofis removed.
The method
returns the noderepresenting the current activity orif there is no current activity.
Once an activity hasbeen completed, the changes that it records can be imported intoanother workspace. This is done with a variant of the merge method:
This method merges thechanges that were made under the specified activity intoworkspace.
An activitywill be associated with a set of versions through thereference of each version node in the set. We call each suchassociated version a member of.
For each versionhistorythat contains one or more members of,one such member will be the latest member ofin.The latest member ofinis the version inthat is a member ofand that has no eventual successor versions that are also members of.
The set of versionsthat are the latest members ofin their respective version histories is called the change set of.It fully describes the changes made under the activity.
This method performs ashallow merge, withequal to,into this workspace (see §15.9Merge) of each version in thechange set of the activity specified by.If there is no corresponding node in this workspace for a givenmember of the change set, that member is ignored.
This method returns aover all versionable nodes in the subgraph that received a mergeresult offail (see §15.9.1Merge Algorithm).
All changes madethrough this method are workspace-write and therefore do not require.
Somerepositories may support
whichremoves the specified activity node from the activity storage andautomatically removes allproperties referring to that node in all workspaces, with theexception ofproperties in version storage. The existence of ato the activity node from within version storage will cause anexception to be thrown. Changes made through this method areworkspace-write and therefore do not require.
Aconfigurationis the subgraph of a specifically designated versionable node(called theconfiguration root node) in a workspace, minusany parts of that subgraph that are themselves designated asconfigurations. Abaseline is the state of a configuration atsome point in time, recorded in version storage as a version object.
Support forconfigurations and baselines is an optional addition to the fullversioning feature. An implementation that supports full versioningmay support configurations and baselines. Whether aparticular implementation supports configurations and baselines canbe determined by querying the repository descriptor table with
.
A return value ofindicates support for configurations and baselines (see §24.2Repository Descriptors).
Each configuration ina given workspace is represented by a distinctproxy node oftypelocated inconfiguration storage within the same workspaceunder.The configuration storage in a particular workspace is specific tothat workspace. It is not a common repository-wide store mirroredinto each workspace, as is the case with version storage.
The proxy node of aconfiguration is used to perform certain operations on thatconfiguration. In particular, version operations performed on theproxy node act not only on that node itself but also on theconfiguration it represents, as a whole. Creating a baseline, forexample, is done by performing aon a configuration’s proxy node.
Every configurationproxy node is of type:
mandatoryautocreated protected
This node type is asubtype ofand adds a single property, theproperty,which points to the root node of the configuration that this proxyrepresents.
Since everyconfiguration proxy node is versionable, each has a version history.The versions within this history store state information aboutconfiguration represented by the proxy node, in addition toinformation about the proxy node itself.
The organization ofconfiguration storage is left up to the implementation (for example,there may be intervening nodes structuring the storage). It isexpected that access control will also be employed to ensure thatonly sessions with appropriate authorization may create or haveaccess to particular configurations.
A configuration iscreated by designating anodein the workspace as a configuration root node. This is done bycalling
whereis the path of.
On creation of a newconfiguration with root,a new proxy node,of type,is created underand a new version historyis created forwith a root version.Note thatis also called abaseline history and its contained versions,including,are calledbaselines. The baselines withinstore not only the state ofbut also the state of the configuration represented by(see 15.13.4.1Creating a Baseline).
The properties ofandare initialized as follows:
points to.
points to.
points to.
Thecall will fail if
the node atis not.
the node atis already a configuration root (i.e., if it already has aproperty).
There exists inthe subgraph ata versionable node that has never been checked-in (i.e., one whosebase version is still its root version).
Themethod is workspace-write. Therefore the changes it makes aredispatched immediately and ais not required.
A baseline records thestate of a configuration at some particular time and is representedby a version (i.e., annode) of thenode in question.
A baseline is createdby performing aon a configuration proxy node (i.e., a node of typefound in configuration storage). Note that sinceis subtype of,a configuration node will have its own version history,distinctfrom the version history of its configuration root node.
Onof the configuration proxy node:
The state of theis recorded in a new baselinejust as it would be in a normal version.
In addition, thecurrent base version of every versionable node in the configurationis also recorded.
How the configurationstate information is stored is up to the repository. It need not bestored as content in the substructure of thenode. For example, some repositories are likely to have someefficient internal mechanisms involving lists of identifiers,possibly stated as a delta against the direct predecessor baseline.The only requirement is that baselines be “restoreable”.
Using the method
whereis a baselineobject, is thenode whose version history containsandis the configuration root node pointed to by:
The state ofis restored to the state recorded inandis set to point to(as in the restore of any normal version).
Each versionablenodein the subgraph below and includingis restored to the state recorded inwhereis the version ofin’sversion history that was recorded in(i.e., the base version ofat the timewas created).
Theparameter behaves just as in a normal restore expect that that itapplies to all nodes restored below.The same behavior applies for the multi-version signature ofrestore,
except that multiplebaselines may be restored simultaneously.
The method
,
whereis a baselineobject andis a path to a location where no node exists but which has asuitable parent node, creates a new configuration atby restoring the baseline.A configuration proxy nodewithpointing to the root node of the new configuration atis automatically created in configuration storage. If a node alreadyexists at,the method fails. The variant signatures
,
and
,
work identicallyexcept that the baseline to be restored is identified either by nameor by label instead of being passed in as aobject.