Deserializes an XML document and adds the resulting item subgraph as a
child of the node at
parentAbsPath
.
If the incoming XML stream does not appear to be a JCR system view
XML document then it is interpreted as a document view XML
document.
The passed InputStream
is closed before this method returns
either normally or because of an exception.
The tree of new items is built in the transient storage of the
Session
. In order to persist the new content,
save
must be called. The advantage of this
through-the-session method is that (depending on what constraint checks
the implementation leaves until save
) structures that
violate node type constraints can be imported, fixed and then saved. The
disadvantage is that a large import will result in a large cache of
pending nodes in the session. See
Workspace#importXML for a
version of this method that does not go through the
Session
.
The flag uuidBehavior
governs how the identifiers of
incoming nodes are handled. There are four options:
-
ImportUUIDBehavior#IMPORT_UUID_CREATE_NEW: Incoming 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, see 4.9.1.1
When Identifiers are Assigned in the specification). 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
dispatched 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 dispatched on save
. -
ImportUUIDBehavior#IMPORT_UUID_COLLISION_THROW: If an incoming
node has the same identifier as a node already existing in the workspace
then an
ItemExistsException
is thrown.
Unlike
Workspace#importXML, this method does not necessarily enforce all
node type constraints during deserialization. Those that would be
immediately enforced in a normal write method (
Node.addNode
,
Node.setProperty
etc.) of this implementation cause an
immediate
ConstraintViolationException
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 ConstraintViolationException
will also be thrown
immediately 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. 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.