com.marklogic.xcc
Class ContentCreateOptions

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

public class ContentCreateOptions
extends Object

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

static 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

ContentCreateOptions()

Method Summary

int	getBufferSize() Return the preferred working buffer size to use for copying the content to the server.
String[]	getCollections() Return the set of collection URIs currently in effect for this options object.
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.
String	getLanguage() Get the current language setting for this options object.
Locale	getLocale() Get the Locale setting for this options object.
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.
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 the flag which indicates whether or not to resolve entities embedded in an XML document to be inserted.
static ContentCreateOptions	newBinaryInstance() Create an instance with format set to DocumentFormat.BINARY.
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(String[] collections) Set an array of URIs that represent collections to which the document(s) will be added when inserted.
void	setEncoding(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	setFormatText() Convenience method equivalent to setFormat (DocumentFormat.TEXT);.
void	setFormatXml() Convenience method equivalent to setFormat (DocumentFormat.XML);.
void	setLanguage(String language) Set the language name to associate with inserted documents.
void	setLocale(Locale locale) Set the effective Locale value for this options object.
void	setNamespace(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(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.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ENCODING

public static final 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.

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);.

getRepairLevel

public DocumentRepairLevel getRepairLevel()

Return the current document repair level setting. The default value is DocumentRepairLevel.FULL, 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.FULL, but this option is only applicable when the document format is DocumentFormat.XML.

Parameters:

repairLevel - An instance of DocumentRepairLevel.

getLocale

public Locale getLocale()

Get the Locale setting for this options object.

Returns:

An instance of Locale, or null.

setLocale

public void setLocale(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.

getResolveEntities

public boolean getResolveEntities()

Get the current setting of the 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.

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

Get the current language setting for this options object.

Returns:

A language name as a String, or null.

setLanguage

public void setLanguage(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 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(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 String[] getCollections()

Return the set of collection URIs currently in effect for this options object.

Returns:

An array of URI Strings, or null.

setCollections

public void setCollections(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 Strings which are collection URIs.

getPlaceKeys

public 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(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.