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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `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.

- - ### Method Detail

    - #### getUri

          java.lang.String getUri()

      The URI with which this content should be inserted.
      Returns:
        A URI as a String.

    - #### openDataStream

          java.io.InputStream openDataStream()
                                      throws java.io.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:
        `java.io.IOException`

    - #### getCreateOptions

          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

          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

          void rewind()
               throws java.io.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:
        `java.io.IOException` - If there is a problem rewinding.

    - #### size

          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

          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.

Copyright © 2025 MarkLogic Corporation

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