com.marklogic.xcc
Interface Content

All Known Implementing Classes:

OutputStreamContent, SemiBufferedContent

public interface Content

A Content object encapsulates content (a document) that can be transferred to and inserted into a contentbase. Because Session.insertContent(Content) automatically handles recovery of interrupted document inserts, Content objects must be rewindable to enable auto-retry.

It is possible to create non-rewindable Content instances, such as from an InputStream, which is too large to buffer and can only be consumed once. If a problem is encountered during or after a non-rewindable Content instance is processed then no automatic retries will be possible and an exception will be thrown.

If rewindable and non-rewindable Content objects are mixed together in a multi-document insert (Session.insertContent(Content[]) and only rewindable instances have so far been processed, the insert will be retryable. If a non-rewindable instance is in process or if the current instance is rewindable but a non-rewindable instance has previously been processed when a problem occurs then no automatic retry is possible and processing will stop with an exception.

Instances of this interface for common usage patterns may be created with the ContentFactory helper class. This interface may also be implemented by user code to handle specialized situations.

Method Summary

void	close() This method will be called after successfully consuming the content from the InputStream returned by openDataStream().
ContentCreateOptions	getCreateOptions() Return the ContentCreateOptions object which should be applied to this object.
String	getUri() The URI with which this content should be inserted.
boolean	isRewindable() Indicates whether this Content instance is rewindable and therefore automatically retryable.
InputStream	openDataStream() Return the byte stream that makes up this document.
void	rewind() This method tells the implementation that the content should be rewound to start again.
long	size() The size of the content, if known.

Method Detail

getUri

public String getUri()

The URI with which this content should be inserted.

Returns:

A URI as a String.

openDataStream

public InputStream openDataStream()
                           throws IOException

Return the byte stream that makes up this document. If the content is character data, as opposed to a binary BLOB, this should be a UTF-8 encoding of the characters.

Each call to this method returns a stream positioned at the beginning of the content. The InputStream object should be closed by the client. The returned InputStream is not intended to be shared. Each call to this method implies that any prior state should be discarded and a new stream created that is positioned at the beginning of the content.

Returns:

An open java.io.InputStream instance.

Throws:

IOException

getCreateOptions

public ContentCreateOptions getCreateOptions()

Return the ContentCreateOptions object which should be applied to this object. Note that if none was provided to the factory method that created this Content instance, one may have been created with appropriate defaults for the content provided.

Returns:

An instance of ContentCreateOptions.

isRewindable

public boolean isRewindable()

Indicates whether this Content instance is rewindable and therefore automatically retryable. If a content insertion (Session.insertContent(Content)) is interrupted and this method returns true, then the operation will automatically be restarted. If this method returns false, then an exception will be thrown immediately. If multiple Content objects are being inserted at once (Session.insertContent(Content[])) and any non-rewindable (Content object has already been even partially sent, the insert will fail immediately.

Returns:

True if rewindable (openDataStream() may be called repeatedly), false otherwise.

rewind

public void rewind()
            throws IOException

This method tells the implementation that the content should be rewound to start again. This method will only be called if isRewindable() returns true and in that case only after openDataStream() has been called.

Throws:

IOException - If there is a problem rewinding.

size

public long size()

The size of the content, if known.

Returns:

The size of the content, in bytes, of the content. If the size cannot be determined at the time this method is invoked (if the content is streaming for example), then -1 is returned.

close

public void close()

This method will be called after successfully consuming the content from the InputStream returned by openDataStream(). This method need not close the stream, that is the responsibility of the client, but it may invalidate the stream. This method is to inform the implementation that any resources it may be holding can be released.