Movatterモバイル変換

javax.jcr.
Session

ContentHandler

getImportContentHandler(String parentAbsPath,
int uuidBehavior)

Returns anorg.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 asystem view XML document then it is interpreted as adocument view XML document.

The incoming XML is deserialized into a subtree of items immediately below the node atparentAbsPath.

This method simply returns theContentHandler without altering the state of the session; the actual deserialization to the session transient space is done through the methods of theContentHandler. Invalid XML data will cause theContentHandler to throw aSAXException.

As SAX events are fed into theContentHandler, 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 untilsave) 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. SeeWorkspace.getImportContentHandler for a version of this method thatdoes not go through the session.

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

• IMPORT_UUID_CREATE_NEW: Incoming referenceable nodes are added in the same way that new node is added withNode.addNode. That is, they are either assigned newly created UUIDs upon addition or uponsave (depending on the implementation, see4.9.1.1When 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 onsave.

• 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 ofparentAbsPath. 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 onsave.

• IMPORT_UUID_COLLISION_THROW: If an incoming referenceable node has the same UUID as a node already existing in the workspace then aSAXException is thrown by theContentHandler during deserialization.

UnlikeWorkspace.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 returnedContentHandler to throw an immediateSAXException during deserialization. All other constraints are checked onsave, 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).

ASAXException will also be thrown by the returnedContentHandler during deserialization ifuuidBehavior is set toIMPORT_UUID_COLLISION_REMOVE_EXISTING and an incoming node has the same UUID as the node atparentAbsPath or one of its ancestors.

APathNotFoundException is thrown either immediately or onsave if no node exists atparentAbsPath. Implementations may differ on when this validation is performed.

AConstraintViolationException is thrown either immediately or onsave if the new subtree cannot be added to the node atparentAbsPath due to node-type or other implementation-specific constraints. Implementations may differ on when this validation is performed.

AVersionException is thrown either immediately or onsave if the node atparentAbsPath 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.

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

ARepositoryException 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 atparentAbsPath.

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

The tree of new items is built in the transient storage of theSession. 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 untilsave) 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 thesession. SeeWorkspace.importXML for a version of this method thatdoes not go through theSession.

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

• IMPORT_UUID_CREATE_NEW: Incoming referenceable nodes are added in the same way that new node is added withNode.addNode. That is, they are either assigned newly created UUIDs upon addition or uponsave (depending on the implementation, see4.9.1.1When 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 onsave.

• 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 ofparentAbsPath. 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 onsave.

• IMPORT_UUID_COLLISION_THROW: If an incoming referenceable node has the same UUID as a node already existing in the workspace then anItemExistsException is thrown.

UnlikeWorkspace.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 immediateConstraintViolationException during deserialization. All other constraints are checked onsave, 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).

AConstraintViolationException will also be thrown immediately ifuuidBehavior is set toIMPORT_UUID_COLLISION_REMOVE_EXISTING and an incoming node has the same UUID as the node atparentAbsPath or one of its ancestors.

APathNotFoundException is thrown either immediately or onsave if no node exists atparentAbsPath. Implementations may differ on when this validation is performed.

AVersionException is thrown either immediately or onsave if the node atparentAbsPath 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.

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

ARepositoryException is thrown if another error occurs.