To begin using arepository, an application must acquire aobject.
Access to aobject may be provided through a number of standard Java naming anddiscovery mechanisms, butmust at the minimum be providedthrough an implementation of theinterface.
Any implementation ofmust have a zero-argument public constructor. Repository factoriesmay be installed in an instance of the Java platform as extensions,that is, jar files placed into any of the usual extensiondirectories. Factories may also be made available by adding them tothe applet or application class path or by some otherplatform-specific means.
A repository factoryimplementation should support the Java Standard Edition ServiceProvider mechanism9,that is, an implementation should include the file.This file contains the fully qualified name of the class thatimplements.
Once theis acquired, theobject itself is acquired through
which attempts toretrieve aobject using the given parameters.
Parameters are passedin aofkey/value pairs. The keys are not specified by JCR and areimplementation specific. However, vendors should use keys that arenamespace qualified in the Java package style to distinguish theirkey names. Alternatively, a client may request a default repositoryinstance by passing a.
The implementationmust returnif a default repository instance is requested and the factory isnot able to identify such a repository or if parameters are passedand the factory does not understand them. See the associated Javadocfor example connection code.
An application mayexplicitly specify the repository factory implementation. Forexample:
Some implementationsmay allow acquisition of athrough thein Java SE 6. For example:
Note that in Java SEprior to version 6, one may use the classto look up the availableimplementations.
A repositoryimplementation must provide thread-safe implementations of all themethods of theandinterfaces. A repository implementation is not required to providethread-safe implementations of any other interface. As aconsequence, an application which concurrently or sequentiallyoperates against objects having affinity to a particularthrough more than one thread must provide synchronization sufficientto ensure no more than one thread concurrently operates against thatand changes made by one thread are visible to other threads.
Interaction with therepository begins with the user acquiring athrough a call to.In the most general case, the client supplies aobject and a workspace name:
.
Other signatures ofare also provided (see §4.2.4External Authentication).
Theinterface is an empty marker for the object that carries theinformation necessary to authenticate and authorize the user. Arepository may use the suppliedimplementation or its own implementation.
is used to acquire an anonymous session.
Thepassed onidentifies one of the persistent workspaces of the repository. Morethan onecan be simultaneously bound to the same persistent workspace.
By providing asignature ofthat does not require,the content repository allows for authorization and authenticationto be handled by JAAS (or another external mechanism) if theimplementer so chooses.
To use such anexternal mechanism to create sessions with end-user identity,invocations of themethod that do not specify(i.e., either ais passed or a signature without theparameter is used) should obtain the identity of thealready-authenticated user through that external mechanism.
A client may also opena newfrom within an existing one using
.
The returnedis bound to the same workspace as the current,though it may (and typically will) have a different authorization.The implementation is free to take both the suppliedand the authorization of the currentinto account in determining the authorization of the returned.
Theobject is granted a set of permissions toward the specifiedpersistent workspace. These are determined by the'scredentials combined with any access control restrictions, eitherJCR-defined or implementation-specific, which may apply (see §9.1Permissions).
Eachhas a user ID, accessed through
.
How the user ID is setis up to the implementation. It may be passed in as part of theor it may be acquired in some other way. This method is free toreturn an “anonymous user ID” or.
Amay have arbitrary, implementation-specific named attributes boundto its.The method
returns the set ofattribute names, and the method
returns the value of anamed attribute.
Theobject through which awas acquired is retrieved with
.
The method
is used to checkwhether aobject represents a live, logged-in session.
Ais closed using
.
Though more than onecan be bound to the samepersistent workspace, eachobject has a single distinct correspondingobject thatrepresents the actual persistent workspace towhich theis bound. Aobject can be thought of as aview on to the persistentworkspace as seen through the permissions granted to itscorresponding(see §10Writing).
.
returns the Workspaceobject representing the actual persistent workspace to which ais bound.
Despite theirone-to-one relationship,andare defined as distinct interfaces in order to separate two types ofwrite behavior:transient vs.immediately persistent,though this distinction is only strictly relevant in writablerepositories.
returns theobject to which aobject is bound.
returns the name ofthe persistent workspace represented by aobject.
returns an arrayholding the names of all persistent workspaces accessible from aobject. Accessibility is determined by the permissions granted totheto which theobject is bound. In order to access one of the listed workspaces,the user performs another,specifying the name of the desired workspace, and receives a newobject.