A repository maysupportobservation, which enables an application to receivenotification of persistent changes to a workspace. JCR defines ageneral event model and specific APIs for asynchronous and journaledobservation. A repository may support asynchronous observation,journaled observation or both.
Whether animplementation supports asynchronous or journaled observation can bedetermined by querying the repository descriptor table with the keys
or
.
A return value ofindicates support (see §24.2Repository Descriptors).
A persisted change toa workspace is represented by a set of one or moreevents.Each event reports a single simple change to the structure of thepersistent workspace in terms of an item added, changed, moved orremoved. The six standard event types are:
,
,
,
,
and
.
A seventh event type,
,
may also appear incertain circumstances (see §12.7.3Event Bundling in JournaledObservation).
The scope of eventreporting is implementation-dependent. An implementation should makeabest-effort attempt to report all events, but may excludeevents if reporting them would be impractical given implementationor resource limitations. For example, on an import, move or removeof a subgraph containing a large number of items, an implementationmay choose to report only events associated with the root node ofthe affected graph and not those for every subitem in the structure.
Some implementationsmay expose capabilities through the JCR API while also beingwritable through a mechanism external to JCR. Whether events aregenerated for changes made through such external means is left up tothe implementation.
Each event generatedby the repository is represented by anobject.
The type of anis retrieved through
which returns one of theconstants found in theinterface:,,,,,or.
Eachis associated with a path, an identifier and an information map, theinterpretation of which depend upon the event type.
The event path is retrieved through
,
the identifier through
and the informationmap through
If the event is aorthen,
returns the absolute path of the node that was added or removed.
returns the identifier of the node that was added or removed.
returns an emptyobject.
If the event isthen,
returns the absolute path of thedestination of the move.
returns the identifier of the node that was moved.
returns acontaining parameter information from the method that caused theevent (see §12.4.3Event Information on Move and Order).
If the event is a,orthen,
returns the absolute path of the property that was added, changedor removed.
returns the identifier of the parent node of the property that wasadded, changed or removed.
returns an emptyobject.
If the event is a(see §12.6.3Event Bundling in Journaled Observation) thenandreturnandreturns an empty.
On aevent, theobject returned bycontains parameter information from the method that caused theevent. There are three JCR methods that cause this event type:,and.
If the method thatcaused theevent was aorthen the returnedhas keysandwith values corresponding to the parameters passed to themethod, as specified in the Javadoc.
If the method thatcaused theevent was athen the returnedhas keysandwith values corresponding to the parameters passed to themethod, as specified in the Javadoc.
In a repository thatreports events caused by mechanisms external to JCR (see §12.2.1Externally Caused Events), the keys and values found in theinformation map returned on aare implementation-dependent.
Analso records the identity of thethat caused it.
returns the user ID of the,which is the same value that is returned by(see §4.4.1User).
Anmay also contain arbitrary string data specific to the session thatcaused the event. A session may set its current user data using
.
Typically a sessionwill set this value in order to provide information about itscurrent state or activity. Any events produced by the session whileits user data is set to particular value will carry that value withthem. A process responding to these events will then be able toaccess this information through
and use the retrieved data to provideadditional context for the event, beyond that provided by theidentify of the causing session alone.
An eventalso records the time of the change that caused it. This acquiredthrough
The date is represented as amillisecond value that is an offset from the epoch January 1, 197000:00:00.000 GMT (Gregorian). The granularity of the returned valueis implementation-dependent.
A repository thatsupports observationmay support event bundling underasynchronous observation, journaled observation, or both.
In such a repository,events are produced in bundles where each corresponds to a singleatomic change to a persistent workspace and contains only eventscaused by that change (see §10.1Types of Write Methods).
For example, given asession with a set of pending node and property additions, onpersist, aoris produced, as appropriate, for each new item. This set of eventsis the event bundle associated with that particular persistoperation. By grouping events together in this manner, additionalcontextual information is provided, simplifying the interpretationof the event stream.
In both asynchronousand journaled observation the order of events within a bundle andthe order of event bundles is not guaranteed to correspond to theorder of the operations that produced them.
Asynchronousobservation enables an application to respond to changes made in aworkspace as they occur.
An applicationconnects with the asynchronous observation mechanism by registeringan event listener with the workspace. Listeners applyperworkspace, not repository-wide; they only receive events for theworkspace in which they are registered. An event listener is anapplication-specific class implementing theinterface that responds to the stream of events to which it has beensubscribed.
This observationmechanism isasynchronous in that the operation that causesan event to be dispatched does not wait for a response to the eventfrom the listener; execution continues normally on the thread thatperformed the operation.
Registration of eventlisteners is done through theobject acquired from thethrough
.
An event listener isadded to a workspace with
Theobject passed is provided by the application. As defined by theinterface, this class must provide an implementation of themethod:
When an event occursthat falls within the scope of the listener (see 12.6.3EventFiltering), the repository calls themethod invoking the application-specific logic that processes theevent.
Which events alistener receives are determined as follows.
An event listener willonly receive events for which its(theassociated with thethrough which the listener was added) has sufficient accessprivileges.
An event listener willonly receive events of the types specified by theparameter of themethod. Theparameter is ancomposed of the bitwiseof the desired event type constants.
If theparameter is,then events generated by thethrough which the listener was registered are ignored.
Node characteristicrestrictions on an event are stated in terms of theassociatedparent node of the event. The associated parent node of an eventis theparent node of the item at (or formerly at) the pathreturned by.
Ifis,only events whose associated parent node is atwill be received.
Ifis,only events whose associated parent node is at or belowwill be received.
It is permissible toregister a listener for a path where no node currently exists.
Only events whoseassociated parent node has one of the identifiers in thearray will be received. If this parameter isthen no identifier-related restriction is placed on events received.Note that specifying an empty array instead ofresults in no nodes being listened to. Theis used for backwards compatibility with JCR 1.0.
Only events whoseassociated parent node is of one of the node types in thearray will be received. If this parameter isthen no node type-related restriction is placed on events received.Note that specifying an empty array instead ofresults in no nodes being listened to.
The filters of analready-registeredcan be changed at runtime by re-registering the sameJava object with a new set of filter arguments. The implementationmust ensure that no events are lost during the changeover.
In addition to thefilters placed on a listener though themethod, the scope of observation support, in terms of whichsubgraphs are observable, may also be subject toimplementation-specific restrictions. For example, in somerepositories observation of changes in thesubgraph may not be supported (see 3.11System Node).
In asynchronousobservation theholds an event bundle or a single event, if bundles are notsupported.inherits the methods ofand adds an-specificmethod:
(see §5.9Iterators)
Methods that return aset ofobjects (such as)do so using an.Theclass inherits the methods ofand adds an-specificmethod:
(see §5.9Iterators)
Journaled observationallows an application to periodically connect to the repository andreceive a report of changes that have occurred since some specifiedpoint in the past (for example, since the last connection). Whethera repository records a per-workspace event journal is up to theimplementation's configuration.
Theof a workspace instance is acquired by calling either
or
.
Events reported bythisinstance will be filtered according to the current session's accessrights, any additional restrictions specified throughimplementation-specific configuration and, in the case of the secondsignature, by the parameters of the method. These parameters areinterpreted in the same way as in the method.
Anis an extension ofthat provides the additional method.
An implementation isfree to limit the scope of journaling both in terms of coverage(that is, which parts of a workspace may be observed and whichevents are reported) and in terms of time and storage space. Forexample, a repository can limit the size of a journal log bystopping recording after it has reached a certain size, or byrecording only the tail of the log (deleting the earliest event whena new one arrives). Any such mechanisms are assumed to be within thescope of implementation configuration.
In journaledobservation dispatching is done by the implementation writing to theevent journal.
If event bundling issupported aevent is dispatched when a persistent change is made to workspacebracketing the set of events associated with that change. Thisexposes event bundle boundaries in the event journal.
Note that aevent will never appear within ansince, in asynchronous observation, the iterator itself serves todefine the event bundle.
In repositories thatdo not support event bundling,events do not appear in the event journal.
Whether events aregenerated for each node and property addition that occurs whencontent is imported into a workspace (see §11Import) isleft up to the implementation.
The methoddoes not specify aclause. This does not prevent a listener from throwing a,although any listener that does should be considered to be in error.