Returns an
org.xml.sax.ContentHandler
which can be used to
push SAX events into the repository. If the incoming XML stream (in the
form of SAX events) does not appear to be a JCR system view XML document
then it is interpreted as a document view XML document.
The incoming XML is deserialized into a subgraph of items immediately
below the node at parentAbsPath
.
This method simply returns the ContentHandler
without
altering the state of the repository; the actual deserialization is done
through the methods of the ContentHandler
. Invalid XML data
will cause the ContentHandler
to throw a
SAXException
.
As SAX events are fed into the ContentHandler
, changes are
made directly at the workspace level, without going through the
Session
. As a result, there is not need to call
save
. The advantage of this direct-to-workspace method is
that a large import will not result in a large cache of pending nodes in
the Session
. The disadvantage is that structures that
violate node type constraints cannot be imported, fixed and then saved.
Instead, a constraint violation will cause the ContentHandler
to throw a SAXException
. See Session.getImportContentHandler
for a version of this method that does go through the
Session
.
The flag uuidBehavior
governs how the identifiers of
incoming (deserialized) nodes are handled. There are four options:
-
ImportUUIDBehavior#IMPORT_UUID_CREATE_NEW: Incoming nodes are
assigned newly created identifiers upon addition to the workspace. As a
result identifier collisions never occur.
-
ImportUUIDBehavior#IMPORT_UUID_COLLISION_REMOVE_EXISTING: If an incoming
node has the same identifier as a node already existing in the workspace,
then the already existing node (and its subgraph) is removed from
wherever it may be in the workspace before the incoming node is added.
Note that this can result in nodes "disappearing" from locations in the
workspace that are remote from the location to which the incoming
subgraph is being written.
-
ImportUUIDBehavior#IMPORT_UUID_COLLISION_REPLACE_EXISTING:
If an incoming node has the same identifier as a node already existing in
the workspace then the already existing node is replaced by the incoming
node in the same position as the existing node. Note that this may result
in the incoming subgraph being disaggregated and "spread around" to
different locations in the workspace. In the most extreme case this
behavior may result in no node at all being added as child of
parentAbsPath
. This will occur if the topmost element of the
incoming XML has the same identifier as an existing node elsewhere in the
workspace. -
ImportUUIDBehavior#IMPORT_UUID_COLLISION_THROW: If
an incoming node has the same identifier as a node already existing in
the workspace then a
SAXException
is thrown by the returned
ContentHandler
during deserialization.
A
SAXException
will be thrown by the returned
ContentHandler
during deserialization if the top-most
element of the incoming XML would deserialize to a node with the same
name as an existing child of
parentAbsPath
and that child
does not allow same-name siblings.
A SAXException
will also be thrown by the returned
ContentHandler
during deserialization if
uuidBehavior
is set to IMPORT_UUID_COLLISION_REMOVE_EXISTING
and an incoming node has the same identifier as the node at
parentAbsPath
or one of its ancestors.