net.sf.exorcist.api
Interface ContentState

All Known Implementing Classes:

FileContentState, MemoryContentState, MultiState

public interface ContentState

State of a content tree being migrated. The Exorcist system represents content as a combination of an XML document and a set of binary attachments. Instead of working on live content repositories, the Exorcist system uses exporter plugins to acquire state snapshots of selected parts of the content repositories. These snapshots are represented as ContentState instances that can then be modified or transformed by converter plugins without concerns for the originating content repository. Importer plugins use ContentState instances as content sources for populating or updating target content repositories.

The content XML document is kept in a serialized format to avoid forcing any specific XML document or processing model (DOM, SAX, etc.) on the Exorcist plugins. The downside of this feature is that each plugin needs to separately parse and serialize the content documents.

ContentState instances are normally created and managed by the Exorcist framework instead of individual plugins. It is up to the framework to decide whether to use a memory- or filesystem-based (or some other) ContentState implementation.

Method Summary

java.lang.String	addAttachment(java.io.InputStream data) Adds a binary attachment.
java.io.InputStream	getAttachment(java.lang.String hash) Returns the attachment with the given hash code.
java.util.Collection	getAttachmentHashes() Returns the hashe codes of all the attachments.
java.io.InputStream	getContent() Returns the serialized XML document that represents the content state snapshot.
void	removeAttachment(java.lang.String hash) Removes the attachment with the given hash code.
void	setContent(java.io.InputStream content) Sets the serialized XML document that represents the content state snapshot.

Method Detail

setContent

void setContent(java.io.InputStream content)
                throws java.io.IOException

Sets the serialized XML document that represents the content state snapshot.

The given input stream should contain a well-formed XML document. The implementation class is not required to strictly enforce this requirement to avoid unnecessary processing, but failure to produce a well-formed XML document should still be considered a fatal error.

The given input stream is consumed until it ends or an exception occurs, but it is not closed. It is the responsibility of the caller to properly close the stream.

Parameters:

content - content XML stream

Throws:

java.io.IOException - if the stream can not be read

getContent

java.io.InputStream getContent()
                               throws java.io.IOException

Returns the serialized XML document that represents the content state snapshot.

The returned input stream should always contain a well-formed XML document although the implementation class might not strictly enforce this. Possible XML parsing exceptions can thus be treated as fatal errors.

The returned input stream belongs to the caller and should be closed when it is no longer used.

Returns:

content XML

Throws:

java.io.IOException - if the stream can not be created

addAttachment

java.lang.String addAttachment(java.io.InputStream data)
                               throws java.io.IOException

Adds a binary attachment. The attachment is read from the given input stream and the SHA-1 hash of the received data is computed. The binary data is saved as a part of the content state and the identifying hash code is returned as a hex-encoded string.

The given input stream is consumed until it ends or an exception occurs, but it is not closed. It is the responsibility of the caller to properly close the stream.

Parameters:

data - input stream containing the attachment

Returns:

the SHA-1 hash of the attachment

Throws:

java.io.IOException - if the attachment stream could not be read

getAttachmentHashes

java.util.Collection getAttachmentHashes()

Returns the hashe codes of all the attachments.

Returns:

SHA-1 hashes of all the attachments

getAttachment

java.io.InputStream getAttachment(java.lang.String hash)
                                  throws java.io.IOException,
                                         java.lang.IllegalArgumentException

Returns the attachment with the given hash code. The binary contents of the identified attachment is returned as an input stream. The caller should make sure that the returned input stream is properly closed when it is no longer used.

Parameters:

hash - SHA-1 hash of the attachment

Returns:

input stream containing the attached data

Throws:

java.lang.IllegalArgumentException - if an attachment with the given hash code does not exist

java.io.IOException - if the stream can not be created

removeAttachment

void removeAttachment(java.lang.String hash)
                      throws java.lang.IllegalArgumentException

Removes the attachment with the given hash code.

Parameters:

hash - SHA-1 hash of the attachment

Throws:

java.lang.IllegalArgumentException - if an attachment with the given hash code does not exist