7.3.7 Session Import Methods

The Session contains the following methods for importing and exporting content:

javax.jcr.
Session

ContentHandler

getImportContentHandler(String parentAbsPath,
int uuidBehavior)

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 system view XML document then it is interpreted as a document view XML document.

The incoming XML is deserialized into a subtree 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 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.getImportContentHandler for a version of this method that does not go through the session.

The flag uuidBehavior governs how the UUIDs of incoming (deserialized) nodes are handled. There are four options (defined as constants in the interface javax.jcr.ImportUUIDBehavior):

  • IMPORT_UUID_CREATE_NEW: Incoming referenceable nodes are added in the same way that new node is added with Node.addNode. That is, they are either assigned newly created UUIDs upon addition or upon save (depending on the implementation, see 4.9.1.1 When UUIDs are Assigned). In either case, UUID collisions will not occur.

  • IMPORT_UUID_COLLISION_REMOVE_EXISTING: If an incoming referenceable node has the same UUID as a node already existing in the workspace then the already existing node (and its subtree) 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 subtree is being written. Both the removal and the new addition will be persisted on save.

  • IMPORT_UUID_COLLISION_REPLACE_EXISTING: If an incoming referenceable node has the same UUID 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 subtree 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 UUID as an existing node elsewhere in the workspace. The change will be persisted on save.

  • IMPORT_UUID_COLLISION_THROW: If an incoming referenceable node has the same UUID 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 normal 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 also depends upon whether node type information in the imported data is respected, and this is an implementation-specific issue (see 7.3.3 Respecting Property Semantics).

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 UUID as the node at parentAbsPath or one of its ancestors.

A PathNotFoundException is thrown either immediately or on save if no node exists at parentAbsPath. Implementations may differ on when this validation is performed.

A ConstraintViolationException is thrown either immediately or on save if the new subtree 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 or on save if the node at parentAbsPath is versionable and checked-in, or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException is thrown either immediately or on save if a lock prevents the addition of the subtree. Implementations may differ on when this validation is performed.

A RepositoryException is thrown if another error occurs.

void

importXML(String parentAbsPath,
InputStream in,
int uuidBehavior)

Deserializes an XML document and adds the resulting item subtree as a child of the node at parentAbsPath.

If the incoming XML stream does not appear to be a system view XML document then it is interpreted as a document view XML document.

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 UUIDs of incoming (deserialized) nodes are handled. There are four options (defined as constants in the interface javax.jcr.ImportUUIDBehavior):

  • IMPORT_UUID_CREATE_NEW: Incoming referenceable nodes are added in the same way that new node is added with Node.addNode. That is, they are either assigned newly created UUIDs upon addition or upon save (depending on the implementation, see 4.9.1.1 When UUIDs are Assigned). In either case, UUID collisions will not occur.

  • IMPORT_UUID_COLLISION_REMOVE_EXISTING: If an incoming referenceable node has the same UUID as a node already existing in the workspace then the already existing node (and its subtree) 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 subtree is being written. Both the removal and the new addition will be persisted on save.

  • IMPORT_UUID_COLLISION_REPLACE_EXISTING: If an incoming referenceable node has the same UUID 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 subtree 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 UUID as an existing node elsewhere in the workspace. The change will be persisted on save.

  • IMPORT_UUID_COLLISION_THROW: If an incoming referenceable node has the same UUID 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 (see 7.3.3 Respecting Property Semantics).

A ConstraintViolationException will also be thrown immediately if uuidBehavior is set to IMPORT_UUID_COLLISION_REMOVE_EXISTING and an incoming node has the same UUID as the node at parentAbsPath or one of its ancestors.

A PathNotFoundException is thrown either immediately or on save if no node exists at parentAbsPath. Implementations may differ on when this validation is performed.

A VersionException is thrown either immediately or on save if the node at parentAbsPath is versionable and checked-in, or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException is thrown either immediately or on save if a lock prevents the addition of the subtree. Implementations may differ on when this validation is performed.

A RepositoryException is thrown if another error occurs.