org.exist.fluent
Class Source

java.lang.Object
  org.exist.fluent.Source

Direct Known Subclasses:

Source.Blob, Source.XML

public abstract class Source
extends Object

A source of data to be loaded into the database, distinguishing between XML documents and other (binary) documents. While you can load XML documents as binary without problem, but will not be able to query them or otherwise access their structure in the database.

Author:

Piotr Kaminski

Nested Class Summary

static class	Source.Blob A source of binary data to be loaded into the database.
static class	Source.XML A source of XML data to be loaded into the database.

Method Summary

static Source.Blob	blob(byte[] bytes) Create a source of binary data from the given byte array.
static Source.Blob	blob(File file) Create a source that reads a binary document from an external file.
static Source.Blob	blob(InputStream stream) Create a source of binary data that reads from the given input stream.
static Source.Blob	blob(Reader reader) Create a source of binary data that reads from the given reader.
static Source.Blob	blob(String literal) Create a source of binary data from the given string literal.
static Source.Blob	blob(URL url) Create a source of binary data that reads from the given URL.
Source	encoding(String characterEncoding) Set an encoding that indicates how the supplied bytes should be converted to characters or vice-versa.
static Source.XML	xml(byte[] bytes) Create a source of XML data from the given byte array.
static Source.XML	xml(File file) Create a source that reads an XML document from an external file.
static Source.XML	xml(InputStream stream) Create a source of XML data that reads from the given input stream.
static Source.XML	xml(Reader reader) Create a source of XML data that reads from the given reader.
static Source.XML	xml(String literal) Create a source of XML data from the given string literal.
static Source.XML	xml(URL url) Create a source of XML that reads from the given URL.

Methods inherited from class java.lang.Object

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

Method Detail

encoding

public Source encoding(String characterEncoding)

Set an encoding that indicates how the supplied bytes should be converted to characters or vice-versa. Whether and how the encoding is used depends on the source. If the encoding is needed but has not been set, the system will make a best guess or default to UTF-8 as appropriate.

Parameters:

characterEncoding - the character encoding to use when dealing with this source

Returns:

this source

xml

public static Source.XML xml(File file)

Create a source that reads an XML document from an external file.

Parameters:

file - the XML file

Returns:

a source that reads XML from the file

blob

public static Source.Blob blob(File file)

Create a source that reads a binary document from an external file.

Parameters:

file - the binary file

Returns:

a source that reads binary from the file

xml

public static Source.XML xml(InputStream stream)

Create a source of XML data that reads from the given input stream. Note that the contents of the stream will need to be read twice, so if the stream is transient (i.e., its contents are not available for random access, such as for a socket input stream) its contents will be automatically saved in memory. This could be very inefficient if the document being streamed is large.

Parameters:

stream - the input stream to read the XML from

Returns:

a source that reads from the given input stream

blob

public static Source.Blob blob(InputStream stream)

Create a source of binary data that reads from the given input stream. At this time, eXist doesn't support streaming into the database, so the contents of the stream will be read entirely into memory before being persisted.

Parameters:

stream - the binary stream to read from

Returns:

a source that reads from the given input stream

xml

public static Source.XML xml(Reader reader)

Create a source of XML data that reads from the given reader. Note that the contents of the reader will need to be read twice, so its contents will be automatically saved in memory. This could be very inefficient if the document being streamed is large.

Parameters:

reader - the reader to read the XML from

Returns:

a source that reads from the given reader

blob

public static Source.Blob blob(Reader reader)

Create a source of binary data that reads from the given reader. The characters will be converted into bytes by using the encoding specified for this source, or UTF-8 by default. At this time, eXist doesn't support streaming into the database, so the contents of the reader will be read entirely into memory before being persisted.

Parameters:

reader - the reader to read from

Returns:

a source that reads from the given reader

xml

public static Source.XML xml(byte[] bytes)

Create a source of XML data from the given byte array. If this source specifies an encoding, it will be used to decode the characters, otherwise the encoding will be guessed using standard XML parsing techniques.

Parameters:

bytes - the source bytes

Returns:

a source that reads XML from the given byte array

blob

public static Source.Blob blob(byte[] bytes)

Create a source of binary data from the given byte array. The bytes will be stored in the database verbatim.

Parameters:

bytes - the source bytes

Returns:

a source that reads binary data from the given byte array

xml

public static Source.XML xml(String literal)

Create a source of XML data from the given string literal. The string should contain an XML document, not a filename or URI.

Parameters:

literal - the contents of an XML document

Returns:

a source that reads XML from the given literal string

blob

public static Source.Blob blob(String literal)

Create a source of binary data from the given string literal. The string should contain the actual data, not a filename or URI. The string's characters will be converted into bytes by using the encoding specified for this source, or UTF-8 by default.

Parameters:

literal - the contents of the document

Returns:

a source that reads binary data from the given literal string

xml

public static Source.XML xml(URL url)
                      throws URISyntaxException

Create a source of XML that reads from the given URL. Note that the URL's contents will have to be retrieved twice, so if the connection is slow or expensive it might be worthwhile to cache them and use a different (local) source constructor.

Parameters:

url - the URL to read XML from

Returns:

a source that reads XML from the given URL

Throws:

URISyntaxException - if the URL syntax is not strictly spec-compliant

blob

public static Source.Blob blob(URL url)

Create a source of binary data that reads from the given URL.

Parameters:

url - the URL to read binary data from

Returns:

a source that reads binary data from the given URL