Returns an
org.xml.sax.ContentHandler
which is used to push
SAX events to the repository. If the incoming XML (in the form of SAX
events) does not appear to be a JCR
system view XML document then
it is interpreted as a JCR
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 session; the actual deserialization to the
session transient space 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
, the tree of
new items is built in the transient storage of the session. In order to
dispatch the new content, save
must be called. See
Workspace#getImportContentHandler for a workspace-write version of this
method.
The flag uuidBehavior
governs how the identifiers of
incoming nodes are handled:
-
ImportUUIDBehavior#IMPORT_UUID_CREATE_NEW:
Incoming identifiers nodes are added in the same way that new node is
added with
Node.addNode
. That is, they are either assigned
newly created identifiers upon addition or upon save
(depending on the implementation). In either case, identifier collisions
will not 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. Both the removal and the new addition
will be persisted on
save
. -
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. The change will be persisted on save
. -
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
ContentHandler
during deserialization.
Unlike
Workspace.getImportContentHandler
, this method does not
necessarily enforce all node type constraints during deserialization.
Those that would be immediately enforced in a session-write method
(
Node.addNode
,
Node.setProperty
etc.) of this
implementation cause the returned
ContentHandler
to throw an
immediate
SAXException
during deserialization. All other
constraints are checked on save, just as they are in normal write
operations. However, which node type constraints are enforced depends
upon whether node type information in the imported data is respected, and
this is an implementation-specific issue.
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.
A PathNotFoundException
is thrown either immediately, on
dispatch or on persist, if no node exists at parentAbsPath
.
Implementations may differ on when this validation is performed
A ConstraintViolationException
is thrown either immediately,
on dispatch or on persist, if the new subgraph cannot be added to the
node at parentAbsPath
due to node-type or other
implementation-specific constraints, and this can be determined before
the first SAX event is sent. Implementations may differ on when this
validation is performed.
A VersionException
is thrown either immediately, on dispatch
or on persist, if the node at parentAbsPath
is read-only due
to a check-in. Implementations may differ on when this validation is
performed.
A LockException
is thrown either immediately, on dispatch or
on persist, if a lock prevents the addition of the subgraph.
Implementations may differ on when this validation is performed.