A repository may bewritable.
Whether animplementation supports writing can be determined by querying therepository descriptor table with
.
A return value ofindicates support (see §24.2Repository Descriptors).
A JCR write method iseither asession-write or aworkspace-write.
Changes made through asession-write are buffered in a transient store associated with thatmethod's current session (see §3.1.8.2Current Session andWorkspace). The transient store permits a series of changes tobe made without validation at every step, thus allowing itemstructures to be temporarily invalid while they are beingconstructed. Once completed, the change set can besaved.
Before save, achange in transient store ispending.
Upon save, allchanges in transient store aredispatched.
A change madethrough a workspace-write is immediatelydispatched.
In the absence ofa transaction, everydispatched change is immediatelypersisted.
Within atransaction, dispatched changes are persisted uponcommit.
(see §21Transactions).
A change that ispendingordispatched (but notpersisted) isvisible only to the session through which that change was made. Achange that ispersisted is visible to all other sessionsbound to the same persistent workspace that have sufficient readpermission.
The write API isdivided into the two types as follows.
The session-writemethods are
,and.
..
..
,and.
,and.
.
,and.
,,and.
and.
The workspace-writemethods are:
,,,and.
,,,,,,,,,and.
and.
and.
,and.
.
Methods ofacquired through.
and(these create or delete another workspace, though they do notaffectthis workspace).
Some repositories maychoose to expose internal state data as virtual content within aworkspace. For example, the set of registered node types may be soexposed.
In such cases, methodswhich directly affect the exposed internal state and, as a sideeffect, change virtual content must do so in a workspace-writemanner. For example,andshould immediately dispatch changes to the in-content node typerepresentation.
Thecore write methodsof JCR are those write methods of the API whose write effect isnotincidental to the support of another feature, such as versioning,import, locking, and so forth. Both session-write andworkspace-write methods are among the core write methods. The corewrite methods are:
,and.
..
..
,and.
,and.
,,.
.
Given the setS0..Snofobjects bound to a persistent workspaceWP,for eachSi, there exists a distinctobjectWi,bound one-to-one toSi,that represents theview ofWPthrough the access permissions ofSi.
Despite theirone-to-one correspondence,andare defined as separate objects in order to differentiate thebehavior of session-write methods from the behavior ofworkspace-write methods.
The following diagramdepicts the behavior of write methodswithout a transaction.
The following diagramsdepicts the behavior of write methodswithin a transaction.
This section coversthe JCR API methods for adding new nodes and properties and changingthe values of existing properties.
The methods
and
add a node at thespecified location relative to this.The former specifies the intended primary node type of the node,while the latter assumes that the repository can determine theintended type from the node type of the parent.
is asession-write method and therefore requires ato dispatch the change (see §10.11Saving).
The generic method forsetting a property is
.
This method sets theproperty of thiswith the specifiedto the specified value and the specified type, converting the givenvalue to that type if necessary. If the property already exists itsvalue is changed. If it does not exist, it is added.
is asession-write method and therefore requires ato dispatch the change (see §10.11Saving).
An existing propertycan also be changed with
.
is asession-write method and therefore requires ato dispatch the change (see §10.11Saving).
Signatures ofandare also provided in which the intended JCR type is implied by theJava type passed in. For example,
sets a JCRproperty calledto the specified.See the Javadoc for the full set of signatures.
When setting aproperty of typeusing
or
theobject passed must be an instance of the actual class,not an instance of a subclass.
Every property musthave a value. The range of property states does not include having a“null value”, or “no value”. Setting a property to “null”is equivalent to removing that property (see §10.9RemovingNodes and Properties).
As with single-valueproperties, there is no such thing as a null value. If a valuewithin a multi-value property is set to null, this is equivalent toremoving that value from the value array. In such a case the arrayis automatically compacted, shifting the indices of those valueswith an index greater than that of the removed value by -1. However,while no value within a multi-value property can be null, amulti-value property can exist with no values (i.e., it can be anempty array).
Multi-value andsingle-value properties are set using different signatures ofand.Multi-value properties must be set using the signatures that takeeither aor.Single-value properties must be set using the signatures that takenon-array value arguments. An attempt to set a multi-value propertywith a non-array value argument, or a single-value property with anarray value argument, will throw a.
In many cases aproperty must be set using aobject.objects are created using a,acquired through
.
The genericcreation method is
which takes thestring-form of the specified type and returns aof that type using standard property type conversion (see §3.6.4Property Type Conversion).
also provides methods for creating values of each property type fromthe corresponding Java type. See the Javadoc for the full set ofsignatures.
To create avalue aobject is first created from a stream using
and then passed to
.
Anormethod must determine which, if any, item definitions of the parentnode apply to the new child item, based on the name of the new itemand, if provided, its type.
If more than one itemdefinition still applies even after taking the name and typeconstraints into consideration, the repository may either fail theadd attempt or automatically select one of the item definitionsbased on implementation-specific criteria.
For example, if theparent nodehas two residual child node definitions that differ only by theirOPV value (see §3.7.2.5On-Parent-Version), then even ifboth a name and a primary type are supplied in the call tothis will not be sufficient informationto unambiguously determine which residual definition the new nodeshould fall under. In such a case, an implementation mightautomatically select one of the definitions based on theimplementation-specific rule that a node with the nameX willalways have an OPV ofV while other nodes will have an OPV ofW.
Whenis used to change the value of an existing property, cases where theintended property is ambiguous are handled in the same way as whenthe method is used to create a new property.
The method
moves the subgraph atto a new location at.This is a session-write operation (see §10.1.1Session-Write).The method
does the same, but isa workspace-write operation (see §10.1.1Workspace-Write).
A referenceable nodeis guaranteed to maintain the same identifier across aoperation.
Non-referenceablenodes, on the other hand,may be tied either partially orentirely (as in the case where the identifier equals the path) totheir position in the hierarchy and therefore may change identifierupon.
Though nothingprevents an implementation from making non-referenceable nodeidentifiers as stable as referenceable node identifiers, a usercannot rely upon this across repository vendors. For an overview ofhow identifiers behave with different methods see §25.1Treatmentof Identifiers.
Nodes can be copiedfrom one path location to another within a workspace and, inrepositories with more than one workspace, across workspaces (see§3.10Multiple Workspaces and Corresponding Nodes). A copyoperation on a node copies the node and its subgraph. Propertiescannot be copied individually.
The method
copies the node atand its subgraph to a new location at.This is a workspace-write operation (see §10.1.1Workspace-Write).
In a repository withmore than one workspace, the method
copies the node atinand its subgraph to a new location atin the current workspace. This is a workspace-write operation (see§10.1.2Workspace-Write).
When a nodeis copied to a path location where no node currently exists, a newnodeis created at that location. The subgraph rooted at and including(call it)is created and is identical to the subgraph rooted at and including(call it)with the following exceptions:
If the copy iswithin the same workspace, every node inis given a new and distinct identifier.If the copy is to another workspace, every referenceable node inis given a new and distinct identifier while everynon-referenceable node inmay be given a new and distinct identifier (see §3.8Referenceable Nodes).
The repositorymay automatically drop anymixin node typepresent on any nodein.Dropping a mixin node type in this context means that whileremains unchanged, its copywill lack the mixinand any child nodes and properties defined bythat are present on.For example, a nodethat ismay be copied such that the resulting nodewill be a copy ofexcept thatwill not beand will not have any of the properties defined by.In order for a mixin node type to be dropped it must be listed byname in theproperty of.The resultingproperty ofwill reflect any change.
If a nodeinis referenceable and itsmixin isnot dropped on copy, then the resultingproperty ofwill reflect the new identifier assigned to.
Eachorpropertyinis copied to its new locationin.Ifreferences a nodewithinthen the value ofwill be the identifier of,the new copy of,thus preserving the reference within the subgraph (see §3.8Referenceable Nodes).
Whena nodeis copied to a location where a nodealready exists the repository may either immediately throw anor attempt to update the nodeby selectively replacing part of its subgraph with a copy of therelevant part of the subgraph of.If the node types ofandare compatible, the implementation supports update-on-copy for thesenode types and no other errors occur, then the copy will succeed.Otherwise anis thrown.
Whichnode types can be updated on copy and the details of any suchupdates are implementation-dependent. For example, someimplementations may support update-on-copy for mix:versionablenodes. In such a case the versioning-related properties of thetarget node would remain unchanged (,,etc.) while the substantive content part of the subgraph would bereplaced with that of the source node.
A node can beclonedto another workspaces to create a new corresponding node (see §3.10Corresponding Nodes)
Corresponding nodescan be created bycloning a node from one workspace toanother using:
This method clones thesubgraph atintoinworkspace. Themethod clones both referenceable and non-referenceable nodes andpreserves the identifier of every node in the source subgraph.
If there alreadyexists anywhere in this workspace a node with the same identifier asan incoming node from,andis,thenwill throw an.
Ifisthen the existing node is removed from its current location and thecloned node with the same identifier fromis copied to this workspace as part of the copied subgraph (that is,not into the former location of the old node). The subgraph of thecloned node will reflect the state of the clone in,in other words the existing node will be movedand changed.If the existing node cannot be moved and changed because of nodetype constraints, access control constraints or because its parentis checked-in (or its parent is non-versionable but its nearestversionable ancestor is checked-in), then the appropriate exceptionis thrown (,or,respectively).
In the case ofshareable nodes, it is possible to clone a node into its ownworkspace (see §14.1Creation of Shared Nodes).
Finding the path of anode's corresponding node in another workspace is done with
.
This method returnsthe absolute path of the node in the specified workspace thatcorresponds to this node.
Node correspondencegoverns the behavior of themethod:
causesnode to be updated to reflect the state of its corresponding node in.
If this node does havea corresponding node in the workspace,then this replaces this node and its subgraph with a clone of thecorresponding node and its subgraph.
If this node does nothave a corresponding node in,then the method has no effect.
If thesucceeds, the changes made to this node and its subgraph are appliedto the workspace immediately, there is no need to call.
Themethod does not respect the checked-in status of nodes. Anmay change a node even if it is currently checked-in.
works for both versionable and non-versionable nodes (see §3.13Versioning Model)
Removing a node orproperty can be done with
On the item to beremoved itself, or
Wherespecifies the item to be removed.
These methods aresession-write and therefore require ato dispatch the change.
A property can also beremoved by setting its value to.When this is done, theparameter must be cast to a non-array type for single-valueproperties and an array type for multi-value properties.
Note that setting amulti-value property to an array containingvalues is different from setting it to acast to an array type. In the former case, allvalues within the array are removed and the array is compacted toinclude only non-null values even if this results in a multi-valueproperty being set to an empty array. In the latter case the entireproperty is removed. For example,
would remove property,whereas
would settoand
would setto the empty array,(see §10.4.2.4No Null Values).
To remove a node thatis the target of aproperty, one must first remove thatproperty (with the exception ofproperties within the frozen node of a version, see §3.13.4.6References in a Frozen Node).
The check forreferential integrity is doneon persist of the removal. Ifthe subgraph to be removed contains a node that is the target of aproperty outside that subgraph, ais thrown.
Most writablerepository implementations will support assignment of primary andmixin node types on node creation. Some implementations may alsosupport assignment of new primary or mixin node types to existingnodes.
Onthe primary node type of the new node is assigned. In cases where adoes not explicitly specify a primary node type, it is determined bythe applicable child node definition (see §3.7.7Applicable ItemDefinition). Otherwise, it is determined by the node type namepassed. Theproperty is created immediately and set to the name of the primarynode type. This property is defined asin the node type(see §3.7.10Base Primary Node Type) and will thereforeappear on every node.
The constraintsenforced by the assigned node type may take effect immediately, oron persist. Whichever is chosen, thisnodetype assignmentbehavior must be consistent across all methods that assign nodetypes (,and,see §10.10.2Updating a Node's Primary Type and §10.10.3Assigning Mixin Node Types).
Ifimmediate effectis implemented then conflicts with other mixins or with the primarytype are detected immediately and an exception thrown. Ifon-persisteffect is implemented, such conflicts are detected and theappropriate exception thrown on persist. This validation can also beperformed pre-emptively with
.
A repositorymaypermit the primary type of a node to be changed during its lifetime.Repositories are free to limit the scope of permitted changes bothin terms of which nodes may be changed and which changes areallowed.
The method forchanging the primary type of a particular node is
.
This method changesthe primary node type of the node to,and immediately changes theproperty of the node appropriately.
Semantically, the newnode type takes effect in accordance with thenode typeassignment behavior of the repository (see §10.10.1NodeType Assignment Behavior).
In addition to itssingle primary node type, a node may have one or more mixin nodetypes assigned to it (see §3.7.5Mixin Node Types).Assignment of mixin types is done through
.
A repository thatsupports the assignment of mixin types may permit mixin additiononly before the first save of a node (in effect, only on nodecreation) or it may permit mixin addition and removal during thelifetime of a node. Removal of mixin node types is done with
.
When a new mixin typeis assigned using,the name of the mixin is added immediately to the multi-valuedproperty. If the property does not exist, it is created. Thisproperty is defined as non-mandatory in the node typeand therefore may appear on any node. When a mixin is removed withthe name of the mixin type is immediately removed from the property.
Semantically, anychanges to mixin node types take effect in accordance with thenodetype assignment behavior of the repository (see §10.10.1NodeType Assignment Behavior).
Aobject can be queried to pre-emptively determine whether aparticular child item's addition or removal is allowed by that nodetype. The methods are:
A repository mayautomatically assign a mixin type to a node upon creation. Forexample if, as a matter of configuration, allnodes in a repository are to be versionable, then the repository mayautomatically assign the mixin typeto each such node as it is created.
Similarly, arepository may automatically strip incoming imported nodes of anymixin node types that the repository does not support (see §11.3Respecting Property Semantics).
Note that thisbehavior is distinct from that of adding a mixin type as a supertypeof some primary types in the node type inheritance hierarchy (see§3.7.16.1.2Additions to the Hierarchy). Though the twofeatures may both be employed in the same repository, they differ inthat one affects the actual hierarchy of the supported node types,while the other works on a node-by-node basis.
When a change is madeto an item through a session-write method bound to a sessionS,that change is immediately visible through all subsequent readmethod calls throughS. When
is performed onS,all pending changes recorded inS are dispatched. Withouttransactions this causes the changes to be persisted. Within atransaction the changes must first be committed in order to bepersisted. When a change is persisted it becomes visible to othersessions bound to the same persistent workspace.
From the point of viewof a sessionS, the apparent state of anbound toS does not change upon aofS (apart from the values returned byor,see §10.11.3Item Status) since that state will have beenvisibleto S since the session-write method call that causedit.
If one or more of thepending changes cause an exception to be thrown on,thenno pending changes are dispatched and the set of pendingchanges recorded on the session is left unaffected.
The method
refreshes the state ofthe transient session store.
Ifis,all pending changes in the session are discarded and all items boundto that session revert to their current dispatched state. Withouttransactions, this is the current persisted state. Within atransaction, this state will reflect persistent storage as modifiedby changes that have been saved but not yet committed.
Ifisthen pending changes are not discarded but items that do not havechanges pending have their state refreshed to reflect the currentpersisted state, thus revealing changes made by other sessions.
If an exception occurson,the set of all pending changes recorded on the session is leftunaffected and the state of all boundsis also unaffected.
The method
is used to determineif a session holds pending changes.
Whether anhas pending changes can be determined with
.
Whether anconstitutes part of the pending changes of its parent can bedetermined with
..
When a change to anitem is persisted, the item in the persistent workspace to whichthat pending change is written is determined as follows:
If the changedis awith identifierI, then the changes are written to thepersistent node with identifierI.
If the changedis anamedP of awith identifierI, then the change is written to thepersistent propertyP of the persistent node with identifierI.
These principles applyto both referenceable and non-referenceable nodes (see §3.8Referenceable Nodes). For an overview of how identifiersbehave with different methods see §25.1Treatment ofIdentifiers.
For session-writemethods, implementers have flexibility in deciding whether aparticular validation is to be performed immediately on invocationof the write method or later on persist. For example, in the case,an implementer might immediately check that the path given is validwhile postponing validation of node type constraints untilpersist-time.
It issuggestedthat an implementation perform each validation as soon as possible,given the underlying design of the repository.
It isrequiredthat an implementation prohibit the emergence of a persistent statein violation of the validation rules defined by this specification.
If an item has beenmodified in thebut not yet persisted, and its corresponding item in the persistentworkspace is altered through a workspace-write method, this has noeffect on the transient state of the.The altered item in theremains and may be persisted later. However, the change made to theworkspacemay render the attempt to persist thesession-change invalid (for example, if the workspace-change removedthe parent of the session-change item). Note that this is preciselythe same situation as would arise if a change were made to aworkspace throughanother.In both cases the persist of the change may throw an.
When changes are madeto anobject, those changes are recorded in its boundand immediately reflected in theobject itself. A subsequent re-retrieval of the same item entitythrough a method bound to the same,will return anobject reflecting the recent change. Note that this includesacquisition of nodes and properties through standard getter methodssuch asand also retrieval through other means, such as a query (see §6Query).
Whether the secondobject is the same actual Java object instance as the first is animplementation issue. However, the state reflected by the objectmust at all times be consistent with any otherobject bound to the samethat represents the same actual item entity. The criteria of itemidentity in this context are those described in §10.11.4Persistingby Identifier.
Anobject may become invalid for a number of reasons.
Ifhas been called on the item any subsequent calls to any read orwrite methods or invocations oforon that,from within the same,will throw an.Before the removal is saved it may be cancelled by a.At this point the invalidobject may become valid again, or the repository may require a newobject to be acquired. Which approach is taken is a matter ofimplementation.
Anmay be thrown immediately on a write method of anif the change being made would, upon persist, conflict with a changemade and persisted through another.If detection of the conflict is only possible at persist-time, thenanwill be thrown at that point. Whether a conflict is detected whenthe change is made or on persist depends on the implementation.
Apart from thesespecific cases, the validity of anmust be as stable as theidentifiers used in the repository(see §3.3Identifiers).
Transient storage ofpending changes in amay be implemented a number of ways. A repository is free to use anyapproach as long as it guarantees that twoobjects bound to the samewill never reflect conflicting state information.
A repository has asingle namespace registry (see §3.5.1Namespace Registry)represented by theobject, acquired through
.
allows for persistent changes to namespaces through the followingmethods.
sets a one-to-onemapping betweenandin the global namespace registry of this repository.
Assigning a new prefixto a URI that already exists in the namespace registry erases theold prefix. Apart from the XML restriction (see §10.9.3NamespaceRestrictions) this can almost always be done, though animplementation is free to prevent particular remappings by throwinga.Re-assigning an already registered prefix to a new URI in effectunregisters its former URI.
The method
removes a namespacemapping from the registry.
The followingrestrictions apply to registering, re-registering and unregisteringnamespaces:
To avoidconflicts with XML , attempting to register a prefix that beginswith the characters “xml” (in any combination of case) willthrow a.
Attempting tore-assign or unregister a built-in prefix (,,,,,or the empty prefix) will throw a.
An attempt tounregister a namespace that is not currently registered will throwa.
An implementationmay prevent the re-assignment or unregistration of any prefixes forimplementation-specific reasons by throwing a.
The following methodsprovide information about the state of the registry:
returns all currentlyregistered prefixes.
returns all currentlyregistered URIs.
returns the URIcurrently mapped to the given.
returns the prefixcurrently mapped to the given.
The repositorynamespace registry serves as the default mapping and is copied to asession's internal mapping table on session creation. The mappingscan then be changed independently of the registry within the scopeof that session. The methods shown here affect and report only thestate of the central registry. Existing local namespace mappingswill not be affected by changes to the persistent namespaceregistry.