heabove diagram depicts a repositorywith workspaces,and.The item graph ofcontains a root node with child nodes,and.has a propertyof typeand a child node,which in turn has a propertyof type.has the properties(a)and(a).has a propertyof type.
This section describesthe objects, types and structures that compose a JCR repository. Thedescription is language-neutral and focuses on the static aspects ofthe data model. Discussion of the behavioral aspects of therepository, and in particular the Java API for performing operationson the model, is found in subsequent sections. The full repositorymodel is described here, though an implementation may support only asubset of this model, in accordance with §24 RepositoryCompliance.
A JCRrepositoryis composed of one or morepersistent workspaces, eachconsisting of a directed acyclic graph ofitems where theedges represent the parent-child relation.
Each persistentworkspace is identified by a unique name within the repository,which is a string.
An item is either anode or aproperty. A node can have zero or more childitems. A property cannot have child items but can hold zero or morevalues.
The nodes of aworkspace form the structure of the stored data while the actualcontent is stored in the values of the properties.
Each workspacecontains at least one item, theroot node. The root node isthe only item in the workspace without a parent node; all otheritems have at least one parent.
In the simplest case,a workspace is atree of items. However, strictly speaking,the more general termgraph should be used to cover thosecases where a repository supports the optionalshareable nodesfeature, which allows an item to have more than one parent (see §3.9Shareable Nodes Model).
The name of the rootnode of a workspace is always ““ (the empty string). Every otheritem in a workspace has a name, which must be aJCR name(see§3.2Names).
In the simplest case,every child item of a given parent has a unique name. However, childnodes with identical names can only occur if a repository supportssame-name siblings(see §22Same-Name Siblings).Additionally, some repositories may support a node and siblingproperty having the same name (see §5.1.8Node and Property withSame Name). However, two sibling properties can never have thesame name.
To distinguish siblingnodes with the same name an integer index, starting at 1, is used.A node with no same-name siblings has an implicit index of 1 and anode name without an index is understood to have an index of 1.
The location of anitem in the workspace graph can be described by the path from theroot node to that item. The path consists of the name (and index incases of same-name siblings) of each interceding node in order fromroot to target item, much like a file system path. Relative pathscan also be used to describe the location of one item with respectto another (see §3.4Paths).
In addition to a path,every node also has an identifier. In some implementations, theidentifier may be independent of the path and provide an identity tothe node that is stable across moves within the workspace. Insimpler repositories the identifier may be implemented as areflection of the path and therefore not provide any additionalsemantics (see §3.3Identifiers).
Properties can beeither single or multi-valued. Each value has one of the 12 possibletypes (see §3.6Properties). These types include familiardata storage types such as strings, numbers, booleans, binaries anddates, as well as types that hold pointers to other nodes in theworkspace.
T
heabove diagram depicts a repositorywith workspaces,and.The item graph ofcontains a root node with child nodes,and.has a propertyof typeand a child node,which in turn has a propertyof type.has the properties(a)and(a).has a propertyof type.
Every node has a type.A node’s type The names, types and other attributes of its childitems. Node types can be used to define complex storage objectsconsisting of multiple subnodes and properties, possibly many layersdeep.
Auser connectsto a repository by passing a set of credentials and the name of theworkspace that the user wishes to access. The repository returns asession which binds the user to the requested persistentworkspace with a level of authorization determined by that user'scredentials. A session is always bound to exactly one persistentworkspace, though a single persistent workspace may be bound tomultiple sessions.
A user is any agentbound to a session. This may be a human user, an external softwareprocess, or anything else that holds and controls the session.
Through a session, theuser can access, read and write the nodes and properties of thebound workspace, to the extent allowed by that user's authorizationand the capabilities of the repository. Any object acquired,directly, or indirectly through a chain of interceding objects, froma particular session, is said to be within the scope of that sessionand any method called on such object is also within the scope of thesame session.
In the context ofdiscussing a particular object or method call, the session withinwhose scope that object or method call lies is referred to as thecurrent session, and the workspace to which that session isbound is referred to as thecurrent workspace.
AJCR name isan ordered pair of strings:
(N,L)
whereN is aJCR namespace andL is aJCR local name.
AJCR namespaceis either the empty string or a Universal Resource Identifier2.
AJCR local nameis a string that conforms to the grammar below.
JCR names are used toname items, node types and other entities throughout the repository.
Every item has one JCR name. If theitem has more than one parent it has the same name relative to each,though in most cases an item will have only one parent (see §3.9Shareable Nodes Model).
JCR names are combinedinto JCR paths which indicate the location of an item within aworkspace either in relation to the root node or relative to anotheritem in the workspace (see §4.5Workspace).
JCR names appear asthe values ofproperties (see §3.6.1.9NAME) and within the values ofproperties (see §3.6.1.10PATH).
JCR names are used to name node types(see §3.7Node Types).
JCR names are used to identify othertypes of entities such asprivileges,access controlpolicies (see §16Access Control Management),retentionpolicies,holds (see §20Retention and Hold),activities (see §15.12Activities) andconfigurations(see §15.13Configurations and Baselines).
This definition ofJCRname represents theleast restrictive set of constraintspermitted for the naming of items and other entities. A repositorymay further restrict the names of entities to a subset of JCRnames and in most cases is encouraged to do so.
In a read-onlyrepository, any such restrictions will stem trivially from the factthat the repository controls the set of entity names exposed. Awritable repositorymay enforce any implementation-specificconstraint by causing an exception to be thrown on an invalid JCRwrite method call.
The charactersdeclared invalid within a local name (“”,“”,““,“”,“”,“”)represent only those characters which are used as metacharacters inJCR names, paths and name-matching patterns (see §5.2.2IteratingOver Child Items). These restrictions are not necessarilysufficient to enforce best practices in the creation of JCR names.In particular, the minimal grammar defined here permits JCR nameswith leading and trailing whitespace as well as characters which mayappear superficially identical while representing different codepoints, creating a potential security issue.
Though thisspecification does not attempt to define good naming practice,implementers are discouraged from permitting names with these andother problematic characteristics when possible. However, there maybe cases where the latitude provided by the minimal grammar isuseful, for example, when a JCR implementation is built on top of anexisting data store with an unconventional naming scheme.
While a JCR name is anordered pair of strings, (N,L), it is not itself astring. There are, however, two lexical forms (stringserializations) that a JCR name can take when used in the JCR API:theexpanded form and thequalified form. A JCR namethat is converted to either lexical form is said to have beenlexicalized.
The expanded form of aJCR name is defined as:
The qualified form ofa JCR name is defined as:
*/
A qualified name isonly interpretable in the context of anamespace mapping,which provides a one-to-one mapping between prefixes and namespaces.
When a qualified nameQ ispassed to a JCR method within the scope of theS then the JCR nameJ represented byQ is(N,L)whereN is thenamespace corresponding toPin thelocal namespace mapping ofS. See §3.4Namespace Mapping.
When a qualified nameoccurs in a string serialization of repository content or a nodetype definition, the namespace mapping is either provided within theserialized form (see, for example, §7Export and §25.2Compact Node Type Definition Notation) or implied by thecontext of use.
The qualified form ofa name (““,L) (i.e., with the empty string as namespace)is not written as
L
but simply as
L
The former is not avalid qualified JCR name.
An implementation thatexposes a non-JCR data store through the JCR API may wish to exposenames containing JCR-illegal characters by using a substitution orescaping scheme. If so, it must do so by substituting private-useUnicode characters for the JCR-illegal characters according to thefollowing mapping.
JCR-Illegalcharacter | Substitutioncharacter |
(U+002A) | U+F02A |
(U+002F) | U+F02F |
(U+003A) | U+F03A |
(U+005B) | U+F05B |
(U+005D) | U+F05D |
(U+007C) | U+F07C |
The mapping mustbe used bi-directionally. When the repository wishes to return thename of an entity whose native name contains a JCR-illegalcharacter, that character must be replaced with its correspondingsubstitution character in the returned string.
Conversely, when aname containing one of the substitution characters is passed to therepository through the JCR API, that character must be replaced withits corresponding non-JCR character before further processing isdone within the native layer, whether writing the name to storage orusing the name to access an entity.
In the unlikely eventthat one of the substitution characters appears literally in anative name, that character will be returned unchanged through theJCR API.
In repositories thatdo not expose non-JCR names and therefore do not need to use thesubstitution scheme, any private-use substitution character passedto the API is stored and returned unchanged. However, such use of aprivate-use substitution character within a JCR name is stronglydiscouraged.
When a JCR name ispassed as an argument to a JCR method it may be in either expandedor qualified form. When a repository returns a JCR name it must bein qualified form. The qualified form of a name depends upon theprevailing local namespace mapping of the current session (see §3.5Namespace Mapping).
Two JCR names (N1,L1) and (N2,L2)areequal if and only ifN1 is equaltoN2 andL1 isequal toL2, according to the definition ofstring equality used in themethod. This definition applies both in the general context of usingan API method that takes or returns a JCR name and in the specificcase of comparing values of type(see §3.6.5.8NAME).
Every node has anidentifier. An identifier is a string whose format is notdefined by this specification but which adheres to the followingconstraints:
The identifier of a non-sharednode is unique within a workspace. The identifier of a shared nodeis common to each member of that node's share-set (see §3.9Shareable Nodes Model).
An identifiermust be themost stable one available to the implementation. For example, insome implementations this might be nothing more than the node pathitself. Other implementations might support node identifiers thatare partly or entirely independent of the path.
The identifier must be assigned at thelatest when the node is first persisted, though it may be assignedearlier, when the node is first created in transient storage in thesession (see §10.4.1Adding a Node).
In implementations that supportreferenceable nodes, these nodes have more stringent requirements ontheir identifiers (see §3.8Referenceable Nodes).
Identifiers are also used fornodecorrespondence across multiple workspaces (see §3.10Corresponding Nodes).
AJCR pathP,
P= (S0,S1, ...,Sn),
is an ordered listwith at least one element, where each elementSi,for 0i n, is apath segment.
A path segment is oneof:
anamesegment, (J,I), whereJ is a JCR nameand
I is an integer index (I≥ 1).
anidentifiersegment,U, whereU is a JCR identifier.
therootsegment.
theselfsegment.
theparentsegment.
The root, self andparent segments are logical constants distinct from each other andfrom all name segments.
Name, self and parentsegments can occur at any position in a path.
A root segment canoccur only as the first segment of a path.
An identifier segmentcan occur only as the first and sole segment in a path. No othersegments may follow an identifier segment.
The successive pathsegments of JCR pathP = (S0,S1,...,Sn) define a route through workspaceWto atarget item as follows:
IfS0is the root segment then the path is absolute and thecurrentitem is the root node ofW.
IfS0is an identifier segmentU, then the path is absolute andthecurrent item is the node inW with the identifierU.
Otherwise, thepath is relative and thecurrent item is determined by thecontext of use.
For each segmentS in pathP:
IfS is aself segment then thecurrent item does not change.
IfS is aparent segment then the newcurrent item is a parent of theoldcurrent item (see §3.4.2.1Parent Resolution).
IfS is aname segment then the new current item is the child of the oldcurrent item identified byS (see §3.4.2.2ChildResolution).
Once all segmentshave been traversed, thecurrent item is thetargetitem.
In most cases an itemwill have only one parent, in such a case, parent resolution istrivial. In repositories that support shareable nodes, a node mayshare its child nodes and properties with other nodes. A child itemof a shared node therefore has more than one parent. In such a casethe parent resolved depends upon thedeemed path of the item,which is an implementation-specific issue (see §3.9.5DeemedPath). An attempt to resolve the parent of a workspace root nodealways fails.
Given a name segmentS= (J,I),J is the name of the child itemindicated by that segment whileIindicates the index of theitem. The index is an integer greater than or equal toand is used to distinguish between sibling child nodes with the samename. If there is only one child node with the nameJthenits index is always.If there is more than one node with the nameJ then each hasa unique index (see §22Same-Name Siblings).
The child itemindicated byS is determined as follows:
If theSis not the last segment of the path then, if a child nodewith nameJ and indexI exists,S resolves tothat node. Otherwise, resolution fails.
IfSisthe last segment of the path then,
ifS isconstrained to resolve to agettable node (as in the case of)and a child node with nameJ and indexI isretrievable,S resolves to that node. Otherwise,
ifS isconstrained to resolve to anaddable node (as in the case of)and a child node namedJ can be legally added andIis equal to 1, thenJ is used as the name of the new nodewhich, if necessary, is given an appropriate index. Otherwise,
ifS isconstrained to resolve to agettable property (as in thecase of)then, if a property with nameJ is retrievable, andIis equal to 1,S resolves to that property. Otherwise,
ifS isconstrained to resolve to asettable property (as in thecase of)then, if a property with nameJ or if a property namedJcan be legally added, andI is equal to 1,S resolvesto that property. Otherwise,
ifS isconstrained to resolve to agettable item (as in the case of)then if a node with nameJ and indexI isretrievable,S resolves to that node. Otherwise, if thereexists a property with name J andI is equal to 1, thenSresolves to that property.
Otherwise,resolution fails.
Given a JCR path=, its lexical formcan be constructed according to the following algorithm, whereis the assignment operator,is the string append operator,indicates an arbitrary choice between alternative operations andis the null operation.
The resultingis a lexical form of.As indicated by the steps markedoptional syntax, a JCR pathmay have multiple equivalent lexical forms depending on the use ofqualified vs. expanded names, the optionalindex indicator and the optional trailing forward slash (“”).
A string constructedwithout any of the optional syntax shown in the algorithm is calledthestandard form of a JCR path. Such a lexical path has thefollowing characteristics:
It consists ofeither one identifier segment or one or more name segments.
All name segmentsare in qualified form, none are in expanded form.
No name segmenthas aindex.
There is notrailing forward slash (“”).
The following areexamples of standard form lexical paths:
A string constructedwith one or more optional steps is anon-standard formJCR path. A non-standard form lexical path hasat least oneof the following features:
One or more namesegments are in expanded form.
One or more namesegments has aindex.
The path has atrailing forward slash (“”).
The following areexamples of non-standard form lexical paths:
A JCR path in lexicalform conforms to the following grammar
When parsing a lexicalpath, the parser must distinguish between name segments that are inexpanded form and those that are in qualified form (see §3.2.5Lexical Form of JCR Names). When making this determination,the repository cannot assume that every namespace URI encountered inan expanded name will be registered within the repository.
An otherwise validpath containing an expanded name with an unregisterednamespaceURIwill always resolve into a valid internal representation ofa path (i.e., an ordered list of path segments, see §3.4Paths).Any errors that arise from passing such a path must therefore be asa result of further processing (not merely parsing) that depends onthe semantics of the path and the context of use.
However, a pathcontaining a qualified name with an unregisteredprefix willnot resolve into a valid internal path representation. Anattempt to pass such a path will therefore fail at the parsingstage.
An abstract JCR pathis eitherabsolute orrelative.
An absolute JCR pathis eitherroot-basedoridentifier-based.
A root-based absolutepath begins with the root segment. Its lexical form therefore beginswith a forward slash, for example,
An identifier-basedabsolute path consists of a single identifier segment. Its lexicalform therefore consists of square brackets delimiting an identifier,for example,
A relative JCR path isone which begins with a segment that is neither a root segment noran identifier segment. Its lexical form therefore begins with eithera JCR name,or, for example,
or
A JCR path isnormalized by the following steps:
All self segmentsare removed.
All redundantparent segments are collapsed. A redundant parent segment is onewhich can be removed by also removing a preceding name segmentwhile preserving the location indicated by the path. For example,the pathcan be collapsed to.Note therefore, that if a normalized path contains any parentsegments, they must all precede the first name segment.
If the path is anidentifier-based absolute path, it is replaced by a root-basedabsolute path that picks out the same node in the workspace as theidentifier it replaces.
When a JCR path ispassed as an argument to a JCR method it may be normalized ornon-normalized and in standard or non-standard form.
When a repositoryreturns a JCR path it must be normalized (see §3.4.5NormalizedPaths), unless the repository is returning the value of aproperty, in which case the original, possibly non-normalized formof the path is preserved and returned. In all cases the returnedpath must be in standard form (see §3.4.3.1Standard Form).
Two types of pathequality are defined:segment equality andsemanticequality.
Two pathsP1andP2 are segment-equal if and only if:
They contain thesame number of segments.
Each segment inP1 is equal to the segment at the sameposition inP2.
Two name segments areequal if and only if their JCR names are equal (see §3.2.7Equalityof Names) and their integer indexes are equal.
Equality foridentifier segments is as defined for identifiers in general, thatis, by standard Javaequality.
Equality for root,self and parent segments is simple type identity; every instance ofa root, parent or self segment is equal to every other instance ofthe same type.
For two pathsP1andP2 semantic equality is defined asfollows:
IfP1andP2 are normalized then they aresemantically equal if and only if they aresegment-equal.
IfP1andP2 are non-normalized then they aresemantically equal if and only if their normalized forms aresemantically equal.
When a JCR path ispassed to a JCR API method that must resolve that path theapplicable definition of path equality is that of semantic equality.Semantic equality of two paths means that, given identical contexts,the two paths will resolve to the same item.
However, values oftypeare not normalized upon storage or retrieval, so the when comparingtwo such values, the applicable definition of equality is that ofsegment equality. (see §3.6.5.9PATH).
For compactness andlegibility in documentation, XML and Java code, JCR names areusually expressed in qualified form.
The use of qualifiedform, however, depends upon a context that supplies a mapping fromprefix to namespace. In documentation this context is providedeither by convention or explicit statement. In XML serialization itis supplied byattributes (see §7Export) and in a running JCR repositoryis provided by the local namespace mapping of each individual.
The local namespacemapping of a session is determined by the initial set of mappingscopied from thenamespace registry and any session-localchanges made to that set.
The namespace registryis a single, persistent, repository-wide table that contains thedefault namespace mappings. It may contain namespaces that are notused in repository content, and there may be repository content withnamespaces that are not included in the registry. The namespaceregistry always contains at least the following built-in mappingsbetween prefix (on the left) and namespace (on the right):
Reservedfor items defined within built-in node types (see §3.7NodeTypes).
Reservedfor the names of built-in primary node types.
Reservedfor the names of built-in mixin node types.
Reservedfor reasons of compatibility with XML.
(the emptystring)(the empty string)
Thedefault namespace is theempty namespace.
The permanent defaultnamespace in JCR is the empty string, also referred to as theemptynamespace. This permanence is reflected in the immutable defaultnamespace mapping in the namespace registry. By definition, theprefix in this mapping is the empty string, also referred to as theempty prefix.
A repository mayprovide additional built-in mappings other than those defined inthis section. All mappings must be one-to-one, meaning that for agiven namespace in the registry exactly one prefix is mapped to it,and for a given prefix in the registry exactly one namespace ismapped to it.
A local set ofnamespace mappings is associated with each session. When a newsession is acquired, the mappings present in the persistentnamespace registry are copied to the local namespace mappings ofthat session. A user can then add new mappings or change existingones. The resulting mapping table applies only within the scope ofthat session (see §5.11Namespace Mapping).
If a JCR methodreturns a name from the repository with a namespace URI for which nolocal mapping exists, a prefix is created automatically and amapping between that prefix and the namespace URI in question isadded to the set of local mappings. The new prefix must differ fromthose already present among the set of local mappings. If a JCRmethod is passed a name or path containing a prefix which does notexist in the local mapping an exception is thrown.
All methods that takeor return names or paths must use the current session (see §3.1.8.2Current Session and Workspace) namespace mappings todynamically interpret or produce those names or paths according tothe current local namespace mapping of the current session.
Though the precisemechanism of this behavior is an implementation detail, its behaviormust be equivalent to that of a system where names and paths arestored internally in expanded form and converted dynamically to andfrom qualified JCR names or paths as necessary.
Names and pathsdetermined by an application provider should be assigned namespaceURIs under the control of the provider organization. Because thespace of URIs is universally managed, this ensures that namingcollisions will not occur between applications from providers thatobserve this convention.
All data stored withina JCR repository is ultimately stored as the values of properties.
Every property is ofone of the following types:,,,,,,,,,,or.
properties store instances of.
properties store instances ofthat conform to the syntax of a URI-reference as defined in RFC39863.
properties store instances of the Java primitive type.
properties store instances of the Java primitive type.
properties store instances of the Java primitive type.
properties store instances of.
properties store instances of(see §5.10.5Binary Object).
properties store instances of.Note that an implementation may not supportvalues that cannot be represented in the ISO 8601-based notationdefined in §3.6.4.3From DATE To. In such cases an attemptto set a property to such a value will throw a.
properties store instances of JCR names.
properties store instances of JCR paths and serve as pointers tolocations within the workspace.propertiesdo not enforce referential integrity.
properties serve as pointers to referenceable nodes by storing theiridentifiers.propertiesdo not enforce referential integrity (see §3.8.2Referential Integrity).
properties serve as pointers to referenceable nodes by storing theiridentifiers.propertiesdo enforce referential integrity (see §3.8.2Referential Integrity).
Thekeyword, while not specifying an actual type, may be supported bysome repositories as a valid property type attribute value inproperty definitions within node types. In that context it indicatesthat the specified property may be ofany type. No actualexisting property in the repository ever has the type.
A property may be asingle-value or a multi-value property.
A single-valueproperty, if it exists, must have a value. There is no such thing asa null value. A multi-value property can have zero or more values.Again there is no such thing as a null value, however a multi-valueproperty can be empty, just as an array can be empty.
The values storedwithin a multi-valued property are all of the same type and areordered.
Whether a particularproperty is a multi-valued property is governed by the propertydefinition applicable to it, which is determined by the node type ofthe property's parent node (see §3.7Node Types).
Accessing the value ofa property is done withwhich returns a singleobject. Accessing the set of values of a multi-value property isdone throughwhich returns a (possibly empty) array ofobjects (see §5.10Reading Properties).
When the value of aproperty is read or written using a type different from thatdeclared for the property, the repository attempts a type conversionaccording to the following rules. Note that even in cases where theJCR type conversion is defined in terms of standard JDK typeconversion method, failure of conversion must only ever cause a JCRto be thrown and never any exception defined in the JDK API.
BINARY: Thestring is encoded using UTF-8.
DATE: If thestring is in the format described in §3.6.4.3From DATE To,it is converted directly, otherwise ais thrown.
DOUBLE: Thestring is converted using.
DECIMAL: Thestring is converted using the constructor.
LONG: Thestring is converted using.
BOOLEAN: Thestring is converted using.
NAME: If thestring is a syntactically valid qualified JCR name with a registeredprefix, it is converted directly. If it is a syntactically validexpanded JCR name with a registered namespace URI, it is returned inqualified form. If it is a syntactically valid expanded JCR namewith anunregistered namespace URI, a prefix is createdautomatically, the mapping added to the local namespace mappings(see §3.5.2Session-Local Mappings), and the name isreturned in qualified form. Otherwise ais thrown.
PATH: If thestring is a valid JCR path then each name segment is converted asperconversion above, and all other segments are converted directly. Ifone or more name conversions fails or if the string is not a validpath then ais thrown. The presence of an item in the current workspace at thatpath is not required.
URI: If thestring is a syntactically valid URI-reference, it is converteddirectly, otherwise ais thrown. The string is parsed as described in RFC 3986. Inparticular, the first colon (“”)encountered is interpreted as the scheme delimiter and the string asa whole is assumed to already be in percent-encoded form. This meansthat if a non-URI-legal character is encountered it is notpercent-encoded, but is instead regarded as an error and ais thrown.
REFERENCE orWEAKREFERENCE: If the string is a syntactically valididentifier, according to the implementation, it is converteddirectly, otherwise ais thrown. The identifier is not required to be that of an existingnode in the current workspace.
STRING: Anattempt is made to interpret the stream as a UTF-8 encoded string.If the string is not a legal UTF-8 byte sequence then the behavioris implementation-specific.
All Others: Thebinary stream is first converted to a string, as described above. Ifthis is successful, the resulting string is converted according tothe appropriate conversion as described in §3.6.4.1From STRINGTo.
STRING: Thedate is converted to the following format:
where:
Four-digityear with optional leading positive (‘’)or negative (‘’)sign.,andall indicate the year 1 BCE. –whereis the numbery indicates the year (y+1) BCE. Theabsence of a sign or the presence of a positive sign indicates ayear CE. For example,would indicate the year 55 BCE, whileandindicate the year 1969 CE.
Two-digitmonth (01 = January, etc.)
Two-digitday of month (01 through 31)
Twodigits of hour (00 through 23, or 24 ifis 00 andis 00.000)
Twodigits of minute (00 through 59)
Seconds,to three decimal places (00.000 through 59.999 or 60.999 in the caseof leap seconds)
Timezone designator (eitherZ for Zulu, i.e. UTC, or+hh:mmor-hh:mm, i.e. an offset from UTC)
Note that the “”separating the date from the time and the separators “”and“”appear literally in the string.
This format is asubset of the format defined by ISO 8601:2004.
If thevalue cannot be represented in this format ais thrown.
BINARY: Thedate is converted to a string, as described in §3.6.4.2FromBINARY To, and this string is encoded in UTF-8.
DOUBLE: Thedate is converted to the number of milliseconds since 00:00 (UTC) 1January 1970 ().If this number is out-of-range for a double, ais thrown.
DECIMAL: Thedate is converted to the number of milliseconds since 00:00 (UTC) 1January 1970 ().
LONG: The dateis converted to the number of milliseconds since 00:00 (UTC) 1January 1970 ().If this number is out-of-range for a long, ais thrown.
All Others: Ais thrown.
Since the string andnumber formats into which amay be converted can hold only a subset of the informationpotentially contained within a,conversion fromto ormay result in loss of information.
STRING: Thedouble is converted using.
BINARY: Thedouble is converted to a string, as described in §3.6.4.2FromBINARY To, and this string is encoded in UTF-8.
DECIMAL: Thedouble is converted using the constructor.
DATE: Thedouble is coerced to a long using standard Java type coercion andinterpreted as the number of milliseconds since 00:00 (UTC) 1January 1970 ().If the resulting value is out of range for a date, ais thrown.
LONG: StandardJava type coercion is used.
All Others: Ais thrown.
STRING: Thedecimal is converted using.
BINARY: Thedecimal is converted to a string, as described in §3.6.4.2FromBINARY To, and this string is encoded in UTF-8.
DOUBLE: Thedecimal is converted using.
DATE: Thedecimal is converted to a long and interpreted as the number ofmilliseconds since 00:00 (UTC) 1 January 1970().If the resulting value is out of range for a date, ais thrown.
LONG: Thedecimal is converted using.
All Others: Ais thrown.
STRING: Thelong is converted using.
BINARY: Thelong is converted to a string, as described in §3.6.4.2FromBINARY To, and this string is encoded in UTF-8.
DECIMAL: Thedouble is converted using the method.
DATE: The longis interpreted as the number of milliseconds since 00:00 (UTC) 1January 1970 ().If the resulting value is out of range for a date, ais thrown.
DOUBLE:Standard Java type coercion is used.
All Others: Ais thrown.
STRING: Theboolean is converted using.
BINARY: Theboolean is converted to a string, as described in §3.6.4.2FromBINARY To, and this string is encoded in UTF-8.
All Others: Ais thrown.
STRING: Thename is converted to qualified form according to the current localnamespace mapping (see §3.2.5.2Qualified Form).
BINARY: Thename is converted to a string, as described in §3.6.4.2FromBINARY To, and then encoded using UTF-8.
PATH: The namebecomes a relative path of length one.
URI: The namebecomes a URI-reference consisting of “”followed by the name in qualified form. For example, the namebecomes the URI-reference.The addition of the leading “”is done to ensure that a colon-delimited prefix is not interpretedas a URI scheme name. If the name includes characters that areillegal within a URI-reference (such as any non-ASCII character),the UTF-8 byte representations of these characters arepercent-encoded, as described in RFC 39864.
All Others: Ais thrown.
STRING: Eachpath is converted to standard form according to the current localnamespace mapping (see §3.4.3.1Standard Form).
BINARY: Thepath is converted to a string, as described in §3.6.4.2FromBINARY To, and then encoded using UTF-8.
NAME: If thepath is a relative path of length one it is converted directly,otherwise ais thrown.
URI: If thepath is root-based absolute (that is, it has a leading “”,see §3.4.4.1.1Root-Based Absolute Paths), it is directlyconverted into a URI-reference. If the path is identifier-basedabsolute (§3.4.4.1.2Identifier-Based Absolute Paths) orrelative, it becomes a URI-reference consisting of “”followed by the path in standard form. For example, the pathbecomes the URI-reference.The addition of the leading “”is done to ensure that a colon-delimited prefix is not interpretedas a URI scheme name. If the path includes characters that areillegal within a URI-reference (such as any non-ASCII character),the UTF-8 byte representations of these characters arepercent-encoded, as described in RFC 39866.
All Others: Ais thrown.
STRING: Theis converted directly into a
BINARY: Since aURI is guaranteed to already contain only ASCII characters it isconverted directly to aresulting in series of octets that is a UTF-8 encoding of thecharacter sequence comprising the URI.
NAME: If theconsists of a single path segment without a colon (for example,simply)it is converted to aby decoding any percent-escaped sequences into octet sequences andthen decoding those into character sequences using UTF-8. If it hasa redundant leading “”followed by a single segment (with or without a colon, likeor) the redundant “”is removed and the remainder is converted to ain the same way. Otherwise ais thrown.
PATH: If thebegins with a “”it is converted aby decoding any percent-escapedsequences into octet sequences and then decoding those intocharacter sequences using UTF-8. If it consists of a path whosefirst segment is without a colon (for example,,or)it is converted in the same way. If it consists of a path with aredundant leading “”(for example,or) the redundant “”is removed and the remainder is converted to aas described in §3.6.4.1From STRING To. Otherwise ais thrown.
All Others: Ais thrown.
STRING: Theidentifier is converted directly to a string.
BINARY: Theidentifier is converted directly to a string and then converted toas described in §3.6.4.1From STRING To.
WEAKREFERENCE:Theis simply turned into a.
All Others: Ais thrown.
STRING: Theidentifier is converted directly to a string.
BINARY: Theidentifier is converted directly to a string and then converted toas described in §3.6.4.1From STRING To.
REFERENCE: Theis simply turned into a.
All Others: Ais thrown.
For any valuesV1andV2 both of the same property type, therelationsis equal to,is ordered before andisordered after are defined in §3.6.5.1CompareTo Semantics.
Note that thedefinition of these relations here does not necessarily imply thatJCR API methods for testing these relations are supported for everyproperty type. In particular,is not required to work onvalues and JCR query is not required to support testing theequality or ordering ofvalues.
For the property typesother than,,and,comparison relations are defined in terms of the result of themethod on instancesandof the Java class corresponding to the JCR property type (see eachsection below for the relevant class). For those types:
V1is equal toV2 if and only if.
V1is ordered beforeV2if andonly if.
V1is ordered afterV2 if and only if.
IfV1andV2 are values of type,,orthen the repositoryshould use the semantics of,as described in §3.6.5.1CompareTo Semantics.
IfV1andV2 are values of typethen the repositorymust use the semantics of,as described in §3.6.5.1CompareTo Semantics.
IfV1andV2 are values of typethen the repositorymust use the semantics of,as described in §3.6.5.1CompareTo Semantics.
IfV1andV2 are values of typethen the repositorymust use the semantics of,as described in §3.6.5.1CompareTo Semantics.
IfV1andV2 are values of typethen the repositorymust use the semantics of,as described in §3.6.5.1CompareTo Semantics.
IfV1andV2 are values of typethen
V1is equal toV2 if and only if.
V1is ordered beforeV2if andonly if and.
V1is ordered afterV2 if and only if and.
IfV1andV2 are values of typeandV1 = (N1,L1)andV2 = (N2,L2)whereN1andN2are JCR namespaces andL1 andL2are JCR local names then
V1is equal toV2 if and only ifN1is equal toN2 andL1is equal toL2, according to the semanticsof(see §3.2.7Equality of Names).
Ordering isimplementation-specific. The only requirement is that atotalorder on values of typemust be defined, meaning that ifV1 andV2are not equal then eitherV1 is orderedbeforeV2 orV1is ordered afterV2.
IfV1andV2 are values of typethen
V1is equal toV2 if and only ifV1andV2 aresegment-equal (see§3.3.8Equality of Paths).
Ordering isimplementation-specific. The only requirement is that atotalorder on values of typemust be defined, meaning that ifV1 andV2are not equal then eitherV1 is orderedbeforeV2 orV1is ordered afterV2.
IfV1andV2 are values of typeand given,
V1is equal toV2 if and only ifV1andV2 are bitwise equivalent.
Ordering isimplementation-specific.
An implementation oftheinterface must override the inherited methodso that, giveninstancesand,will returnif:
andwere acquired from the same,and
the contents ofandhave not yet been accessed, and
andare of the same type, and
is equal toas defined in §3.6.5Comparison of Values.
will returnotherwise.
In addition:
The equalitycomparison must not change the state of eitherorand
support forin the case ofvalues is optional.
Thelength of avalue is defined as follows:
For avalue, its length is equal to its length in bytes. This number isreturned both by(see §5.10.5Binary Object) and byand(see §5.10.3Value Length).
For other types,the length is the same value that would be returned by callingon theresulting from standard JCR property type conversion (see §3.6.4Property Type Conversion). This number is returned byand.
For single valueproperties, the length of a property's value is often referred to astheproperty length.
Node types are used toenforce structural restrictions on the nodes and properties in aworkspace by defining for each node, its required and permittedchild nodes and properties.
Every node has onedeclaredprimary node type and zero or moremixin nodetypes. Primary node types are typically used to defined the corecharacteristics of a node, while mixin node types are used to addadditional characteristics often related to specific repositoryfunctions or to metadata.
In a writablerepository a node's primary type is first assigned upon nodecreation, while mixin types may be assigned on creation or during anode's lifetime. Repository implementations may vary as to howflexible they are in allowing changes to the primary or mixin nodetypes assigned to a node.
Each repository has asingle, system-wide registry of node types. Typically, a repositorywill come with some implementation-determined set of built-in nodetypes. Some of these types may be vendor-specific while others maybe standard node types defined by JCR to support common use-cases(see §3.7.11Standard Application Node Types) or repositoryfeatures. Some repositories may further allow users to register newnode types programmatically (see §19Node Type Management).
A node type definitionconsists of the following attributes:
Every registered nodetype has a JCRname, unique within the repository.
A node type haszeroor moresupertypes. Supertypes are specified by name.
A node type may bedeclaredabstract, meaning that it cannot be directlyassigned to a node, though it may act as a supertype to other nodetypes. The abstract flag is a boolean.
A node type may bedeclared a mixin node type. A mixin node type can be assigned to anode during that node's lifetime, not just upon node creation, as isthe case with primary node types. The mixin flag is a boolean.
A node type may bedeclaredqueryable, meaning that the node type can be used ina query selector and that the query-related attributes of propertiesdefined in that node type take effect. Thequeryable node typeattribute is a boolean.
If a node type isdeclared queryable, then theavailable query operators,full-text searchable andquery-orderableattributes of its property definitions take effect (see §3.7.3.3Available Query Operators, §3.7.3.4Full-Text Searchable,§3.7.3.5Query-Orderable). If a node type is declarednon-queryable then these attributes of its property definitions haveno effect.
A node type maydeclare its child nodes orderable, meaning that for all nodes ofthat type, the order that the child nodes are iterated over can beprogrammatically controlled by the user (see §23Orderable ChildNodes). The orderable child nodes flag is a boolean.
A node type candeclare one of its child items as primary, meaning that for allnodes of that type, that child item is accessible through adedicated API method which does not require the name of the item.(see §5.1.7Primary Item Access). This feature can helpgeneric API clients intelligently traverse an unknown nodestructure. The primary item may be an item name, which must be a JCRname, or null, meaning that there is no primary item.
In cases where theprimary child item specifies the name of a set of same-name siblingchild nodes, the node with indexwill be regarded as the primary item.
In cases where thisnode has both a child node and a property with the same name andwhere that name is specified as the primary item name, the childnode will be regarded as the primary item (see §22.4Propertyand Node with Same Name).
A node type maycontain a list ofproperty definitions, which specify theproperties that nodes of that type are permitted or required to haveand the characteristics of those properties. The list of propertydefinitions may be empty.
A node type maycontain a list of child node definitions, which specify thepermitted or required child nodes and their characteristics. Thelist of child node definitions may be empty.
Propertyand child node definitions have some attributes in common, whileothers are specific to either property definitions or child nodes inparticular (this is reflected in the API interfaces, see §8.3ItemDefinition Object).The common attributes are:
The name attributespecifies the set of child nodes or properties to which thedefinition applies. This set is called thescope of thedefinition. An item within the scope of a given definition is calledascoped item (scoped property, scoped child node) of thatdefinition. The definition within whose scope a given item falls iscalled thescoping definition of that item.
In the standard casethe scope consists of the single item named by the attribute andmust be a JCR name.
In a repository thatsupportssame-name siblings(see §22Same-Name Siblings),the name attribute of a child node definition will have scope overall the child nodes of that name. In this case the attribute mustalso be a JCR name.
In a repository thatsupportsresidual definitions the name attribute may be “”(asterisk), specifying that thedefinition is residual, meaning that its scope consists of all otherproperties (child nodes), which are not otherwise scoped by any ofthe other property (child node) definitions in the effective nodetype of the node (see §3.7.6.5Effective Node Type).
Anode type may have two or more item definitions with identicalnameattributes. Onor,the repository must choose among the available definitions for onewhich matches the name and possible type information specified inthe method call. If this information is insufficient to select asingle definition unambiguously, the repository may choose adefinition based on some implementation-specific criteria or failthe operation (see §10.4Adding Nodes and Setting Properties).
If an itemI isdeclared protected it isrepository-controlled.
IfI is a nodethen, through the core write methods of JCR (see §10.2CoreWrite Methods),
I cannotbe removed,
child nodes ofIcannot be added, removed, or reordered,
properties ofIcannot be added or removed,
the values ofexisting properties ofI cannot be changed,
the primary nodetype ofI cannot be changed and
mixin node typescannot be added to or removed fromI.
If I is a propertythen, through thecore write methods of JCR(see §10.2CoreWrite Methods),
I cannotbe removed and
the value ofIcannot be changed.
Additionally, ifIis a property, its being repository-controlled also implies that itsvalue is under the control of the repository and can change at anytime, before or after save. See §3.7.2.3.2Auto-Created andProtected.
Anitem may be declaredauto-created,meaning that it is automatically created upon creation of its parentnode. The auto-created attribute is a boolean.
If an item isauto-created but not protected then itmust beimmediatelycreated in transient space when its parent node is created. Creationof auto-created non-protected items must never be delayed until save(see §10.11Saving).
If an item is bothauto-created and protected, then itshould be immediatelycreated in transient space when its parent node is created. Creationof auto-created protected items should not be delayed until save,though doing so does not violate JCR compliance. In someimplementations the value of an auto-created property may beassigned upon save, in such cases the creation of the property mayalso be delayed until save (see, for example, §3.7.1IdentifierAssignment).
In a repository thatsupports same-name siblings (see §22Same-Name Siblings), achild node definition may specify that a node be both auto-createdand allow same-name siblings. In that case the repository mustcreate at least one such child node with the specified name uponparent node creation, though it may create more than one.
In repositories thatsupport residual definitions, an item cannot be both auto-createdand residual (see §3.7.2.1.2Item Definition Name and ResidualDefinitions).
An auto-created nodemay itself have auto-created child items, resulting in the automaticcreation of a tree of items. However, chaining that produces aninfinite loop of item creation is not permitted. A repository mustensure that at no time does it have a set of registered node typesthat could result in such behavior (see §19Node TypeManagement).
Anitem may be declaredmandatory,meaning that the item must exist before its parent node is saved.
Since single-valueproperties either have a value or do not exist (there being noconcept of the null value, see §10.4.2.4No Null Values), amandatory single-value property must have a value. A mandatorymulti-value property, on the other hand, may have zero or morevalues.
In a repository thatsupports same-name siblings, a child node definition may specifythat a node be both mandatory and allow same-name siblings. In thatcase at least one child node must exist upon save of the parent node(see §22Same-Name Siblings).
In repositories thatsupport residual definitions, an item cannot be both mandatory andresidual (see §3.7.2.1.2Item Definition Name and ResidualDefinitions).
In a repository thatsupportssimple orfull versioning theon-parent-version attribute governs the behavior of the child itemwhen its parent node is checked-in (see §15.2Check-In: Creatinga Version). In repositories that do notsupportsimple orfullversioning this attribute has no effect.
Aproperty definition has all the attributes of a generic itemdefinition as well as the following property-specific attributes:
A property definitionmust specify a property type. This must be one of the JCR propertytypes (see §3.6.1Property Types) or, in repositories thatsupport it, thekeyword, indicating that the property scoped by this definition canbe of any type (see §3.6.2Undefined Type). An attempt tosave a property with a type different from that required by itsdefinition will fail if conversion to that type is not possible (see§10.4.2Setting a Property and §3.6.4Property TypeConversion).
Thedefault valuesattribute of a property definition defines the valuesassigned to property if it isauto-created. If the propertyis single-valued this attribute will hold a single value. If it ismulti-valued this attribute will hold an array of values. A defaultvalues setting ofindicates that the property does not have a single static defaultvalue. It may have no default value at all or it may have aparameterized default value defined externally to thisspecification. If the scoped property is notauto-createdthen this attribute has no effect.
A property definitiondeclares the set of query comparison operators that can be validlyapplied to a property. The set of operators that can appear in thisattribute may be limited by implementation-specific constraints thatdiffer across property types. For example, some implementations maypermit property definitions to provideand(see §6.7.16Comparison) as available operators forproperties while others may not. However, in all cases where aJCR-defined operatoris potentially available for a givenproperty type, its behavior must conform to the comparison semanticsdefined in §3.6.5Comparison of Values.
This attribute onlytakes effect if the node type holding the property definition has aqueryable setting oftrue (see §3.7.1.5Queryable NodeType).
A property may bedeclaredfull-text searchable, meaning that its value isaccessible through the full-text search function within a query (see§6.7.19FullTextSearch). The full-text searchable flag is aboolean.
This attribute onlytakes effect if the node type holding the property definition has aqueryable setting oftrue (see §3.7.1.5Queryable NodeType), otherwise this attribute is automatically set tofalse.
A property may bedeclaredquery-orderable, meaning that query results may beordered by this property using theorderclause of a query(see §6.7.37Ordering). The query-orderable flag is aboolean.
This attribute onlytakes effect if the node type holding the property definition has aqueryable setting oftrue (see §3.7.1.5Queryable NodeType), otherwise this attribute is automatically set tofalse.
A property definitionmay impose constraints on the value that the property may hold.These value constraints are defined by an array of strings, whoseformat differs depending on the type of the property.
Each string in thereturned array specifies a constraint on the values of the property.In order to be valid,each value of the property (since aproperty may be multi-valued) must independently meetat leastone of the constraints.
If a property does notexist or, in the case of multi-value properties, contains an emptyarray, the constraint set is considered to have been met.
An attempt to save aproperty whose value or values fail to meet the constraint criteriawill fail (see §10.11Saving).
Reporting constraintinformation is optional on a per property instance level. The returnof an empty array indicates that there are noexpressibleconstraints, meaning that either there are constraints but they arenot expressible in the constraint-string syntax, or constraintdiscovery is not supported for that property.
Constraint stringshave different formats depending on the type of the property inquestion. The following sections describe the value constraintsyntax for each property type.
Forandproperties, the constraint string is a regular expression patternaccording to the syntax of.
Forproperties, the constraint is an absolute or relative path, possiblyterminating with a “”as the last segment.
On assignment theconstraint may be passed in any valid lexical form, with thepossible addition of a trailing “”.The constraint, however is stored as a JCR path in normalized formplus an optionalmatch-descendantsindicator corresponding tothe “”.The constraint is returned in normalized standard form (see §3.4.5.1Standard Form and §3.4.5Normalized Paths).
For a constraintwithout match-descendants, the constraint is met when theproperty value is equal to the constraint. For a constraintwithmatch-descendants, the constraint is met when the property value iseither equal to the constraint or equal to a descendant path of theconstraint (see §3.4.8Equality of Paths).
For properties, the constraint is a JCR name. On assignment theconstraint may be passed in any valid lexical form but is returnedin qualified form (see §3.2.5.2Qualified Form).Theconstraint is met if the property value is equal to the constraint(see §3.2.7Equality of Names).
Forandproperties, the constraint is a JCR name. The constraint is met ifthe target node of the property is of the node type indicated by theconstraint (see §3.7.6.3Is-of-Type Relation). On assignmentthe constraint passed may be in any valid lexical form but isreturned in qualified form (see §3.2.5.2Qualified Form).
The remaining typesall have value constraints in the form of inclusive or exclusiveranges specified according to the following pattern:
The brackets ““and “”indicate inclusivity, while ““and “”indicate exclusivity. A missingorvalue indicates no bound in that direction. The meaning of theandvalues themselves differ between types as follows:
:andspecify the allowed size range of the binary value in bytes.
:andare dates specifying the allowed date range. The date strings mustbe in the standard string serialization (see §3.6.4.3FromDATE To).
:,are valid Java language numeric literals.
Therange is evaluated according to the standard value comparison rules(see §3.6.5Comparison of Values).
To specify a constantvalue, the constant itself, “”may be used instead of the bracket notation, though the constraintis always returned in bracket notation.
Forproperties the constraint string can be either “”or “”.In most caseswill return an empty array since placing a constraint on avalue is uncommon.
Because constraintsare returned as an array of disjunctive constraints, in many casesthe elements of the array can serve directly as achoice list.This may, for example, be used by an application to display optionsto the end user indicating the set of permitted values.
A property can bedeclaredmulti-valued. An attempt to set a single-valueproperty by passing an array will fail. Similarly, an attempt to seta multi-value property by passing a non-array will also fail (see§10.4.2Setting a Property).
A childnode definition has all the attributes of a generic item definitionas well as the following node-specific attributes:
A child nodedefinition must declare one or morerequired primary node types.
In order tosuccessfully save a scoped child nodeN, it must be true foreach required primary typeR that the assigned primary typeAofNis of type R (see §3.7.6.3Is-of-TypeRelation).
In cases where thisattribute specifies more than one required node type, any particularnode instance will still have only one assigned primary type, butthat type must be a subtype ofall of the types specified bythis attribute. Such a situation may arise, for example, inrepositories that support multiple inheritance of node types.
Thedefault primarytype of a child node definition is a JCR name defining the nodetype that the child node will be given if it is auto-created orcreated without an explicitly specified node type. This node typemust be the same as or a subclass of each of the required primarynode types.
Ifis returned this indicates that no default primary type is specifiedand that therefore an attempt to create this node without specifyinga node type will fail.
Thesame-name siblingattribute of a child node definition indicates whether the childnode can have sibling nodes with the same name (see §22Same-NameSiblings). In repositories that do notsupport same-name siblings this attribute has no effect.
Mixin node types areused to add additional properties or child nodes to a given nodeinstance, typically in order to expose some aspect of a specializedrepository feature. For example, referenceability is supported bythe mixinwhich defines the propertyto expose a node's identifier (see §3.3Identifiers).
Mixin node types applyto specific node instances within a workspace, allowing therepository to decouple support for some repository features from theprimary node type assigned to that node. In effect, mixin node typespermitper instance node type inheritance. In a writablerepository mixin node types can be assigned to a node during itslifetime, not just upon creation.
A mixin node type mayhave one or more supertypes, which must also be mixin types.Additionally, a mixin node type can serve as a supertype of aprimary type. This is typically done to build a mixin-linked featureinto a primary node type. For example, if a repository requires allnodes of typeto be referenceable it can specify thatas a supertype of.
A mixin node typecannot be used by itself as the node type of a node. A primary nodetype is always required.
A mixin node typemaybe part of an inheritance hierarchy. A primary node (other than)must at least be a subtype of the common base primary type,(see §3.7.10Base Primary NodeType). The semantics of inheritance are defined by the followingrules.
Thesupertype relation istransitive: IfT1 is a supertype ofT2andT2 is a supertype ofT3thenT1 is a supertype ofT3.
Thesupertype relation alwaysand only stems from explicitsupertypes attributedeclarations within the set of node types: ForT1to be a supertype ofT2 it isnotsufficient that the item definitions ofT2be a superset of the item definitions ofT1.For that to be the case,T2 mustdeclareT1 as a supertype.
Thesubtype relation is theconverse of supertype:T1 is a subtype ofT2 if and only ifT2is a supertype ofT1. Hence, subtype isalso a transitive relation.
Theis-of-type relation whichholds between node instances and node types (as in, nodeN isof typeT) is transitive across thesubtype relation:IfN is of typeT2 andT2is a subtype ofT1 thenN is (also)of typeT1. This predicate appears in theAPI as the method(see §8.6Node Type Information for Existing Nodes). Thisrelation is also the one that is relevant in the child nodedefinition attributerequired primary node types (see§3.7.4.1Required Primary Node Types).
Theis of type relation alwaysand only stems from an explicit assignment of a node type to a node:For nodeN to be of typeT it isnot sufficientforN to have the child items declared byT. For thatto be the case,N must beexplicitly assigned the typeT, or a subtype ofT.
As mentioned (see§3.7.1.3Abstract), a node type may be declared abstract,meaning that it cannot be assigned as the primary or mixin node typeof a node but can be used in the definition of other node types as asupertype.
Thecomplete set of node type constraints on a particular node isreferred to as that node'seffectivenode type. This consists of the sum ofall attributes
declaredin that node's primary type,
inheritedby that node's primary type,
declaredin that node's mixin node types, and
inheritedby that node's mixin node types.
The summing of theseattributes must conform to the semantics of subtyping defined inthis section.
The general principleguiding inheritance is to preserve theis-a relation acrosssubtyping. This implies that ifT' is a subtype ofTandN is a valid instance ofT' then:
N must be a valid instanceofT.
A method call that depends on thetruth of the testN is of type T must not failsolelydue toN being of typeT'.
IfT' is asubtype ofT then the following must hold:
The name ofT' must differ fromthe name ofT.
The supertypeslist ofT' must include eitherT or a subtype ofT.
IfT is aprimary type,T' must be a primary type. However, ifTis a mixin thenT' may be either a mixin or a primary type.
IfT has orderable child nodesthenT' must have orderable child nodes.
IfT specifies a primary itemIthenT' inherits that setting and must not specify a primaryitem other thanI.
T' may declare any number ofproperty definitions as long as they are not invalid (see §3.7.6.8Item Definitions in Subtypes).
T' may declare any number ofchild node definitions as long as they are not invalid (see §3.7.6.8Item Definitions in Subtypes).
IfT is aregistered node type andT' is the definition of a subtype ofT that meets the criteria in the preceding sections, then anitem definitionD' inT' is eitheradditive,overriding orinvalid, as determined by the followingalgorithm:
IfD' isnot statically valid thenD' is invalid.
IfD' is aresidual definition thenD' is additive.
If theredoesnot exists a definitionD inT with a name andclass (i.e., eithernode orproperty) identical tothat ofD' thenD' is additive.
If theredoesexist a definitionD inT with name and classidentical to that ofD' thenD' is overriding if:
Theimplementation supports item definition overrides in this instance(implementations are free allow or disallow overrides globally oron an instance-by-instance basis)
IfD is aproperty definition thenD andD' have identicalmultiple settings and any property values valid againstD'would also be valid againstD.
IfD is achild node definition thenD andD' have identicalsame-name sibling settings.
IfD isautocreated, mandatory or protected thenD' must be,respectively, that as well.
Otherwise,D'is invalid.
IfD' isadditive then whenT' is registeredD' becomespart ofT' alongside all item definitions inherited fromT.
IfD'overridesD then whenT' is registeredD' replaces thedefinitionD that would otherwise have been inherited fromT.
IfD' isinvalid thenT' cannot be registered.
The rules ofinheritance will have most impact on repositories that allow
a wide latitudein assigning mixins to nodes,
registration ofcustom node types (see §19NodeType Management) or, in particular,
registration ofcustom node types with multiple super types (multiple inheritance).
In fixed node typerepositories (those without support for mixin assignment or nodetype registration), adherence to the inheritance rules is simply amatter of ensuring that the correct relations hold among thestatically defined node type that the system exposes.
Though there may bemore than one definition in the parent node's type thatcouldapply to the child item, the definition that does apply isdetermined by the implementation and remains constant through thelifetime of the item.
In writablerepositories the applicable item definition is determined at itemcreation time.
The node type of theroot node of each workspace is implementation-determined. There areno restrictions other than those implied by the feature set of therepository. For example, a repository that exposes system data underwill necessarily have a root node of a type that allows achild node.
The node typedefinitions shown in this specification use thecompact node typedefinition (CND) notation (see §25.2Compact Node TypeDefinition Notation).
Someof the attributes of the node types defined in this specificationmay vary across implementations. For example, it isimplementation-dependent which node types and which properties arequeryable (see §3.7.1.5Queryable Nodeand §3.7.3.3Available QueryOperators). Similarly, some of thestandard application node types (see §3.7.11StandardApplication Node Types) may vary as totheon-parent-versionandprotectedstatus of some properties. In the CND notation, variant attributesare indicated with either a question mark (for example,and)or, in the case of the queryable node type attribute, by the absenceof an explicit indicator. For the queryable attribute of a node typeto be non-variant it must be explicitly defined using the keywordsor,(see §25.2Compact Node Type Definition Notation).
All repositories mustsupply thebase primary node type,,as a built-in type.
is an abstract primary node type that is the base type for all otherprimary node types. It is the only primary node type withoutsupertypes.
exposes type information about a node through the properties,and.
Since every otherprimary type must be a subtype of(see §3.7.6.2Subtype Relation), every primary node typewill inherit these two type-reflective property definitions.
is a protected mandatoryproperty which holds the name of the declared primary node type ofits node. The repository must maintain its value accuratelythroughout the lifetime of the node (see §10.10Node TypeAssignment). Since it is mandatory, every node will have thisproperty.
is a non-mandatory protected multi-valueproperty which holds a list of the declared mixin node types of itsnode. It is non-mandatory but is required to be present on any nodethat has one or more declared mixin types. If it is present, therepository must maintain its value accurately throughout thelifetime of the node (see §10.10.3Assigning Mixin Node Types).
JCR defines a numberof standard application node types designed to support commonapplication-level entities. A repository may supply zero or more ofthese as built-in types (see §24Repository Compliance).
This abstract nodetype serves as the supertype ofandand inherits the item definitions ofand so requires the presence of that node type (see §3.7.11.7mix:created).
Nodes of this nodetype may be used to represent files. This node type inherits theitem definitions ofand requires a single child node called.Thenode is used to hold the actual content of the file. This child nodeis mandatory, but not auto-created. Its node type will beapplication-dependent and therefore it must be added by the user. Acommon approach is to make thea node of type.Thechild node is also designated as the primary child item of itsparent.
Thenode type is similar to,except that the content node is not stored directly as a child node,but rather is specified by aproperty. This allows the content node to reside anywhere in theworkspace and to be referenced by multiplenodes. The content node must be referenceable. Support for this nodetype requires support forreferenceable nodes withreferential integrity (see §3.8.2Referential Integrity).
Nodes of this type maybe used to represent folders or directories. This node type inheritsthe item definitions ofand adds the ability to have any number of otherchild nodes with any names. This means, in particular, that it canhave child nodes of types,or.
This node type may beused to represent the content of a file. In particular, thesubnode of annode will often be an.Note that the definition of this node type indicates multipleinheritance (see §3.7.6Node Type Inheritance).
This mixin node type can be used toadd standardized title and description properties to a node.
This mixin node typecan be used to add standardized creation information properties to anode. In implementations that make these properties protected, theirvalues are controlled by the repository, whichshould setthem appropriately upon the initial persist of a node with thismixin type. In cases where this mixin is added to an alreadyexisting node the semantics of these properties are implementationspecific (see §10.10.3Assigning Mixin Node Types).
This mixin node type can be usedto provide standardized modification information properties to anode. In implementations that make these properties protected, theirvalues are controlled by the repository, which shouldset them appropriately upon a significant modificationof the subgraph of a node with this mixin. What constitutes asignificant modification will depend on the semantics of the variousparts of a node's subgraph and is implementation-dependent.
This mixin node type can be usedto provide a standardized property thatspecifies the natural language in which the content of a node isexpressed. The value of theproperty should be a language code as defined in RFC 46465.Examples include “”(English), “”(United States English), “”(German) and “”(Swiss German).
This mixin node typecan be used to provide standardized mimetype and encoding propertiesto a node.
If a node of this typehas a primary item that is a single-valueproperty thenproperty indicates the media type6applicable to the contents of that property and, if that media typeis one to which a text encoding applies, theproperty indicates the character set7used.
If a node of this typedoes not meet the above precondition then the interpretation of theandproperties is implementation-dependent.
This node type may beused to represent the location of a JCR item not just within aparticular workspace but within the space of all workspaces in allJCR repositories.
Theproperty stores a string holding the protocol through which thetarget repository is to be accessed.
Theproperty stores a string holding the host name of the system throughwhich the repository is to be accessed.
Theproperty stores a string holding the port number through which thetarget repository is to be accessed.
The semantics of theseproperties are left undefined but are assumed to be known by theapplication. The names and descriptions of the properties are notnormative and the repository does not enforce any particularsemantic interpretation on them.
Theproperty stores a string holding the name of the target repository.
Theproperty stores the name of a workspace.
Theproperty stores a path to an item.
Theproperty stores a weak reference to a node.
In most cases eithertheor theproperty would be used, but not both, since they may point todifferent nodes. If any of the properties other thanandare missing, the address can be interpreted asrelative tothe current container at the same level as the missing specifier.For example, if no repository is specified, then the address can beinterpreted as referring to a workspace and path or id within thecurrent repository.
Itis often useful for an application to be able to quickly findwhether the value of aproperty has changed since the last time it was checked. This isparticularly useful when determining whether to invalidate a cachecontaining a copy of thevalue.
Themixin type defines a standardized identity validator forproperties similar to the entity tags used in HTTP/1.18.
Aproperty is an opaque string whose syntax is identical to thatdefined for entity tags in HTTP/1.1. Semantically, theis comparable to the HTTP/1.1 strong entity tag.
On creation of anode,or assignment ofto, the repository must create aproperty with an implementation determined value.
The value of theproperty must change immediately on persist of any of the followingchanges to:
Aproperty is added to.
Aproperty is removed from.
The value of anexistingproperty ofchanges.
Supportfor unstructured content may be provided by supporting a free-formnode type:.Support for this node type requires support for theproperty type value.
This node type is usedto store unstructured content. It allows any number of child nodesor properties with any names. It also allows multiple nodes havingthe same name as well as both multi-value and single-valueproperties with any names. This node type also supportsclient-orderable child nodes.
A repository mayexpose the definitions of its available node types in content usingthe node types,and.If a repository exposes node type definitions in content, then thatrepository must also support the system node (see §3.11SystemNode) and the node type definitions should be located below.Support for these node types also requires support for same-namesiblings (see §22Same-Name Siblings).
This node type is usedto store a node type definition. Property and child node definitionswithin the node type definition are stored as same-name siblingnodes of typeand.
This node type used tostore a property definition within a node type definition, whichitself is stored as annode.
This node type used tostore a child node definition within a node type definition, whichitself is stored as annode.
The attributes thatmake up a node type definition may in some cases have no set value(for example, some child node definitions may not define adefaultprimary type). To store this information (i.e., the lack of avalue) in an,ornode the property representing that attribute must simply be notpresent, since null values for single-value properties are notpermitted (see §10.4.2.4No Null Values).
To indicate that aproperty or child node definition is residual, the value returned byis “”.However, “”is not a valid value for the propertyin anornode (becauseit is aproperty, not a).As a result, an in-content definition of a residual item will simplynot have aproperty.
JCRdefines a number of node types in order to support specificrepository features. Descriptions of these node types are found intheir corresponding feature sections. The following list summarizesthe node types and their associated features:
ReferenceableNodes:(see §3.8Referenceable Nodes).
Locking:(see §17Locking).
Shareable Nodes:(see §3.9Shareable Nodes Model).
Lifecycles:(see §18Lifecycle Management).
Versioning:,,,,,,(see §3.13Versioning Model).
An implementationmayprovide a variant of a JCR node type as a built-in under certainconditions.
Such a variant musthave the same name as the canonically defined type and thus replaceit in that implementation's set of available node types.
An implementation mayalter the definition of a JCR node type by adding supertypes. Theseadditional supertypes may be either JCR mixin node types orimplementation-specific mixin or primary node types. For example, arepository may require that all nodes of typebe, additionally,.In such a repository the definition of,when introspected, would report an additional supertype of.
This extensionmechanism is distinct from the automatic addition of mixin typesthat may be done on node creation (see §10.10.3.3AutomaticAddition and Removal of Mixins). Though the two features mayboth be employed in the same repository, they differ in that oneaffects the actual hierarchy of the supported node types, while theother works on a node-by-node basis.
An implementation maymake abstract a JCR node type that is not canonically abstract. Forexample, some implementations might useas is, whereas others might subtype it in order to introduceimplementation specific item definitions. Such implementations wouldtherefore designateas abstract.
An implementation mayvary the value of a node type or child definition attribute that isexplicitly indicated as a variant in the node type definitions givenin this specification. For example, any node type defined in thisspecification may be either queryable or non-queryable, depending onthe implementation. Also, the protected and OPV settings of theproperties of the metadata mixins (,,,and)are also variant.
Anexternal nodetype is one defined outside this specification. It may be eitheran implementation-specific type built into a repository or a nodetype defined and registered by a user (see §19Node TypeManagement).
The followingrestrictions apply to all external node types:
An implementationmust not allow external node types with node type names inthe,,ornamespaces.
An implementationmay allow external node types which have item definitions in thenamespace. Such an item definition must only reuse an itemdefinition from a JCR-defined node type.
Any jcrnamespaced item definitionD' in an external node typeT'must not be invalid with respect to the JCR-defined definitionDin the JCR-defined nodeT (withD,D',TandT' as above, see §3.7.6.8Item Definitions inSubtypes).
Any jcrnamespaced item definition in an external node type must be usedfor a purpose equivalent to its JCR use.
All custom nodetypes must adhere to semantics of subtyping (see §3.7.6.6Semantics of Subtyping)
A repository maysupportreferenceable nodes. A node must be referenceable toserve as the target of areference property, which is eitheraor.To be referenceable a node must be of type.
This node type adds anauto-created, mandatory, protectedproperty to the node, called,which exposes the identifier of the node. Note that the term “UUID”is used for backward compatibility with JCR 1.0 and does notnecessarily imply the use of the UUID syntax, or global uniqueness.
The identifier of areferenceable node must be areferenceable identifier.Referenceable identifiers must fulfill a number of constraintsbeyond the minimum required of standard identifiers (see §3.8.3Referenceable Identifiers).
A reference propertyis a property that holds the referenceable identifier of areferenceable node and therefore serves as a pointer to that node.The two types of reference properties,anddiffer in that the former enforces referential integrity while thelatter does not (see §3.8.2Referential Integrity). Arepository may support onlyor bothandproperty types.
Given a propertywith valuein workspace
Ifis of typethen there must exist a node inwith identifier.
Ifis of type,no such restriction exists.
In a read-only contextthe only difference between the types is that a workspace cannotcontain a danglingwhile it may contain a dangling.
In a repository thatexposes version storage in content, such as one that supportsfullversioning, an exception is made to the referential integrityrule when theproperty in question is part of the frozen state of a version storedin version storage. In that case the frozenproperty may hold the identifier of a node that is no longer in theworkspace (see §3.13.3.7References in a Frozen Node).
Every node has anidentifier, where an identifier is a string which is the most stableavailable. Areferenceable node, however, must have areferenceable identifier, which is subject to a number offurther constraints:
As with any identifier, areferenceable node's identifier must be assignedat the latestwhen the node is first persisted. However, theproperty of the node must be created immediately upon the nodebecoming referenceable, which may be upon node creation or upon alater mixin addition. Consequently, the value of theproperty before the first persist is not guaranteed to be theidentifier of the node.
The identifier is immutable during thelifetime of the node, that is, until the node is deleted though aoperation. In particular, the identifier is immutable acrossandoperations. Note that non-referenceable identifiers arenotrequired to be immutable across these operations. As in thenon-referenceable case, the referenceable identifier is notimmutable acrossoperations. This operation results in the creation of a new nodewith a new identifier.
These are the minimum requirements fora referenceable identifier, but implementations are free to exceedthese requirements.
The ability to addressthe same piece of data via more than one path is a common feature ofmany content storage systems. In JCR this feature is supportedthroughshareable nodes.
Two or more shareablenodes in the same workspace may belong to a shared set. Each nodewithin that set has its own unique path within the workspace but allshare exactly the same set of child nodes and properties. This meansthat while the shared nodes are distinct from a path perspective,they are effectively the same node for purposes of operations thataccess their common subgraph.
In order to beshareable, a node must of type:
All shareable nodesare referenceable.
Given two distinctshareable nodesA andB whereA shares withB,the following facts hold:
A andBare in the same shared set.
B shareswithA (sharing is a symmetric relation).
IfBshares withC thenA shares withC (sharing isa transitive relation).
If itemIis a child ofA thenI is also a child ofBand has the same name relative to bothA andB.
A andBhave the same identifier.
A andBare in the same workspace
A andBhave distinct paths.
Each node in a sharedset shares the same child nodes. In particular, the addition orremoval of a child from a shared nodeautomatically adds or removes that child from all the nodes in theshared set of.
For example, supposethe following nodes exist:
Suppose a shared nodeatis created and shares with the shareable node at.Since the children ofare automatically added to,a child named “”is automatically added to.Therefore, as a result of creating,the following paths are associated with nodes:
whereis a new node that shares with,identifies the same node as,identifies the same node as,andidentifies the same node as.
Subsequently, when anew child named “”is added to eitheror,that child is automatically added to bothand.Conversely, when a child named “”is removed from eitheror,the child named “”is removed from bothand.
E
achnode in shared set shares the same properties and their respectiveproperty values. When a change, addition or removal of a property ofone node in a shared set is made, that change, addition or removalis immediately reflected in the properties of each node in theshared set.
Theabove diagram shows a share set of three nodes,,and,which share the child nodesandand the property.
A descendant item of ashared set will have more than one valid path (assuming the sharedset has at least two members). When the parent node or path of sucha descendant item is requested, an implementation must choose adeemed path to return.
How the deemed path ischosen and its stability both over time and across the set ofdescendent items is an implementation issue.
In particular, it ispermissible for an implementation to choose deemed paths for twosibling items where those paths differ by more than just the lastelement. It is also permissible for the deemed path of an item tochange from one request to the next on the same item within the samesession.
Though mostimplementations are expected to support deemed paths which are morestable than this, flexibility of the deemed path is provided tofacilitate implementations which would otherwise not be able tosupport shareable nodes.
Given the followingsituation:
Nodeis an ancestor of node
is in the shared set
is also in the shared set
is an ancestor of
is a descendent of
The followingterminology applies:
is anancestor of(as usual).
is ashare-ancestor of the setand of the individual nodes,and (trivially),.
Sinceis adescendent ofit is also adescendent of every node in(,for example). We also say that it is adescendent of the set
Sinceis ashare-ancestor ofandis adescendent of,is anancestor (proper) of.
Note that the termshare-ancestor does not meanshared ancestor. Theancestor (proper) of a member of a shared set is not necessarily anancestor (proper) of any other member of that set.
When a node isrequested by identifier and that identifier references a shared setof nodes with more than one member the repository must return onemember of that set. How this node is chosen is an implementationissue. In general, a user that interacts with repositories thatsupport shareable nodes must be prepared to deal with differentnodes having the same identifier.
Ashare cycleoccurs when a node is in the same shared set as one of itsancestors. A repository implementationmay prevent theoccurrence of share cycles. In such implementations any method callthat would cause a cycle will fail.
In a repository withmore than one workspace, a node in one workspacemay havecorresponding nodes in one or more other workspaces.
Given a repositoryRwith workspacesW0,W1,...Wkand a nodeN0 inW0with identifierI0 then for each workspaceWx inR, ifWxhas a nodeNx with identifierI0,Nx is a corresponding node ofN0.Some corollaries include:
Every node corresponds to itself.
A non-shared node has at most onecorresponding node per workspace. In repositories that supportshareable nodes the nodes within a shared-set have the sameidentifier and therefore a node in another workspace with thatidentifier will have more than one corresponding node in thatworkspace (see §3.9Shareable Nodes Model).
Apart from having thesame identifier, corresponding nodes need have nothing else incommon. They can have different sets of properties and child nodes,for example.
The root nodes of allworkspaces in a repository all have the same identifier, andtherefore correspond to one another.
Themechanism of correspondence allows two nodes in separate workspacesto be related by a common identifier while maintaining distinctstates. This relation is used to model cases where copies of acommon content structure must be maintained separately.
JCRprovides methods for transferring state between workspaces throughclone andupdate(see §10.7.2Copying Across Workspaces and §10.8Cloning and Updating Nodes).
Insystems that support versioning, corresponding nodes in separateworkspaces share the same version history (see §3.13.7Versioningand Multiple Workspaces).
T
heabove diagram depicts two workspacesand.Nodeinand nodeinare corresponding nodes. Note that the subgraphs of correspondingnodes may differ, as they do in this case.
The locationis reserved for use as a “system folder”. Some implementationsmay use this location to expose repository-internal data as content.
If a repositoryexposes node type definitions in content, then those node typedefinitionsshould be located at(see §3.7.14Node Type Definition Storage).
If a repositorysupports full versioning, then itmust expose the versionstorage at.If it supports only simple versioning then itmay expose theversion storage (see §3.13.8Version Storage).
Similarly, if animplementation supports activities (see §15.12Activities)or configurations and baselines (see §15.13Configurations andBaselines), the in-content representations of these entities arestored underand,respectively.
Ifis supported, its node type is left up to the implementation.
Implementers thatbuild a JCR repository on top of an existing repository thatsupports content objects which exist outside of a hierarchicalstructure may expose these objects as nodes below(see §3.11System Node).
The hierarchicalstructure belowis implementation-dependent.
JCR implementers maydisallow discovery (listing) of the nodes beneath this folder. Insuch a case a call to()on thenode would throw a.
JCR implementers mayexpose the nodes belowto search through the query mechanism (see §6Query).
Versioning enables auser to record the state of a node and its subgraph and restore thatstate at a later time. A repository that supports versioning maysupport either the complete set of versioning features, referred toasfull versioning, or a specific subset defined here, whichis referred to assimple versioning. This section describesthe concepts, data structures and node types of the full versioningmodel as well as which parts of that model apply under simpleversioning. Discussion of the versioning API and its behavior underboth levels of support is found in §15Versioning.
For its state to berecorded in a version, a node must beversionable.
When a versionablenode ischecked-in, a newversion of that node iscreated which contains a (typically partial) copy of its subgraph.The part of a node’s subgraph that is to be copied to a version isreferred to as itsversionable state. A node’s versionablestate is determined by theon-parent-version attribute ofeach of its subitems, as defined in its node type (see §3.7.2.5On-Parent-Version).
Once created, aversion is stored in aversion history. Within a givenworkspace, each non-shared versionable node has its own versionhistory which contains aversion graph that records theposition of each version in relation to its direct predecessor anddirect successor versions.
is adirect successor ofif and only ifis adirect predecessor of.
A versionis aneventual successor of a versionif and only ifis a direct successor ofor there exists a versionsuch thatis a direct successor ofandis an eventual successor of.
Similarly, a versionis aneventual predecessor of a versionif and only ifis a direct predecessor ofor there exists a versionsuch thatis a direct predecessor ofandis an eventual predecessor of.
When the termssuccessor andpredecessor are used withoutqualification they meandirect successor anddirectpredecessor, respectively.
Under simpleversioning, each new version is always added as the unique directsuccessor of the previous version, thus maintaining a linear seriesof versions.
Under full versioning,a new version may be added as the direct successor of a version thatalready has another direct successor, thus producing abranch.A new version may also be added as the direct successor of more thanone existing version, thus producing amerge.
Version histories arestored in a repository-wideversion storage. Under fullversioning this store is exposed both through the Java objects ofthe versioning API as well as in a read-only subgraph reflected ineach workspace. Within that subgraph version histories arerepresented as nodes of typeand versions as nodes of type.Under simple versioning, the version store is exposed through theversioning API but is not required to be exposed as a node subgraph.
Once checked-in, a versionable nodeand its versionable subgraph becomeread-only. To alter achecked-in node or its versionable subgraph, the node must first bechecked-out. It can then be changed and checked-in again,creating a new version.
A versionable node and its versionablesubgraph can also berestored to the state recorded in one ofits versions.
Under simpleversioning, a versionable node must be.Under full versioning, it must be.
Thetype exposes the node’schecked-out status as aproperty.
A new version of aversionable node is created bychecking-in a versionable node(see §15.2Check-In: Creating a Version). In this state thenode and itsversionable subgraph areread-only (see§15.2.2Read-Only on Check-In). The node can then bechecked-out(see 15.3Check-Out), at which point itbecomes writable again.
Under both simple andfull versioning, this status is accessible through(see §15.3.1.1Testing for Checked-Out Status) and theproperty.
The mixinis a subtype ofand,and adds properties exposing a number of additionalversioning-related attributes.
Apart from nodeswithin the same shared set, which share the same version history,each versionable node within a persistent workspace has its ownversion history.
Under both simple andfull versioning the version history of a node is accessed through,which returns aobject (see §15.1.1VersionHistory Object). Under fullversioning it is also represented by theproperty,which points to annode (see §3.13.5.1nt:versionHistory).
Each versionable nodehas abase version within its version history. When a newversion of a node is created, it is placed in that node’s versionhistory as a direct successor of the base version. That versionitself then becomes the new base version (see §3.13.6.2BaseVersion).
Under simpleversioning, the base version of a versionable node is always themost recent version in its version history.
Under full versioning,corresponding versionable nodes in different workspaces, whilehaving the same version history, may have different base versionswithin that history. Therefore, the base version of a fullversionable node may not be the most recent version in that node'sversion history (see §3.13.6.2Base Version).
The base version isaccessed through(see §15.1.2Getting the Base Version) which returns aobject (see 15.2.1Version Object). Under full versioning theconnection to the base version is also represented by theproperty,which points to annode (see §3.13.2.3mix:versionable).
Under full versioning,a versionable nodehas one or more versions in its version history that will becomedirect predecessors of the new versioncreated on the next check-in of.For convenience these versions can also be referred to as the directpredecessors of(i.e., not just the direct predecessor of the hypothetical.
The base version ofis alwaysone of these direct predecessors, butmay have additional direct predecessors as well. If so, on check-inof,all of these become direct predecessors of the newly created version,thus forming a merge within the version graph (see §15.9Merge).
A node’s directpredecessors are exposed by the multi-valueproperty(see §3.13.2.3mix:versionable) which points to one or morenodes (see §3.13.3.1nt:version).
There is no dedicatedAPI for accessing the direct predecessors of aversionablenode; access is provided through the property only (thisshould not be confused with access to the direct predecessors of aversion, which is exposed through the API, see §3.13.2.6Predecessors).
Under simpleversioning, theattribute is not needed (and hence not present on)since a versionable node will only ever have one direct predecessor,which is its base version.
Under full versioning,is a multi-valueproperty that is used to mark merge failures (see §15.9Merge).Under simple versioning, merges are not supported. There is nodedicated API for accessing merge failures; access is provided onlythrough this property.
Under full versioning,is aproperty used to support the activities feature (see §15.12Activities). Under simple versioning, activities are notsupported. There is no dedicated API for retrieving the activityassociated with a given versionable node; access is provided onlythrough this property.
Under full versioning,is aproperty used to support the configurations and baselines feature(see §15.13Configurations and Baselines). Under simpleversioning, configurations are not supported. There is no dedicatedAPI for retrieving the configuration associated with a givenversionable node; access is provided only through this property.
Under simpleversioning, a version is represented by aobject (see §15.2.1Version Object) and the attributes ofthe version are accessible only through methods of that class.
Under full versioninga version is represented by both aobject and a node of typewithin the version storage (see §3.13.7Version Storage).The attributes of a version are accessible both through methods oftheclass and through the properties of.
Each version has aname unique within its version history that is assignedautomatically on creation of the version. The format of the name isimplementation-dependant. Under full versioning this is the name ofthenode representing the version. Under simple versioning this issimply the name returned whenis called on theobject.
is a subclass of.However, since under simple versioning a version is not representedby a node, most of themethods inherited byare not required to function. The single exception isas mentioned above. Under full versioning themethods inherited byfunction as expected on thenode.
Under full versioningthenodes representing the versions within a given history are alwayscreated as direct child nodes of thenode representing that history.
inherits thefrom,making everynode referenceable. Additionally, it defines properties that exposethe following attributes.
Each version recordsits creation date, which is accessible throughand, under full versioning, through theproperty of.
Each version has zero or more directpredecessor versions within its version history, accessible though.Under simple versioning, a version will have either zero directpredecessors (if it is the root version of a history) or one directpredecessor. Under full versioning, a version may have zero, one, ormore direct predecessors, which are exposed through themulti-valueproperty of.
Each version has zero or more directsuccessor versions within its version history, accessible though.Under simple versioning, a version will have either zero or onedirect successors. Under full versioning, a version may have zero,one, or more direct successors, which are exposed through themulti-valueproperty of.
Each version recordsthe versionable state of its versionable node at the time ofcheck-in in afrozen node, attached to the version andaccessed though.Under simple versioning, the frozen node is isolated, having noparent in any workspace. Under full versioning, it is a subnode ofthenode in the version storage subgraph. In both cases the node is oftype(see §3.13.4.1nt:frozenNode).
Under full versioning a version may bebound to an activity. This relationship is recorded by theproperty ofpointing tonode that represents the activity under which this version wascreated (see §15.12Activities). Under simple versioningactivities are not supported.
When a version iscreated, theversionable subgraph of its versionable node iscopied to afrozen node within the new version. On check-inthe child nodes and properties that constitute the versionablesubgraph are copied and placed as child items of the frozen nodeunder the same names as they had under the versionable node.
Which child nodes andproperties are copied, and in the case of child nodes, the depth ofthe subgraph to be copied, constitutes the versionable state of thenode and is determined by the on-parent-version settings defined inthe node type of the versionable node (see §3.7.2.5On-Parent-Version).
Regardless of the nodetype of the original versionable, all frozen nodes are of the type.Under both simple and full versioning, the frozen node of a versionis accessible directly from theobject (see §15.2.1Version Object). Under full versioning,the frozen node is also accessible as the child nodeof thenode. Under simple versioning the frozen node is aobject but does not have a parent, and consequently methods calledon the frozen node that depend upon having a parent will throw anexception. Under full versioning the frozen node's parent is thenode to which it belongs.
A frozen node alwayshas the name.Under full versioning this is the name under which it exists as achild of itsnode. Under simple versioning this is simply the name returned whenis called on the frozen node.
defines the following properties and child nodes.
is aproperty that stores the primary node type of the versionable node.
is a multi-valueproperty that stores the mixin types of the versionable node, ifany.
is aproperty that stores the referenceable identifier of the versionablenode. Note that the term “UUID” is used for backwardscompatibility with JCR 1.0 and does not necessarily the use of theUUID syntax, or global uniqueness.
A set of residualdefinitions are defined for the copies of the properties and childnodes that make up the versionable state of the versionable node. Inrepositories that do not support residual item definitions (see§3.7.2.1.2Item Definition Name and Residual Definitions)these must be implemented as a special case for the frozen node.
Aproperty stored in the frozen node of a version does not enforcereferential integrity. Under simple versioning this follows from thefact that awithin a frozen node does not appear within the workspace in anycase, it only appears when the frozen node is explicitly retrievedthrough theobject (see §15.2.1Version Object). Under full versioning awithin a frozen node will appear in the workspace within theread-only version storage (see §3.13.8Version Storage) sothe referential integrity requirement must be lifted as a specialcase.
Under simpleversioning a version history is represented by aobject (see §15.1.1VersionHistory Object). Under fullversioning a version history is represented by both aobject and a node of type.
A version history iscreated upon creation of a new versionable node. Under fullversioning this results that annode being created automatically within the version storage subgraphin an implementation determined location and with animplementation-determined name.
is a subclass of.However, since under simple versioning a version history is notrepresented by a node, themethods inherited byare not required to function. Under full versioning those methodswill function as expected on thenode representing the history.
This type inherits thefrom,making everynode referenceable. It also defines properties and child nodesrepresenting the following attributes.
Each version historyhas aroot version, which is a null version that stores nostate; it simply serves as the eventual predecessor of allsubsequent versions.
The root version isaccessed through(see 15.1.1.1Root Version). Under full versioning it is alsorepresented as anchild node of thenode, called.
In addition to theroot version, a version history also holds all the versions thathave been created through check-ins of its versionable node (ornodes, in the case of corresponding or shared nodes). These versionsare accessible through,and.
Under full versioningthese versions are also accessible aschild nodes of thenode, under their respective implementation-determined names.
Each version historyalso stores the identifier of its versionable node (or nodes in thecase of corresponding or shared nodes).
This attribute isaccessible throughand, under full versioning, through thepropertyof.Note that the term “UUID” is used for backward compatibilitywith JCR 1.0 and does not necessarily imply the use of the UUIDsyntax, or global uniqueness.
A version label is aJCR name, unique among the labels within a version history, thatidentifies a single version within that history. A version can havezero or more labels.
Labels are can beassigned, removed and retrieved through the API. Versions can alsobe retrieved by label (see §15.4Version Labels).
Under full versioninglabels are also exposed through anchild node ofcalled.This node holds a set of reference properties that record all labelsthat have been assigned to the versions within this version history.Each label is represented by a single reference property which usesthe label itself as its name and points to thatchild node to which the label applies (see §15.4.1.2Adding aVersion Label). Thenode type has the following definition:
When a fullversionable node is copied to a new location and the repositorypreserves themixin (see §10.7Copying Nodes), the copy gets a new versionhistory and that history records the base version of the node fromwhich the copy was created. This information, known as the node'slineage, is recorded in theproperty of(see §15.1.4 Copying Versionable Nodes and Version Lineage).
The versions within aversion history form aversion graph where the versions arethe vertices and eachdirect successor/direct predecessorpair are joined by a directed edge.
Under simpleversioning, branching and merging are not supported, so the versiongraph is always a linear series of successive versions.
Under full versioningbranching and merging are supported, so a version may have multipledirect predecessors, multiple direct successors, or both. Also,under full versioning, the version graph is exposed in content withnodes as the vertices and the edges defined by thepropertiesand.
The version graphalways contains at least the root version. This is a null versionthat stores no state and simply serves as the eventual predecessorof all subsequent versions. Its frozen node does not contain anystate information about the versionable other than the node type andidentifier information found in the properties,,and.
For a givenversionable node, one version within its version history is itsbaseversion.Conceptually, the base version of a versionable node isthat version relative to which the current state of the checked-outversionable node constitutes a versionable change.
On check-in, the newlycreated version becomes a direct successor of the current baseversion and then itself becomes thenew base version.
Under full versioning,corresponding versionable nodes in different workspaces, whilesharing the same version history, may have distinct base versionswithin that history. This means that when one versionable node ischecked-in, its version will become direct successor of a particularexisting version but when one of its correspondees is checked in,that new version may become direct successor to adifferentexisting version within the same version history.
Under simpleversioning the linearity of the version graph guarantees that thecurrent base version is always the most recent version. On check-init becomes the unique direct predecessor of the newly createdversion, which then becomes the new base version.
Under full versioning,the presence of branches and merges means that the current baseversion for a given versionable node is not guaranteed to be themost recent version.
Asmentioned (see 3.13.2.5BaseVersion Reference and 3.13.6.2BaseVersion), under full versioning,corresponding versionable nodes in different workspaces all have asingle common version history, though within that history each mayhave a distinct base version at any given time.
Theintended semantics of the correspondence relationship is thatcorresponding nodes represent copies of a common content structurewhich while identical at one level (i.e., as determined byidentifier),can be maintained in distinct states (see §3.10.1.2CorrespondenceSemantics).
Therelation of corresponding versionable nodes to the same versionhistory reflects these semantics in that when different copies ofthe same content entity are changed and checked-in from differentworkspaces the resulting versions are all recorded within the sameversion graph and, depending on their individual base versions,extending that graph at different points.
Version histories arestored in a single, repository-wide version storage mutable andreadable through the versioning API.
Under full versioningthe version storage data must, additionally, be reflected in eachworkspace as a protected (see §3.7.2.2Protected) subgraphof nodes of typelocated below(see §3.11System Node). Because it is protected, thesubgraph cannot be altered through the core write methods of JCR(see §10.2Core Write Methods) but only through though themethods of the versioning API.
Though the general repository-wideversion history is reflected in each workspace, the access that aparticulargets to that subgraph is governed by that'sauthorization, just as for any other part of the workspace.
Thenodes below,may all be direct children of thenode or may be organized in a deeper substructure of interveningsubnodes that sort the version histories by someimplementation-specific criteria.
The node type of the nodeand any structural nodes used within the subgraph are left up to theimplementation.
Theversionablestate of a versionable nodeis typically asubset of its subgraph. The extent of thissubset is defined in the node type ofthrough theon-parent-version attribute (OPV) ofeach of its child items (see §3.7.2.5On-Parent-Version).
A frozen nodestoring the versionable state of the nodeis constructed as follows:
The primary typeofN is copied from theproperty ofN to theproperty ofF.
The mixin typesofN(if any) are copied from theproperty ofN to theproperty ofF.
The referenceableidentifier ofN is copied from theproperty ofNto theproperty ofF.
For each propertyofother than,andwhere
has an OPV ofor
has an OPV of,
acopy ofis added to the frozen node, preserving its name and value (orvalues).
For each childnodeofwhere
has an OPV of,
acopy of the entire subgraph rooted at(regardless of the OPV values of the sub-items) is added to thefrozen node, preserving the name ofand the names and values of all its sub-items.
Ina repository that supports orderable child nodes, the relativeordering of the set of child nodesthat are copied to the frozen node is preserved. As is the orderingwithin the subgraph of each of these child nodes.
For each childnodeofwhere:
has an OPV of
Undersimple versioning, the same behavior as.
Underfull versioning, ifis not,the same behavior as.
Underfull versioning, ifis,then a specialnode with a reference to the version history ofis substituted in place ofas a child of the frozen node. Thenode has the same name asand, in a repository that supports orderable child nodes, therelative ordering of any such child nodeis preserved. The definition ofis:
Thepropertypoints to theof.
The above diagramdepicts the main elements of the full versioning model. A workspacecontains a versionable nodewith child nodesandand property.The on-parent-version settings of each child are shown.has an OPV ofwhilehas an OPV of.is itself versionable and has an OPV of.
is thenode holding the version history ofwhich, in the situation depicted, consists of the versions,,,and,whereis the root version,is the successor of,andare both successors of(constituting abranch) andis the successor of.
is the current base version ofand is shown in detail. As defined by the OPV values of the childrenof,contains a partial copy of'ssubtree in its frozen node. This partial copy consists of thesubtree rooted at(sinceinhas an OPV of)but does not include the property(sinceinhas an OPV of).Sinceis itself versionable it has its own, separate, version history atand since it has an OPV of,is represented in the frozen subtree ofby annode that points to.
The above diagramdepicts the main elements of the simple versioning model. Unlikeunder full versioning, the connections from the versionable node tothe version history and the base version are not mediated byreference properties but through API methods only. As well, theversion history and its contained versions are represented only byJava object instances (of classesand,respectively) not by nodes. Finally, as the diagram indicates, undersimple versioning the version history is always linear and theon-parent-version setting and associated structures are notsupported.
The above diagramdepicts two workspaces,andcontaining corresponding nodesand,both versionable. Because the two versionable nodes correspond, theyshare the same version history, as shown by their respectivereferences both pointing to the samenode. Despite sharing the same history, at any given time,corresponding nodes may have distinct base versions within thathistory. In this diagram the base version ofiswhile the base version ofis.