com.marklogic.xcc

## Class ContentCreateOptions

- java.lang.Object
- - com.marklogic.xcc.ContentCreateOptions

- All Implemented Interfaces:
    java.lang.Cloneable

      public class ContentCreateOptions
      extends java.lang.Object
      implements java.lang.Cloneable

  A set of creation options to be applied to a document when it is inserted into a contentbase. By default, the document format is set to `DocumentFormat.NONE` which indicates that server-configured defaults should be used to determine the document format.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DEFAULT_ENCODING` The default character encoding (UTF-8) that will be assumed if not explicitly set by `setEncoding(String)`.
    `static int` | `MAX_BUFFER_SIZE` The maximum user-settable buffer size (12MB)
    `static int` | `MIN_BUFFER_SIZE` The minimum user-settable buffer size (256)

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ContentCreateOptions()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `clone()`
    `int` | `getBufferSize()` Return the preferred working buffer size to use for copying the content to the server.
    `java.lang.String[]` | `getCollections()` Return the set of collection URIs currently in effect for this options object.
    `java.lang.String` | `getEncoding()` Get the current charset encoding setting for this options object.
    `DocumentFormat` | `getFormat()` Return the document format value currently in effect for this options object.
    `java.lang.String` | `getGraph()` Get the RDF Graph for this options object
    `java.lang.String` | `getLanguage()` Get the current language setting for this options object.
    `java.util.Locale` | `getLocale()` Get the `Locale` setting for this options object.
    `java.util.Map<java.lang.String,java.lang.String>` | `getMetadata()` Return the set of metadata currently in effect for this options object.
    `java.lang.String` | `getNamespace()` Return the namespace name setting current in effect for this options object.
    `ContentPermission[]` | `getPermissions()` Return the set of document permissions currently in effect for this options object.
    `java.math.BigInteger[]` | `getPlaceKeys()` Returns the set of forest placement keys (forest IDs) currently in effect for this options object.
    `int` | `getQuality()` Return the quality value currently set on this options object.
    `DocumentRepairLevel` | `getRepairLevel()` Return the current document repair level setting.
    `int` | `getResolveBufferSize()` Indicate the buffer size to use for entity resolution.
    `boolean` | `getResolveEntities()` Get the current setting of the flag which indicates whether or not to resolve entities embedded in an XML document to be inserted.
    `java.lang.String` | `getTemporalCollection()` Get the temporal collection for this options object.
    `java.lang.String` | `getTemporalVersionURI()` Get the temporal version URI for this options object.
    `static ContentCreateOptions` | `newBinaryInstance()` Create an instance with format set to `DocumentFormat.BINARY`.
    `static ContentCreateOptions` | `newJsonInstance()` Create an instance with format set to `DocumentFormat.JSON`.
    `static ContentCreateOptions` | `newTextInstance()` Create an instance with format set to `DocumentFormat.TEXT`.
    `static ContentCreateOptions` | `newXmlInstance()` Create an instance with format set to `DocumentFormat.XML`.
    `void` | `setBufferSize(int newSize)` Set a preferred working buffer size to use for copying to the server.
    `void` | `setCollections(java.lang.String[] collections)` Set an array of URIs that represent collections to which the document(s) will be added when inserted.
    `void` | `setEncoding(java.lang.String encoding)` Set the charset encoding to be used by the server when loading this document.
    `void` | `setFormat(DocumentFormat format)` Set the format of the document to be created to the given type.
    `void` | `setFormatBinary()` Convenience method equivalent to `setFormat (DocumentFormat.BINARY);`.
    `void` | `setFormatJson()` Convenience method equivalent to `setFormat (DocumentFormat.JSON);`.
    `void` | `setFormatText()` Convenience method equivalent to `setFormat (DocumentFormat.TEXT);`.
    `void` | `setFormatXml()` Convenience method equivalent to `setFormat (DocumentFormat.XML);`.
    `void` | `setGraph(java.lang.String graph)` Set the RDF Graph for this options object
    `void` | `setLanguage(java.lang.String language)` Set the language name to associate with inserted documents.
    `void` | `setLocale(java.util.Locale locale)` Set the effective `Locale` value for this options object.
    `void` | `setMetadata(java.util.Map<java.lang.String,java.lang.String> metadata)` Set an map of metadata key and metadata values that represent metadata to which the document(s) will be added when inserted.
    `void` | `setNamespace(java.lang.String namespace)` Set a namespace name, which will used as the namespace associated with inserted documents.
    `void` | `setPermissions(ContentPermission[] permissions)` Set the permissions to be applied when documents are inserted.
    `void` | `setPlaceKeys(java.math.BigInteger[] forestKeys)` Set the forest placement keys for this options object as an array of `BigInteger` objects.
    `void` | `setPlaceKeys(long[] forestKeys)` Set the forest placement keys as long values.
    `void` | `setQuality(int quality)` Set the quality value for this options object, which will set on inserted documents.
    `void` | `setRepairLevel(DocumentRepairLevel repairLevel)` Set the document repair level for this options object.
    `void` | `setResolveBufferSize(int resolveBufferSize)` Set the entity resulution buffer size.
    `void` | `setResolveEntities(boolean resolveEntities)` Set the flag indicating whether embedded entities should be resolved during content insertion.
    `void` | `setTemporalCollection(java.lang.String temporalCollection)` Set the temporal collection to associate with inserted documents.
    `void` | `setTemporalVersionURI(java.lang.String temporalVersionURI)` Set the temporal version URI to associate with inserted documents.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### DEFAULT_ENCODING

          public static final java.lang.String DEFAULT_ENCODING

      The default character encoding (UTF-8) that will be assumed if not explicitly set by `setEncoding(String)`.
      See Also:
        Constant Field Values

    - #### MIN_BUFFER_SIZE

          public static final int MIN_BUFFER_SIZE

      The minimum user-settable buffer size (256)
      See Also:
        Constant Field Values

    - #### MAX_BUFFER_SIZE

          public static final int MAX_BUFFER_SIZE

      The maximum user-settable buffer size (12MB)
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ContentCreateOptions

          public ContentCreateOptions()

  - ### Method Detail

    - #### newXmlInstance

          public static ContentCreateOptions newXmlInstance()

      Create an instance with format set to `DocumentFormat.XML`.
      Returns:
        An options object that specifies XML format.

    - #### newTextInstance

          public static ContentCreateOptions newTextInstance()

      Create an instance with format set to `DocumentFormat.TEXT`.
      Returns:
        An options object that specifies text() format.

    - #### newBinaryInstance

          public static ContentCreateOptions newBinaryInstance()

      Create an instance with format set to `DocumentFormat.BINARY`.
      Returns:
        An options object that specifies binary() format.

    - #### newJsonInstance

          public static ContentCreateOptions newJsonInstance()

      Create an instance with format set to `DocumentFormat.JSON`.
      Returns:
        An options object that specifies json format.

    - #### setFormat

          public void setFormat(DocumentFormat format)

      Set the format of the document to be created to the given type. If never set, the document format is `DocumentFormat.NONE` which indicates that the server should apply its configured rules for determining the document format. This may include choosing a format according to the suffix of the document URI.
      Parameters:
        `format` - An instance of `DocumentFormat`.

    - #### getFormat

          public DocumentFormat getFormat()

      Return the document format value currently in effect for this options object.
      Returns:
        An instance of `DocumentFormat`

    - #### setFormatXml

          public void setFormatXml()

      Convenience method equivalent to `setFormat (DocumentFormat.XML);`.

    - #### setFormatText

          public void setFormatText()

      Convenience method equivalent to `setFormat (DocumentFormat.TEXT);`.

    - #### setFormatBinary

          public void setFormatBinary()

      Convenience method equivalent to `setFormat (DocumentFormat.BINARY);`.

    - #### setFormatJson

          public void setFormatJson()

      Convenience method equivalent to `setFormat (DocumentFormat.JSON);`.

    - #### getRepairLevel

          public DocumentRepairLevel getRepairLevel()

      Return the current document repair level setting. The default value is `DocumentRepairLevel.DEFAULT`, but this option is only applicable when the document format is `DocumentFormat.XML`.
      Returns:
        An instance of `DocumentRepairLevel`.

    - #### setRepairLevel

          public void setRepairLevel(DocumentRepairLevel repairLevel)

      Set the document repair level for this options object. The default value is `DocumentRepairLevel.DEFAULT`, but this option is only applicable when the document format is `DocumentFormat.XML`.
      Parameters:
        `repairLevel` - An instance of `DocumentRepairLevel`.

    - #### getLocale

          public java.util.Locale getLocale()

      Get the `Locale` setting for this options object.
      Returns:
        An instance of `Locale`, or null.

    - #### setLocale

          public void setLocale(java.util.Locale locale)

      Set the effective `Locale` value for this options object. The default is null, which indicates that the local JVM default value is to be applied. Note that the server may not support the locale configured as the local client default. In such a case it may be necessary to explicitly set the `Locale` to a value recognized by the server for content insertion to succeed.
      Parameters:
        `locale` - An instance of `Locale`.

    - #### getMetadata

          public java.util.Map<java.lang.String,java.lang.String> getMetadata()

      Return the set of metadata currently in effect for this options object.
      Returns:
        An map of metadata keys and metadata values, or null.

    - #### setMetadata

          public void setMetadata(java.util.Map<java.lang.String,java.lang.String> metadata)

      Set an map of metadata key and metadata values that represent metadata to which the document(s) will be added when inserted. The default is null.
      Parameters:
        `metadata` - A map of metadata keys and metadata values.

    - #### getResolveEntities

          public boolean getResolveEntities()

      Get the current setting of the flag which indicates whether or not to resolve entities embedded in an XML document to be inserted. If true, any entity references in a document being inserted will be resolved (if possible) by XCC and sent to the server for inline expansion. If false, entities will simply be stored as text. The default is false and this flag is only meaningful when the format is `DocumentFormat.XML`.
      Returns:
        A boolean value.

    - #### setResolveEntities

          public void setResolveEntities(boolean resolveEntities)

      Set the flag indicating whether embedded entities should be resolved during content insertion. The default is false. When XCC is set to be in HTTP compliant mode through system property "xcc.httpcompliant", setting the flag to true will throw UnsupportedOperationException.
      Parameters:
        `resolveEntities` - A boolean indicating whether entities should be resolved or not.
      See Also:
        `getResolveEntities()`

    - #### getResolveBufferSize

          public int getResolveBufferSize()

      Indicate the buffer size to use for entity resolution. The default is zero.
      Returns:
        An integer value, possibly zero.

    - #### setResolveBufferSize

          public void setResolveBufferSize(int resolveBufferSize)

      Set the entity resulution buffer size. This value is passed to the server and is not used directly by XCC. The default is 0, which indicates that a reasonable default should be used. The default should be appropriate for all but the most unusual of circumstances.
      Parameters:
        `resolveBufferSize` - The buffer size to pass the server.

    - #### getQuality

          public int getQuality()

      Return the quality value currently set on this options object.
      Returns:
        An integer value.

    - #### setQuality

          public void setQuality(int quality)

      Set the quality value for this options object, which will set on inserted documents. The default is zero.
      Parameters:
        `quality` - An integer value.

    - #### getNamespace

          public java.lang.String getNamespace()

      Return the namespace name setting current in effect for this options object.
      Returns:
        A namespace name `String`, or null.

    - #### setNamespace

          public void setNamespace(java.lang.String namespace)

      Set a namespace name, which will used as the namespace associated with inserted documents. The default is null, which indicates that the default namespace should be used.
      Parameters:
        `namespace` - A namespace name as a `String`, or null to reset to default.

    - #### getLanguage

          public java.lang.String getLanguage()

      Get the current language setting for this options object.
      Returns:
        A language name as a `String`, or null.

    - #### setLanguage

          public void setLanguage(java.lang.String language)

      Set the language name to associate with inserted documents. A value of `en` indicates that the document is in english. The default is null, which indicates to use the server default.
      Parameters:
        `language` - A language name as a `String`, or null to reset to the default.

    - #### getEncoding

          public java.lang.String getEncoding()

      Get the current charset encoding setting for this options object.
      Returns:
        A charset encoding name, as a `String`
      Since:
        3.2

    - #### setEncoding

          public void setEncoding(java.lang.String encoding)

      Set the charset encoding to be used by the server when loading this document. The encoding provided will be passed to the server at document load time and must be a name that it recognizes. The document byte stream will be transcoded to UTF-8 for storage.

      Note: UTF-8 encoded files may contain a three-byte Byte Order Mark at the beginning which decodes as the Unicode character ﻿. As of 4.0, this value is no longer ignored by the server. When it's safe to do so, XCC will strip the BOM, which is not considered to be part of the content. XCC will not strip the BOM if the encoding is not UTF-8 (either explicitly set, or defaulted) and the document format (`setFormat(DocumentFormat)`) is not text or XML. If the document format is not explicitly set, BOM stripping will not occur (because the server may choose to treat the content as binary) and document insertion may fail if a BOM is present.

      Parameters:
        `encoding` - The name of an encoding to be used to interpret the document data as it is loaded by the server. A value of null sets the encoding to the default ( `DEFAULT_ENCODING`).
      Since:
        3.2

    - #### getCollections

          public java.lang.String[] getCollections()

      Return the set of collection URIs currently in effect for this options object.
      Returns:
        An array of URI `String`s, or null.

    - #### setCollections

          public void setCollections(java.lang.String[] collections)

      Set an array of URIs that represent collections to which the document(s) will be added when inserted. The default is null, which indicates that the document(s) should be added to the users default collections.
      Parameters:
        `collections` - An array of `String`s which are collection URIs.

    - #### getPlaceKeys

          public java.math.BigInteger[] getPlaceKeys()

      Returns the set of forest placement keys (forest IDs) currently in effect for this options object. Although forest placement keys may be specified in two ways, as `BigInteger` or and long, they are always stored internally as `BigInteger` objects.

      If the URI of the document being inserted already exists exists in the contentbase, it will remain in the same forest. If a specified forest ID does not exist, that is an error. If more than one forest ID is given, the document will be placed in one of them at the server's discretion.

      Returns:
        An array of `BigInteger` objects, or null.

    - #### setPlaceKeys

          public void setPlaceKeys(java.math.BigInteger[] forestKeys)

      Set the forest placement keys for this options object as an array of `BigInteger` objects. Forest IDs are unsigned 64-bit values generated by the server. Because Java long values are signed longs, there is a possiblity that forest IDs cannot reliably be represented by Java longs.

      While is it not possible to specify forest placement directly by forest name, is it very easy to map forest names to forest IDs. The `ContentbaseMetaData.getForestMap()` method will return a `Map` of the forest names and their associated IDs.

      Parameters:
        `forestKeys` - An array of `BigInteger` objects or null to set default.

    - #### setPlaceKeys

          public void setPlaceKeys(long[] forestKeys)

      Set the forest placement keys as long values. The values provided, if any, will be converted and stored a `BigInteger` objects.
      Parameters:
        `forestKeys` - An array of long values.
      See Also:
        `setPlaceKeys(java.math.BigInteger[])`

    - #### getPermissions

          public ContentPermission[] getPermissions()

      Return the set of document permissions currently in effect for this options object.
      Returns:
        An array of `ContentPermission` objects, or null.

    - #### setPermissions

          public void setPermissions(ContentPermission[] permissions)

      Set the permissions to be applied when documents are inserted. The default is null, which indicates that the default permissions for user should be applied.
      Parameters:
        `permissions` - An array of `ContentPermission` objects or null to reset to defaults.

    - #### getBufferSize

          public int getBufferSize()

      Return the preferred working buffer size to use for copying the content to the server.
      Returns:
        The user-supplied buffer size, or -1.

    - #### setBufferSize

          public void setBufferSize(int newSize)

      Set a preferred working buffer size to use for copying to the server. A value of -1, the default, indicates that an internal default should be used. If the value supplied is less than one, it will treated as -1. Positive values will be constrained to `MIN_BUFFER_SIZE` and `MAX_BUFFER_SIZE`. This buffer size is a maximum. If the actual size of the content is smaller than this size, a buffer of the smaller size will be used.
      Parameters:
        `newSize` - A preferred buffer size, or -1 to use the default.

    - #### getTemporalCollection

          public java.lang.String getTemporalCollection()

      Get the temporal collection for this options object.
      Returns:
        Temporal collection as a `String`, or null.

    - #### setTemporalCollection

          public void setTemporalCollection(java.lang.String temporalCollection)

      Set the temporal collection to associate with inserted documents. A value of null indicates that the document is not temporal. The default is null.
      Parameters:
        `temporalCollection` - A temporal collection as a `String`, or null for non-temporal.

    - #### getTemporalVersionURI

          public java.lang.String getTemporalVersionURI()

      Get the temporal version URI for this options object.
      Returns:
        Temporal collection a `String`, or null.

    - #### setTemporalVersionURI

          public void setTemporalVersionURI(java.lang.String temporalVersionURI)

      Set the temporal version URI to associate with inserted documents. The default is null. Only used when temporalCollection is set as well.
      Parameters:
        `temporalVersionURI` - A URI as a `String` or null.

    - #### getGraph

          public java.lang.String getGraph()

      Get the RDF Graph for this options object
      Returns:
        A graph iri as `String`, or null.

    - #### setGraph

          public void setGraph(java.lang.String graph)

      Set the RDF Graph for this options object
      Parameters:
        `graph` - A graph iri as `String`.

    - #### clone

          public java.lang.Object clone()

      Overrides:
        `clone` in class `java.lang.Object`

Copyright © 2025 MarkLogic Corporation

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