7.3.8 Importing jcr:root

If the root node of a workspace is exported it will be rendered in XML (in either view) under the name jcr:root (see 6.4 XML Mappings). In addition, if the root node has a UUID (in many implementations it will, see 4.9 Referenceable Nodes) this will also be recorded in the serialization.

If this XML document is imported back into the workspace a number of different results may occur, depending on the methods and settings used to perform the import. The following summarizes the possible results of using various uuidBehavior values (in either using either Workspace.getImportContentHandler or Workspace.importXML) when a node with the same UUID as the existing root node is encountered on import (the constants below are defined in the interface javax.jcr.ImportUUIDBehavior).

IMPORT_UUID_CREATE_NEW: The XML element representing jcr:root is rendered as a normal node at the position specified (with the name jcr:root). It gets a new UUID, so there is no effect on the existing root node of the workspace.

IMPORT_UUID_COLLISION_REMOVE_EXISTING: If deserialization is done through a ContentHandler (acquired by getImportContentHandler) a SAXException will be thrown. Similarly, if deserialization is done through importXML a ConstraintViolationException will be thrown. Note that this is simply a special case of the general rule that under this uuidBehavior setting, an exception will be thrown on any attempt to import a node with the same UUID as the node at parentAbsPath or any of its ancestors (which, of course, includes the root node).

IMPORT_UUID_COLLISION_REPLACE_EXISTING: This setting is equivalent to importing into the Session and then calling save since save always operates according to UUID (plus relative path, for non-referenceables). In both cases the result is that the root node of the workspace will be replaced along with its subtree (i.e., the whole workspace), just as if the root node had been altered through the normal getNode, change, save cycle.

IMPORT_UUID_COLLISION_THROW: Under this setting a ContentHandler will throw a SAXException and the importXML method will throw ItemExistsException.

Note that an implementation is always free to prevent the replacement of a root node (or indeed any node) either through access control restrictions or other implementation-specific restrictions.