A JCR repository mustsupport export of content to two XML formats:system view anddocument view.
Export operates on asubgraph of a workspace. Given a repositoryR with workspaceW and a nodeN withinW the following sectionsdescribe the algorithm for producing the system view and documentview serializations of the subgraph rooted atN.
In a repository thatsupportsshareable nodes the set of nodes belowN maynot be a tree, it may, more generally, be a subgraph with uniquesourceN (see §3.9Shareable Nodes Model).
The exported systemview XML document is constructed as follows:
For everynamespace used within the subgraph rooted atN, thecorresponding JCR namespace mapping in the current sessionisincluded as an XML namespace declaration such that any use of anamespace prefix is within the scope of the appropriate namespacedeclaration.
Other JCRnamespace mappings in the current sessionmay be included asXML namespace declarations in the exported document.
The JCR namespacemapping of the prefixmay be excluded from the namespace declarations in theexported document.
A namespacedeclaration for the URI,is included such that any use of the corresponding namespace prefixis within the scope of the declaration. In this section the prefixis assumed, making the declaration.
Each JCR nodebecomes an XML element.
Each JCR propertybecomes an XML element.
The name of eachJCR node or property becomes the value of theattribute of the correspondingorelement.
If the root nodeof a workspace is included in the serialized subgraph, it receivesthe name.
The property typeof each content repository property is recorded in theattribute of the correspondingelement, using the standard string forms for property type names asreturned by the method.
The value of each JCR property is Base6412encoded and the resulting string is included as XML text within anelement within theelement.
The value of eachnon-JCR property is converted to string form according to the standardconversion (see §3.6.4Property Type Conversion) and theresulting string is included as XML text within anelement within theelement.
Entityreferences are used to escape characters which cannot be includedas literals within XML text (see §7.5Escaping of Values).
If, afterconversion to string and entity escaping is performed, the stringform of a value still contains characters which cannot appear inan XML document (neither as literals nor as character references13)then:
The string formis further encoded using Base64 encoding.
The attributeis added to theelement.
The namespacemappings forandare added to the exported XML document so that theattribute is within their scope. The namespace declarationsrequired areand.Note that the prefixes representing these two namespaces need notbeliterally “”and “”.Any two prefixes are permitted as long as the correspondingnamespace declarations are changed accordingly.
A multi-valueproperty is converted to anelement containing multipleelements. The order of theelements reflects the order of the value array returned by.If a property is multi-valued but happens to have only one value,then the attributemust be added to the correspondingelement. If the property is multi-valued and has more than onevalue then theattributemay be added.
The hierarchy ofthe content repository nodes and properties is reflected in thehierarchy of the corresponding XML elements.
Within anelement allsubelements must occur before the firstsubelement.
The firstelement in anelement must be(see §3.7.10Base Primary Node Type).
If a node has aproperty, then the secondelement in theelement must be(see §3.7.10Base Primary Node Type).
In the case ofreferenceable nodes, the thirdelement in theelement must be(see §3.8.1.1mix:referenceable).
The order of thesubelements of a parentmust reflect the order in which the corresponding child nodes arereturned by.
Shared nodes areexported as described in §14.7Export.
A writable repositorymay support import using system view (see §11Import).
The document viewprovides a more human-readable serialization than system view.Unlike system view, document view is lossy. It does not preserve allinformation in the subgraph.
For everynamespace used within the subgraph rooted atN, thecorresponding JCR namespace mapping in the current sessionisincluded in the exported document such that any use of thenamespace prefix in the exported document is within the scope ofthe appropriate namespace declaration.
Other JCRnamespace mappings in the current sessionmay be included asXML namespace declarations in the exported document.
The JCR namespacemapping of the prefixmay be excluded from the namespace declarations in theexported document.
Each JCR nodebecomes an XML element of the same name,.
If the root nodeof a workspace is included in the serialized subgraph, it becomesan XML elements with the name.
Each child nodeofbecomes a subelementof XML element.
The order of thesubelements of elementmust reflect the order in which the corresponding child nodes arereturned by.
Each propertyof nodebecomes an XML attributeof XML element.
Ifis aproperty its value is Base64 encoded. The resulting string becomesthe value of the XML attribute.
Ifis a non-property its value is converted to string form according to thestandard conversion (see §3.6.4Property Type Conversion).Entity references are used to escape characters which cannot beincluded as literals within attribute values (see §7.5Escapingof Values).
A writable repositorymaysupport document view import (see §11.1ImportingArbitrary XML).
The following sectionsdescribe the exceptions to the above general rules.
In a repository thatsupports it, on document view import XML text is converted to thespecial node/property structure(see §11.1Importing Document View). When this structure isexported back to XML the process is reversed.
If a child node ofcalledis encountered and thatnode has one and only one child item and that item is asingle-valued property called,then thenode is not converted into an XML element. Instead, the value of theproperty becomes text within the body of the XML element.Entity references are used to escape characters which cannot beincluded as literals within XML text (see §7.5Escaping ofValues) however, escaping of whitespace is not performed (see§7.3.3Multi-Value Properties). Two or morenodes adjacent within the ordering of a child node set will have thevalues of their respectiveconcatenated into a single resulting XML text node.
If the name of acontent repository itemis not a valid XML element or attribute name (as the case may be)then on export the repository may either ignore the item in questionor employ the escaping scheme described in §7.4Escaping ofNames. Which approach is taken is implementation-dependent.
If a multi-valuepropertyis encountered on export, the repository may either ignore themulti-value property or serialize it as an attribute whose value isan XML Schema list type14(i.e., a whitespace-delimited list of strings). If the latterapproach is taken then:
Each value in theproperty is converted to a string according to standard conversion,see §3.6.4Property Type Conversion. If the multi-valueproperty contains no values, then it is serialized as an emptystring.
All literalwhitespace within each string is escaped, as well as any charactersthat should not be included as literals in any case, see §7.5Escaping of Values.
The finalattribute value is constructed by concatenating the resultingstrings, with the addition of the space delimiter, into a singlestring. The order of concatenation must be the same as the order inwhich the values appear in thearray returned by.
Furthermore, ifmulti-value property serialization is supported, then a mechanismmust be adopted whereby upon re-import the distinction betweenmulti- and single- value properties is not lost, see §7.5Escapingof Values.
Note that thisescaping of space literals does not apply to the value ofwhen it is converted to XML text. In that case only the standardXML entity escaping is required, regardless of whether multi-valueproperty serialization is supported (see §7.3.1XML Textand §7.5Escaping of Values).
If the string form ofthe value of propertycontains characters which cannot appear in XML documents at all(neither as literals nor as character references15)then the attributeis simply excluded from the document view serialization and does notappear at all.
Though a JCR prefix isalways a valid XML prefix, the JCR local name may not be a valid XMLname. Consequently, for document view serialization, each JCR nameis converted to a valid XML name (as defined by XML 1.0) bytranslating invalid characters into escaped numeric entityencodings16.
The escape characteris the underscore (“_”). Any invalid character is escaped as,whereis the four-digit hexadecimal UTF-16 code for the character. Whenproducing escape sequences the implementation should use lowercaseletters for the hex digits-.When unescaping, however, both upper and lowercase alphabetichexadecimal characters must be recognized.
Escaping andunescaping is done by parsing the name from left to right.
The underscorecharacter (“_”), when appearing as literal, is itself escaped ifit is followed bywhereis one of the following characters:.
For example,
“” is encoded as“”.
“”is not encoded.
“”is encoded as
“”is encoded as “”.
“” is encoded as“”.
When a non-value is serialized during either system view or document viewexport, it is first converted to string form using standard valueconversion, see §3.6.4Property Type Conversion.values are encoded using Base64. The resulting string then undergoesany further changes required by the standard XML escaping rules17.
In document viewserialization, if the property being serialized is multi-valued (orif the implementation chooses to encode spaces in single-valueproperties as well, see below) then the value or values must befurther encoded by escaping any occurrence of one of the fourwhitespace characters: space, tab, carriage return and line feed.The scheme used to encode these characters is the same as thatdescribed in §7.4Escaping of Names. Note that in thisrestricted context, applying those escaping rules amounts to thefollowing: a space becomes,a tab becomes,a carriage return becomes,a line feed becomesand any underscore ()that occurs as the first character of a sequence that could bemisinterpreted as an escape sequence becomes.
Finally, in documentview export, the value of the attribute representing a multi-valueproperty is constructed by concatenating the results of the aboveescaping into a space-delimited list.
In document viewexport (though not in system view), if multi-value propertyserialization is supported (see §7.3.3Multi-Value Properties)then a mechanism must be adopted whereby upon re-import thedistinction between multi- and single- value properties is not lost.One option is that escaping of space literals must be applied to thevalue of all single-value properties as well. Another option is thatwhen an XML document is imported in document view, each attribute isassumed to be a single-value property unless out-of-band informationdefines it to be multi-valued (for example, if the applicable nodetype defines the property as multi-valued or the XML document isassociated with a schema definition that indicates that theattribute is a list value). The approach taken isimplementation-specific.
Note that the value ofaproperty used to represent XML text (see §7.3.1XML Text) isnot space-escaped, regardless of the prevailing multi-value propertyserialization policy.
Exported XML can beoutput either as a stream or as a series of SAX events. The exportmethods are found in theobject.
The methods
and
serialize the itemsubgraph starting at.
The first methodserializes content to XML as a series of SAX events triggered by therepository calling the methods of the supplied.
The second methodserializes content to an XML stream and outputs it to the supplied.
The resulting XML isin the system view form.
Ifisthen any properties of typewill be serialized with emptyelements. In the case of multi-valueproperties, the number of values in the property will be reflectedin the serialized output, though they will all be empty.
Ifisthen the actual values of eachproperty are serialized.
Ifisthen only the node atand its properties, but not its child nodes, are serialized. Ifisthen the entire subgraph is serialized.
The methods
and
work identically totheir respective system view variants, except that the resulting XMLis in the document view form.
Export obeys theaccess restrictions of the bound.If thelacks read access to some subsection of the specified content, thatsection is not exported.
The exported outputreflects the state of the bound persistent workspace as modified bythe transient store of the bound.This means that pending changes and all namespace mappings in thenamespace registry, as modified by the current session-mappings, arereflected in the output.
XML streams producedby export must be encoded in UTF-8 or UTF-16 as per the XMLspecification18.