There are three typesof read access which a session may have with respect to a particularitem, depending on that session's permissions: direct access,traversal access and query access.
Direct accessto an item means being able to retrieve it by absolute and relativepath and, in the case of nodes, by identifier.
Letreturn the normalized absolute path of item, return the normalized relative pathfrom itemto itemand,return the identifier of node.
For any sessionand node,the statements below must be either all true or all false. If theyare all true thenhas direct access to,if they are all false thendoes not have direct access to:
returns.
returns.
returns.
returns.
returns.
Ifis the primary item of a nodethenreturns.
Ifis the root node of the workspace thenreturns.
For all nodesto whichhas direct access,returns.
For all nodesto whichhas direct access,returns.
For any sessionand property,the statements below must be either all true or all false. If theyare all true thenhas direct access to,if they are all false thendoes not have direct access to:
If there is nonode at the pathto which S has read access then
returnsand
returns.
returns.
returns.
has read access to the value of(see §9.1Permissions).
Ifis the primary item of a nodethenreturns.
For all nodesto whichhas direct access,returns.
For all nodesto whichhas direct access,returns.
The root node of theworkspace can be acquired with
.
The existence of anode or property at a particular absolute path can be tested forwith
,
and
.
Nodes and propertiescan be acquired by absolute path with
,
and
.
A node can beretrieved by its identifier with
.
Using anidentifier-based absolute path a node can also be retrieved byidentifier with a path-basemethod. For example,
whereis the session andis the identifier.
Existence of nodes andproperties can be tested by path relative to a given node with
and
.
Nodes and propertiescan be acquired via relative path with
and
If a primary childitem is specified by the node type of a node, this item can beretrieved directly from the node with
.
See §3.7.1.7PrimaryItem.
In some repositories anode and property with the same parent may have the same name. Themethodsand specify whether thedesired item is a node or a property. The methodwill return the item at the specified path if there is only one suchitem, if there is both a node and a property at the specified path,will return the node.
Whether animplementation supports this feature can be determined by queryingthe repository descriptor table with
.
A return value ofindicates support (see §24.2Repository Descriptors).
Traversal access to anitemmeans that it is returned when iterating over the children of anode.
For any given sessionand item,the statements below must be either both true or both false. If theyare both true thenhas traversal access to,if they are both false thendoes not have traversal access to:
has access towhereis the parent ofandappears among the items in the iterator returned by eitheror.
has access to is a descendant ofand I appears in the serialized output of an export of the subgraphrooted at.
A client can testwhether a retrieved iterator will be empty using the following:
Iterators over childnodes and properties can be acquired using the following methods:
These methods returnall the child nodes or properties (as the case may be) of the nodethat are visible to the current session.
These methods returnall the child nodes or properties (as the case may be) of the nodethat are both visible to the current session and that match thepassedorarray.
Thepassed inandis a string matched against the qualified names (not the paths) ofthe immediate child items of this node. We call theparameter thepattern and the qualified names against whichit is tested thetarget strings.
Apatternconsists of one or moreglobs. In cases of two or moreglobs, they are delimited by the pipe character (,U+0076).
A pattern matchesa target string if and only if at least one of its globs matchesthat target string.
Aglobmatches a target string if and only if it matches character forcharacter, except for any asterisk characters (*, U+002A) in theglob, which match any substring (including the empty string) in thetarget string.
The characters “”and “”are excluded from qualified JCR names (see §3.2.5.2QualifiedForm), so their use as metacharacters in the pattern will notlead to a conflict.
For backwardscompatibility with JCR 1.0, leading and trailing whitespace around aglob is ignored but whitespace within a glob forms part of thepattern to be matched.
The alternatesignatures
Behave identically tothose that takeexcept that the parameter passed is an array of globs, as definedabove, which are “ORed” together, removing the need for the “”metacharacter to indicate disjunction. The items returned,therefore, are those that matchat least one of the globs inthe array. Unlike thecase, leading and trailing whitespace in globsis not ignoredby these methods.
Dependingon the implementation, the order of child nodes within the returnediterator may be more or less stable across different retrievals. Arepository that supportspreservationof child node ordering will maintain aconstant total order across separate retrievals. A repository thatsupports orderable child nodes necessarily also supports orderpreservation (§23Orderable ChildNodes).
Exporting a subgraphwithin a workspace can be done with
or
.
See §7Export.
A sessionhas query access toif and only if for at least oneobject,whereis created through theof theobject bound to,is returned in thefor(see §6Query).
For any given sessionand item:
Ifhas traversal access tothenmust have direct access to.
Ifhas query accessthenhas direct access to.
However, note that,
If S has direct access tothenmay or may not have traversal access to.
If S has direct access tothenmay or may not have query access to.
If S has direct access tothenmay or may not have direct access to any parent of.
If a repositoryrestricts the read access of a session, then the nodes andproperties to which that session does not have read access mustappear not to exist. For example, the iterator returned onwill not include subnodes ofto which the session in question does not have read access. In otherwords, lack of read access to an item blocks access to bothinformation about the content of that item and information about theexistence of that item.
In repositories thatsupportsame-name siblings, denial of access to a subset ofnodes within a same-name sibling seriesmay result in gaps inthe index numbering of that series, thus revealing information aboutthe existence of the inaccessible nodes.
Theinterface includes a number of methods that provide informationabout an item.
This method providesaccess to the current.
These methods provideinformation about the location of anwithin the workspace hierarchy:
returns the name ofthe
returns the absolutepath of the.
returns the ancestorof thethat is at the specified depth below the root node
returns the parent ofthe
returns the depthbelow the root node of the.
returnsif theis aandif it is a.
This method is used todetermine the repository-level semantic identity of twoobjects.
returns true if thisobject represents the same actual repository item as the object.This method does not compare the states of the two items. Forexample, if twoobjects representing the same actual repository item have beenretrieved through two different sessions and one has been modified,then this method will still returnfor these two objects. Note that if twoobjects representing the same repository item are retrieved throughthe samethey will always reflect the same state so comparing state is not anissue (see section §10.11.7Reflecting Item State).
This method implementsthevisitor design pattern.
Theinterface defines the methods
and
which the user canimplement.
The method
returns the identifierof a node.
The method
returns the index of anode among its same-name siblings (see §22Same-Name Siblings).Same-name sibling indexes begin with,so this method will returnfor a node without any same-name siblings.
Methods that return aset oforobjects do so using aor,subclasses of.
JCR also specifies thefollowing subclasses of:,,,,,and.
The lifespan of aninstance ofor any of its subclasses is implementation-specific. For example, insome implementations a(see §10.11.1Refresh) might invalidate a previouslyacquiredwhile in others it might not.
If a session has readaccess to a single–value property then it can read the value ofthat property. If a session has read access to a multi-valueproperty then it can readall the values of that property.
The generic valuegetter for single value properties is
.
For multi-valueproperties it is
.
Single and multi-valueproperties can be distinguished by calling
.
returns one of theconstants of(see §3.6.1Property Types) indicating the property type ofthe.
The length of a valuein a single-value property, as defined in §3.6.7Length of aValue, is returned by
Similarly, the method
is used to get anarray of the lengths of all the values of a multi-value property.
Each property type hasa standardread method. This is the method that returns the Java object orprimitive type that corresponds naturally to the JCR property type.Amay also be readable by a non-standard read method, depending onwhether it is convertible to that method's return type according tothe rules described in §3.6.4Property Type Conversion. Thefollowing sections set out the standard read method for each type.
returns a JCRas a.
returns a JCRas a(see §5.10.5Binary Object).
returns a JCRas a Java.
returns a JCRas a Java.
returns a JCRas a.
returns a JCRas a.
returns a JCRas a Java.
returns a JCRas a.Thereturned must be the JCR name inqualified form (see §3.2.5.2Qualified Form).
returns a JCRas a.Thereturned must be the JCR path instandard form (see §3.4.3.1Standard Form). However, if the original value wasnon-normalized it must be returned non-normalized, preservingthe path structure as it was originally set, including any redundantpath segments that may exist (see §3.4.5Normalized Paths).
returns a JCRoras a.The value of aoris a node referenceable identifier (see §3.8.3ReferenceableIdentifiers). Since an identifier is simply a,the returned value can be used directly to find the referenced node(see §5.1.4Getting a Node by Identifier).
Theobject returned byprovides the following methods:
,
which returns anrepresentation of the value. Each call to this method returns a newstream and the API consumer is responsible for callingon the returned stream.
,
which reads successivebytes starting from the specified position in the value into thepassed byte array until either the byte array is full or the end ofthe value is encountered.
,
which returns the sizeof the value in bytes.
When an application isfinished with a Binary object it should call
on that object. Thiswill releases all resources associated with the object and informthe repository that these resources may now be reclaimed.
Theinterface and its related methods in,andreplace the deprecatedandmethods from JCR 1.0. Though these methods have been deprecated, forreasons of backward compatibility their behavior must conform to thefollowing rules:
Once aobject has been read once using,all subsequent calls towill return the same stream object. This may mean, for example,that the stream returned is fully or partially consumed. In orderto get a fresh stream theobject must be reacquired viaor.
Unlike in JCR1.0, calling amethod other than getStream before callingon the sameobject will never cause an.
,andproperties function as pointers to other items in the workspace. Acan point to a node or a property while aorcan point only to a referenceable node.properties enforcereferential integrity whileproperties andproperties do not. These properties can be dereferenced eithermanually or though convenience methods.
Tomanually dereference a pointer property it is first read as astring, for example with
.
In the case ofandproperties the resulting string is passed to
.
In the case ofproperties the string is passed to
or
as appropriate to thetarget item. Whether theis aorcan be determined withor(see §5.1.2Testing for Existence by Absolute Path).
Theinterface provides convenience methods for dereferencing pointerproperties:
returns the nodepointed to by a single-value property. This method works withandproperties and withproperties that point to nodes.
returns the propertypointed to by a single-valueproperty.
For multi-valuepointer properties the array of values must be retrieved withand each individually manually dereferenced.
Given a referenceablenode,
returns all accessibleproperties in the workspace that point to the node.
returns all accessibleproperties in the workspace that pointto the node.
Note that accesscontrol and other implementation-specific limitations my mean thatsome references within the workspace are not accessible.
properties are not automatically backtrackable.
Theproperty interface provides convenience methods for readingsingle-value properties which function identically to theircounterparts.
Amulti-value property can be accessed with
.
The classdefines integer constants for the property types as well as stringconstants for their standardized type names (which are used inserialization) and two methods for converting back and forth betweenname and integer value (see Javadoc).
The method
is used to change thelocal namespace mappings of the current.When called, all local mappings that include either the specifiedor the specifiedare removed and the new mapping is added. However, the method willthrow an exception if
the specifiedprefix begins with the characters “”(in any combination of case) or,
the specifiedprefix is the empty string or,
the specifiednamespace URI is the empty string.
The following methodsare also related to the local namespace mapping: