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

    All Methods Instance Methods Concrete Methods
    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`

Copyright © 2025 MarkLogic Corporation. All Rights Reserved.

Complete online documentation for MarkLogic Server, XQuery and related components may be found at developer.marklogic.com