com.marklogic.xcc.examples

Class SemiBufferedContent

java.lang.Object

com.marklogic.xcc.examples.SemiBufferedContent

All Implemented Interfaces:

Content

public class SemiBufferedContent
extends java.lang.Object
implements Content

This is a specialized Content implementation that takes an InputStream and will either buffer the content of the stream if it's small enough, or copy the content to a temporary disk file otherwise.

Click here for the source code for this class

Use this class rather than ContentFactory.newContent(String, java.io.InputStream, com.marklogic.xcc.ContentCreateOptions) when the size of the input stream may be too large to buffer in memory and you need to assure that retries are supported when calling Session.insertContent(com.marklogic.xcc.Content).

A buffer will be allocated of the size you specify. The InputStream will be read into that buffer until either the stream is fully read or the buffer fills up. If all the content fits into the buffer, then this class will be equivalent to ContentFactory.newContent(String, byte[], com.marklogic.xcc.ContentCreateOptions) . If the internal buffer fills up, then a temp file is created and all the content is written to it. This class will then be equivalent to ContentFactory.newContent(String, java.io.File, com.marklogic.xcc.ContentCreateOptions) .

If you provide a File object as the fifth argument to the constructor, then it is passed to File.createTempFile(String, String, java.io.File) to specify the directory in which to create the temporary file. If null, then the system-default temp directory is used.

Constructor Summary

Constructors

Constructor and Description
SemiBufferedContent(java.lang.String uri, ContentCreateOptions options, java.io.InputStream input, int bufferSize) Instantiate a Content object that will either buffer the InputStream or copy it to disk, depending on whether the size exceeds the provided buffer size.
SemiBufferedContent(java.lang.String uri, ContentCreateOptions options, java.io.InputStream input, int bufferSize, java.io.File directory) Instantiate a Content object that will either buffer the InputStream or copy it to disk, depending on whether the stream size exceeds the provided buffer size.

Method Summary

Modifier and Type	Method and Description
void	close() This method will be called after successfully consuming the content from the InputStream returned by Content.openDataStream().
ContentCreateOptions	getCreateOptions() Return the ContentCreateOptions object which should be applied to this object.
java.lang.String	getUri() The URI with which this content should be inserted.
boolean	isRewindable() Indicates whether this Content instance is rewindable and therefore automatically retryable.
java.io.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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SemiBufferedContent

public SemiBufferedContent(java.lang.String uri,
                           ContentCreateOptions options,
                           java.io.InputStream input,
                           int bufferSize,
                           java.io.File directory)
                    throws java.io.IOException

Instantiate a Content object that will either buffer the InputStream or copy it to disk, depending on whether the stream size exceeds the provided buffer size.

Parameters:

uri - The URI to use when the content is inserted.

options - The ContentCreateOptions object to use when the content is inserted.

input - An InputStream object, which will be consumed when this object is created.

bufferSize - The maximum number of bytes to buffer in memory before spilling the content to a temporary disk file.

directory - A File object that specifies a directory where the temporary file, if needed, will be created. This parameter may be null.

Throws:

java.io.IOException - If there is a problem reading the InputStream or creating the temporary file.

SemiBufferedContent

public SemiBufferedContent(java.lang.String uri,
                           ContentCreateOptions options,
                           java.io.InputStream input,
                           int bufferSize)
                    throws java.io.IOException

Instantiate a Content object that will either buffer the InputStream or copy it to disk, depending on whether the size exceeds the provided buffer size. This constructor defaults to using the system-specific temporary file directory.

Parameters:

uri - The URI to use when the content is inserted.

options - The ContentCreateOptions object to use when the content is inserted.

input - An InputStream object, which will be consumed when this object is created.

bufferSize - The maximum number of bytes to buffer in memory before spilling the content to a temporary disk file.

Throws:

java.io.IOException - If there is a problem reading the InputStream or creating the temporary file.

Method Detail

getUri

public java.lang.String getUri()

Description copied from interface: Content

The URI with which this content should be inserted.

Specified by:

getUri in interface Content

Returns:

A URI as a String.

openDataStream

public java.io.InputStream openDataStream()
                                   throws java.io.IOException

Description copied from interface: Content

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.

Specified by:

openDataStream in interface Content

Returns:

An open java.io.InputStream instance.

Throws:

java.io.IOException

getCreateOptions

public ContentCreateOptions getCreateOptions()

Description copied from interface: Content

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.

Specified by:

getCreateOptions in interface Content

Returns:

An instance of ContentCreateOptions.

isRewindable

public boolean isRewindable()

Description copied from interface: Content

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.

Specified by:

isRewindable in interface Content

Returns:

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

rewind

public void rewind()
            throws java.io.IOException

Description copied from interface: Content

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

Specified by:

rewind in interface Content

Throws:

java.io.IOException - If there is a problem rewinding.

size

public long size()

Description copied from interface: Content

The size of the content, if known.

Specified by:

size in interface Content

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()

Description copied from interface: Content

This method will be called after successfully consuming the content from the InputStream returned by Content.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.

Specified by:

close in interface Content