A repository maysupport the bulkimport of content from XML. Two XML mappingsare defined:document view andsystem view. The formeris used primarily for the import of arbitrary XML into therepository while the latter is a full serialization of repositorycontent (see §7Export). A repository that supports importmust support both formats.
Whether animplementation supports import can be determined by querying therepository descriptor table with
.
A return value ofindicates support (see §24.2Repository Descriptors).
Thedocument viewXML mapping (see §7.3Document View) allows the import ofarbitrary XML into the repository. On import, the repository firstchecks if the incoming XML appears to be a system view document. Ifit does not, then it is assumed to be in document view form, and thefollowing occurs:
For each XMLnamespace declaration with prefixand URI:
If the namespaceregistry already contains a mapping of some prefixto(wheremay or may not be equal to)then the namespace registry is left unchanged.
If the namespaceregistry does not contain a mapping tothen such a mapping is added to the registry. The prefix assignedmay beP, ifP is not already used in the registry,otherwise the repository must generate and assign a new,previously unused, prefix.
Each XML elementbecomes a JCR node of the same name,.
The node type ofthe JCR nodeis determined by the implementation in accordance with its policyon respecting property semantics (see §11.3Respecting PropertySemantics and §11.4Determining Node Types).
Each child XMLelementof XML elementbecomes a JCR child nodeof node.
Each XMLattributewithin an XML elementbecomes a propertyof JCR node.The value of each XML attributebecomes the value of the corresponding property.
The type of eachimported property is determined by the implementation in accordancewith its policy on respecting property semantics (see §11.3Respecting Property Semantics and §11.4Determining NodeTypes).
Escape sequencesrepresenting non-XML-valid characters in element names andwhitespace in attribute values may be encountered (for example, ifthe incoming XML stream is the product of an earlier document viewexport). In such cases, whether the escape sequences are decoded isleft up to the implementation. Note that the predefined entityreferences,,,and,as well as all other entity and character references, must bedecoded in any case, in accordance with the XML specification.
An implementationthat respects node type information may be able to determinewhether a particular attribute is intended to be a single ormulti-value property, and treat any spaces embedded in the valueaccordingly (either as delimiters or as literal spaces).Implementations are also free to rely on information external tothis specification (such as any schema associated by the incomingXML) to help determine the intended interpretation of whitespacewithin a particular incoming attribute value.
Text within anXML elementbecomes aproperty calledof a JCR node called,which itself becomes a JCR child node of the node. The value ofwill be the character data passed to.
If import is donethrough thereturned by,data passed tois ignored.
If import is donethrough,pure whitespace between elements (that is, a string containing nonon-whitespace characters) is ignored. However, whitespace leading,trailing and between non-whitespace characters is included in thetext that is stored in.
Not all informationwithin the infoset of an XML document is maintained on import todocument view. Information lost will include processinginstructions, the distinction between text and CDATA and namespacescoping at the sub-document level. As a result, perfectroundtripping of a full XML infoset is not possible through documentview.
On document viewimport, the repository will automatically add repository metadata inthe form of JCR properties (at least,for example), if these are not already present in the incoming XML.When re-exported using document view, the resulting XML will containthese properties in the form of XML attributes. As a result, theapplication must take care of stripping out unwanted repositorymetadata.
Given a system viewXML document the subgraph constructed upon import is determined byreversing the mapping discussed in §7.2System View. Thoughthe mapping is largely straightforward some special considerationsare discussed in §11.3Respecting Property Semantics and§11.9Importing jcr:root.
During either systemor document view import, XML elements (in system view) or XMLattributes (in document view) may be encountered that correspond toJCR properties with repository-level semantics such as the-prefixedproperties of such node types as,or,among others.
When an element orattribute representing such a property is encountered, animplementation may eitherskip it orrespect it.
A repository thatrespects a particular element or attribute must import it and alterthe internal state of the repository in accordance with thesemantics of the property given the configuration of thatrepository instance. For example, a repository that respectswill attempt to create a node of the indicated primary node type.If that node type is not supported, the repository will throw anexception.
A repository thatskips an element or attribute must not import it all.It mustnot import it but then ignore the semantics of the resultingproperty.
Theimplementation-specific policy regarding what to skip and what torespect must be internally consistent. For example, it makes nosense to skip(thus missing the presence of,for example) and yet respectand.
If an implementationchooses to skip,the node type of the imported node is determined by theimplementation (see §11.5Determining Node Types).
In cases of XML import where primarynode type information is unavailable, either because it is skippedor because it is not available (as is the case on document viewimport of arbitrary XML), the implementation must determine anappropriate node type to assign to each newly created node. How thisis done is implementation-dependent.
On import of arbitraryXML using document view, the implementation must determine asuitable property type for each incoming property. Determination ofthe property type must be done as follows:
If the property type isdeterminable from the node type assigned to its node (regardless ofhow this node type is itself determined; see §11.5DeterminingNode Types) then that property type is used.
If the property type is notdeterminable from the node type assigned to its node then thedetermination of the property is left up to the implementation. Forexample, an implementation may useproperties exclusively, or attempt to“guess” the type according to an analysis of the content.
Theandinterfaces provide the following event-based import methods:
and
These methods returnanwithout altering either theor.The actual changes to the repository are made through the methods ofthe.Invalid XML data will cause theto throw a.
If the incoming XML isasystem view XML document then it is interpreted as such,otherwise it is imported asdocument view.
The incoming XML isimported into a subgraph of items immediately below the node at.
Aacquired through themethod dispatches changes immediately. Node type constraints areenforced by theby throwing aduring deserialization. However, which node type constraints areenforced depends upon whether node type information in the importeddata is respected, and this is an implementation-specific issue (see§11.3Respecting Property Semantics).
Aacquired through thewill build the graph of new items in the transient session store.The changes are then dispatched on.
Different node typeconstraints may be enforced at different times. Those that would beimmediately enforced on a core write method (see §10.2CoreWrite Methods) of that particular implementation will cause thereturnedto throw an immediate.All other node type constraints are enforced as they would be ifmade through the core write methods. However, which node typeconstraints are enforced also depends upon whether node typeinformation in the imported data is respected, which is animplementation-specific issue (see §11.3Respecting PropertySemantics).
Theandinterfaces provide the following stream-based import methods:
and
These methods importthe XML document in the input stream and add the resulting itemsubgraph as a child of the node at.If the incoming XML is asystem view XML document then it isinterpreted as such, otherwise it is imported asdocument view.
Onchanges are dispatched immediately. Node type constraints areenforced by throwing a.However, which node type constraints are enforced depends uponwhether node type information in the imported data is respected,which is an implementation-specific issue (see §11.3RespectingProperty Semantics).
Onchanges remain pending until dispatched on.Node type constraints that would be immediately enforced on a corewrite method (see §10.2Core Write Methods) of thatparticular implementation will cause an immediateduring import. All other node type constraints are enforced as theywould be if made through the core write methods. However, which nodetype constraints are enforced depends upon whether node typeinformation in the imported data is respected, and this is animplementation-specific issue (see §11.3Respecting PropertySemantics).
Theflag governs how the identifiers of imported nodes are handled.There are four options, defined as constants in the interface:
:Incoming nodes are assigned newly created identifiers upon additionto the workspace. As a result, identifier collisions never occur.
:If an incoming non-shareable node has the same identifier as a nodealready existing in the workspace then the already existing node(and its subgraph) is removed from wherever it may be in theworkspace before the incoming node is added. Note that this canresult in nodes “disappearing” from locations in the workspacethat are remote from the location to which the incoming subgraph isbeing written. In the case of shareable node, however, the behaviordiffers (see §14.1.2Shared Node Creation on Import).
:If an incoming non-shareable node has the same identifier as a nodealready existing in the workspace, then the already existing node isreplaced by the incoming node in the same position as the existingnode. Note that this may result in the incoming subgraph beingdisaggregated and “spread around” to different locations in theworkspace. In the most extreme case this behavior may result in nonode at all being added as child of.This will occur if the topmost element of the incoming XML has thesame identifier as an existing node elsewhere in the workspace. Inthe case of shareable node, however, the behavior differs (see§14.1.2Shared Node Creation on Import).
:If an incoming non-shareable node has the same identifier as a nodealready existing in the workspace, then either ais thrown by the(in the case of event-based import) or anis thrown by themethod (in the case of stream-based import). In the case ofshareable nodes, the behavior differs (see §14.1.2Shared NodeCreation on Import).
The term “UUID”occurs in the names of certain properties, classes and methods inJCR 1.0. This usage is maintained in JCR 2.0 to preservecompatibility with JCR 1.0. However, in the context of JCR 2.0 thesenames should be understood to apply to identifiersin generaland not just identifiers that use of the UUID syntax, or thatpossess global uniqueness.
If the root node of aworkspace is exported it will be rendered in XML (in either view)under the name.In addition, if the root node is referenceable this will be recordedin the serialization of theproperty.
If this XML documentis imported back into the workspace a number of different resultsmay occur, depending on the methods and settings used to perform theimport. The following summarizes the possible results of usingvariousvalues (in either using eitheror)when a node with the same identifier as the existing root node isencountered on import (the constants below are defined in theinterface).
:The XML element representingis rendered as a normal node at the position specified (with thename).It gets a new identifier, so there is no effect on the existing rootnode of the workspace.
:If deserialization is done through a(acquired by)awill be thrown. Similarly, if deserialization is done throughawill be thrown. Note that this is simply a special case of thegeneral rule that under thissetting, an exception will be thrown on any attempt to import a nodewith the same identifier as the node ator any of its ancestors(which, of course, includes the rootnode).
:This setting is equivalent to importing into theand then calling sincealways operates according to identifier. In both cases the result isthat the root node of the workspace will be replaced along with itssubgraph (i.e., the whole workspace), just as if the root node hadbeen altered through the normal-makechange-cycle.
:Under this setting awill throw aand themethod will throw.
Note that animplementation is always free to prevent the replacement of a rootnode (or indeed any node) either through access control restrictionsor other implementation-specific restrictions.