software.amazon.ion

Interface IonSystem

All Superinterfaces:

ValueFactory

public interface IonSystem
extends ValueFactory

Entry point to all things Ion.

WARNING: This interface should not be implemented or extended by code outside of this library.

In general, IonValue instances returned from one system instance are not interoperable with those returned by other instances. The intended usage pattern is for an application to construct a single IonSystem instance and use it throughout, rather than constructing multiple systems and intermingling their use. To create a copy of a value for use by a different system, use ValueFactory.clone(IonValue).

To create an IonSystem, see IonSystemBuilder.

Implementations of this interface are safe for use by multiple threads.

See Also:

IonSystemBuilder

Method Summary

Modifier and Type	Method and Description
IonCatalog	getCatalog() Gets the catalog used by this system.
IonLoader	getLoader() Gets the default system loader.
SymbolTable	getSystemSymbolTable() Gets the default system symbol table.
SymbolTable	getSystemSymbolTable(String ionVersionId) Gets a system symbol table for a specific version of Ion.
Iterator<IonValue>	iterate(byte[] ionData) Creates an iterator over Ion data.
Iterator<IonValue>	iterate(InputStream ionData) Creates an iterator over a stream of Ion data, detecting whether it's text or binary data.
Iterator<IonValue>	iterate(Reader ionText) Creates an iterator over a stream of Ion text data.
Iterator<IonValue>	iterate(String ionText) Creates an iterator over a string containing Ion text data.
IonWriter	newBinaryWriter(OutputStream out, SymbolTable... imports) Creates a new writer that will encode binary Ion data, using the given shared symbol tables as imports.
IonTimestamp	newCurrentUtcTimestamp() Constructs a new UTC timestamp instance initialized so that it represents the time at which it was allocated, measured to the nearest millisecond.
IonDatagram	newDatagram() Creates a new empty datagram.
IonDatagram	newDatagram(IonValue initialChild) Creates a new datagram containing one value.
IonDatagram	newDatagram(SymbolTable... imports) Creates a new datagram, bootstrapped with imported symbol tables.
IonLoader	newLoader() Constructs a new loader instance using the default system catalog.
IonLoader	newLoader(IonCatalog catalog) Constructs a new loader instance using the given catalog.
SymbolTable	newLocalSymbolTable(SymbolTable... imports) Creates a new local symbol table based on specific imported tables.
IonReader	newReader(byte[] ionData) Creates an new IonReader instance over a block of Ion data, detecting whether it's text or binary data.
IonReader	newReader(byte[] ionData, int offset, int len) Creates an new IonReader instance over a block of Ion data, detecting whether it's text or binary data.
IonReader	newReader(InputStream ionData) Creates a new IonReader instance over a stream of Ion data, detecting whether it's text or binary data.
IonReader	newReader(IonValue value) Creates an new IonReader instance over an IonValue data model.
IonReader	newReader(Reader ionText) Creates an new IonReader instance over Ion text data.
IonReader	newReader(String ionText) Creates an new IonReader instance over Ion text data.
SymbolTable	newSharedSymbolTable(IonReader reader) Materializes a shared symbol table from its serialized form.
SymbolTable	newSharedSymbolTable(IonReader reader, boolean alreadyOnStruct) Materializes a shared symbol table from its serialized form.
SymbolTable	newSharedSymbolTable(String name, int version, Iterator<String> newSymbols, SymbolTable... imports) Creates a new shared symbol table containing a given set of symbols.
IonWriter	newTextWriter(Appendable out) Creates a new writer that will write text to the given output stream.
IonWriter	newTextWriter(Appendable out, SymbolTable... imports) Creates a new writer that will write text to the given output stream, using the given shared symbol tables as imports.
IonWriter	newTextWriter(OutputStream out) Creates a new writer that will write UTF-8 text to the given output stream.
IonWriter	newTextWriter(OutputStream out, SymbolTable... imports) Creates a new writer that will write UTF-8 text to the given output stream, using the given shared symbol tables as imports.
IonTimestamp	newUtcTimestamp(Date utcDate) Constructs a new UTC timestamp instance initialized so that it represents the given time.
IonTimestamp	newUtcTimestampFromMillis(long millis) Constructs a new UTC timestamp initialized to represent the specified number of milliseconds since the standard base time known as "the epoch", namely 1970-01-01T00:00:00Z.
IonValue	newValue(IonReader reader) Extracts the current value from a reader into an IonValue.
IonWriter	newWriter(IonContainer container) Creates a new writer that will add IonValues to the given container.
IonValue	singleValue(byte[] ionData) Extracts a single value from Ion text or binary data.
IonValue	singleValue(String ionText) Extracts a single value from Ion text data.

Methods inherited from interface software.amazon.ion.ValueFactory

clone, newBlob, newBlob, newBool, newBool, newClob, newClob, newDecimal, newDecimal, newDecimal, newDecimal, newEmptyList, newEmptySexp, newEmptyStruct, newFloat, newFloat, newInt, newInt, newInt, newList, newList, newList, newList, newNull, newNull, newNullBlob, newNullBool, newNullClob, newNullDecimal, newNullFloat, newNullInt, newNullList, newNullSexp, newNullString, newNullStruct, newNullSymbol, newNullTimestamp, newSexp, newSexp, newSexp, newSexp, newString, newSymbol, newSymbol, newTimestamp

Method Detail

getSystemSymbolTable

SymbolTable getSystemSymbolTable()

Gets the default system symbol table.

Returns:

not null.

getSystemSymbolTable

SymbolTable getSystemSymbolTable(String ionVersionId)
                          throws UnsupportedIonVersionException

Gets a system symbol table for a specific version of Ion.

Parameters:

ionVersionId - must be of the form "$ion_X_Y".

Returns:

the requested system table.

Throws:

UnsupportedIonVersionException - if the requested version of Ion is not supported by this implementation.

getCatalog

IonCatalog getCatalog()

Gets the catalog used by this system. Unless otherwise noted, all objects derived from this system will use this catalog.

Returns:

this system's default catalog; not null.

newLocalSymbolTable

SymbolTable newLocalSymbolTable(SymbolTable... imports)

Creates a new local symbol table based on specific imported tables. If the first imported table is a system table, then the local table will use it appropriately. Otherwise, the local table will use this system's default system symbol table.

Parameters:

imports - the set of shared symbol tables to import. The first (and only the first) may be a system table.

Returns:

a new local symbol table.

Throws:

IllegalArgumentException - if any import is a local table, or if any but the first is a system table.

NullPointerException - if any import is null.

newSharedSymbolTable

SymbolTable newSharedSymbolTable(String name,
                                 int version,
                                 Iterator<String> newSymbols,
                                 SymbolTable... imports)

Creates a new shared symbol table containing a given set of symbols. The table will contain symbols in the following order:

1. If version is larger than 1, the prior version of the named table is retrieved from the catalog and all of its symbols are added.
2. For each non-system table in imports, add all of its declared symbols.
3. Add all of the symbols provided by newSymbols.

Any duplicate symbol texts or null strings are ignored.

This method is intended for use by utilities that are defining new symbol tables for use by applications. The result will typically be added to an IonCatalog which is responsible for persistence. Shared symbol tables are serialized via SymbolTable.writeTo(IonWriter) and materialized via newSharedSymbolTable(IonReader).

Parameters:

name - the symbol table name, a non-empty string.

version - at least one.

newSymbols - provides symbol names; may be null.

imports - other tables from which to import symbols.

Returns:

a new shared symbol table with the given name and version.

Throws:

IonException - if version > 1 and the prior version does not exist in this system's catalog.

newSharedSymbolTable

SymbolTable newSharedSymbolTable(IonReader reader)

Materializes a shared symbol table from its serialized form. This method expects the reader to be positioned before the struct. Which is to say the reader's next() method has not been called to position the reader on the symbol table struct.

Parameters:

reader - must not be null.

Returns:

a new symbol table instance.

newSharedSymbolTable

SymbolTable newSharedSymbolTable(IonReader reader,
                                 boolean alreadyOnStruct)

Materializes a shared symbol table from its serialized form.

Parameters:

reader - must not be null.

alreadyOnStruct - is true if the caller has aleady next-ed onto the struct, false if a next call is needed

Returns:

a new symbol table instance.

newLoader

IonLoader newLoader()

Constructs a new loader instance using the default system catalog.

newLoader

IonLoader newLoader(IonCatalog catalog)

Constructs a new loader instance using the given catalog.

Parameters:

catalog - may be null, in which case the loader will use the default system catalog.

See Also:

newLoader()

getLoader

IonLoader getLoader()

Gets the default system loader. Applications may replace this loader with one configured appropriately, and then access it here.

Returns:

not null.

iterate

Iterator<IonValue> iterate(Reader ionText)

Creates an iterator over a stream of Ion text data. Values returned by the iterator have no container.

The iterator will automatically consume Ion system IDs and local symbol tables; they will not be returned by the iterator.

If the input source throws an IOException during iteration, it will be wrapped in an IonException. See documentation there for tips on how to recover the cause.

This method is suitable for use over unbounded streams with a reasonable schema.

Applications should generally use iterate(InputStream) whenever possible, since this library has much faster UTF-8 decoding than the Java IO framework.

Because this library performs its own buffering, it's recommended that you avoid adding additional buffering to the given stream.

Parameters:

ionText - a stream of Ion text data. The caller is responsible for closing the Reader after iteration is complete.

Returns:

a new iterator instance.

Throws:

NullPointerException - if ionText is null.

IonException - if the source throws IOException.

iterate

Iterator<IonValue> iterate(InputStream ionData)

Creates an iterator over a stream of Ion data, detecting whether it's text or binary data. Values returned by the iterator have no container.

The iterator will automatically consume Ion system IDs and local symbol tables; they will not be returned by the iterator.

If the input source throws an IOException during iteration, it will be wrapped in an IonException. See documentation there for tips on how to recover the cause.

This method is suitable for use over unbounded streams with a reasonable schema.

This method will auto-detect and uncompress GZIPped Ion data.

Because this library performs its own buffering, it's recommended that you avoid adding additional buffering to the given stream.

Parameters:

ionData - a stream of Ion data. The caller is responsible for closing the InputStream after iteration is complete.

Returns:

a new iterator instance.

Throws:

NullPointerException - if ionData is null.

IonException - if the source throws IOException.

iterate

Iterator<IonValue> iterate(String ionText)

Creates an iterator over a string containing Ion text data. Values returned by the iterator have no container.

The iterator will automatically consume Ion system IDs and local symbol tables; they will not be returned by the iterator.

Parameters:

ionText - must not be null.

Returns:

a new iterator instance.

Throws:

NullPointerException - if ionText is null.

iterate

Iterator<IonValue> iterate(byte[] ionData)

Creates an iterator over Ion data. Values returned by the iterator have no container.

The iterator will automatically consume Ion system IDs and local symbol tables; they will not be returned by the iterator.

This method will auto-detect and uncompress GZIPped Ion data.

Parameters:

ionData - may be either Ion binary data or (UTF-8) Ion text, or GZIPped Ion data. This method assumes ownership of the array and may modify it at will.

Returns:

a new iterator instance.

Throws:

NullPointerException - if ionData is null.

singleValue

IonValue singleValue(String ionText)

Extracts a single value from Ion text data.

Parameters:

ionText - must not be null.

Returns:

the first (and only) user value in the data; not null.

Throws:

NullPointerException - if ionText is null.

UnexpectedEofException - if the data doesn't contain any user values.

IonException - if the data does not contain exactly one user value.

singleValue

IonValue singleValue(byte[] ionData)

Extracts a single value from Ion text or binary data.

This method will auto-detect and uncompress GZIPped Ion data.

Parameters:

ionData - may be either Ion binary data or (UTF-8) Ion text, or GZIPped Ion data. This method assumes ownership of the array and may modify it at will.

Returns:

the first (and only) user value in the data; not null.

Throws:

NullPointerException - if ionData is null.

UnexpectedEofException - if the data doesn't contain any user values.

IonException - if the data does not contain exactly one user value.

newReader

IonReader newReader(String ionText)

Creates an new IonReader instance over Ion text data.

The text is parsed incrementally by the reader, so any syntax errors will not be detected during this call.

Parameters:

ionText - must not be null.

newReader

IonReader newReader(byte[] ionData)

Creates an new IonReader instance over a block of Ion data, detecting whether it's text or binary data.

This method will auto-detect and uncompress GZIPped Ion data.

Parameters:

ionData - may be either Ion binary data, or UTF-8 Ion text. The reader retains a reference to the array, so its data must not be modified while the reader is active.

newReader

IonReader newReader(byte[] ionData,
                    int offset,
                    int len)

Creates an new IonReader instance over a block of Ion data, detecting whether it's text or binary data.

This method will auto-detect and uncompress GZIPped Ion data.

Parameters:

ionData - is used only within the range of bytes starting at offset for len bytes. The data in that range may be either Ion binary data, or UTF-8 Ion text. The reader retains a reference to the array, so its data must not be modified while the reader is active.

offset - must be non-negative and less than ionData.length.

len - must be non-negative and offset+len must not exceed ionData.length.

newReader

IonReader newReader(InputStream ionData)

Creates a new IonReader instance over a stream of Ion data, detecting whether it's text or binary data.

This method will auto-detect and uncompress GZIPped Ion data.

Because this library performs its own buffering, it's recommended that you avoid adding additional buffering to the given stream.

Parameters:

ionData - must not be null.

Returns:

a new reader instance. Callers must call Closeable.close() when finished with it.

Throws:

IonException - if the source throws IOException.

newReader

IonReader newReader(Reader ionText)

Creates an new IonReader instance over Ion text data.

Applications should generally us newReader(InputStream) whenever possible, since this library has much faster UTF-8 decoding than the Java IO framework.

Because this library performs its own buffering, it's recommended that you avoid adding additional buffering to the given stream.

Throws:

IonException - if the source throws IOException.

newReader

IonReader newReader(IonValue value)

Creates an new IonReader instance over an IonValue data model. Typically this is used to iterate over a collection, such as an IonStruct.

Parameters:

value - must not be null.

newWriter

IonWriter newWriter(IonContainer container)

Creates a new writer that will add IonValues to the given container.

Parameters:

container - a container that will receive new children from the the returned writer. Must not be null.

Returns:

a new IonWriter instance; not null.

newTextWriter

IonWriter newTextWriter(OutputStream out)

Creates a new writer that will write UTF-8 text to the given output stream.

Parameters:

out - the stream that will receive UTF-8 Ion text data. Must not be null.

Returns:

a new IonWriter instance; not null.

See Also:

IonTextWriterBuilder

newTextWriter

IonWriter newTextWriter(Appendable out)

Creates a new writer that will write text to the given output stream.

Parameters:

out - the stream that will receive Ion text data. Must not be null.

Returns:

a new IonWriter instance; not null.

See Also:

IonTextWriterBuilder

newTextWriter

IonWriter newTextWriter(OutputStream out,
                        SymbolTable... imports)
                 throws IOException

Creates a new writer that will write UTF-8 text to the given output stream, using the given shared symbol tables as imports.

The output stream will start with an Ion Version Marker and a local symbol table that uses the given imports.

Parameters:

out - the stream that will receive UTF-8 Ion text data. Must not be null.

imports - a sequence of shared symbol tables

Returns:

a new IonWriter instance; not null.

Throws:

IOException - if its thrown by the output stream.

See Also:

IonTextWriterBuilder

newTextWriter

IonWriter newTextWriter(Appendable out,
                        SymbolTable... imports)
                 throws IOException

Creates a new writer that will write text to the given output stream, using the given shared symbol tables as imports.

The output stream will start with an Ion Version Marker and a local symbol table that uses the given imports.

Parameters:

out - the stream that will receive Ion text data. Must not be null.

imports - a sequence of shared symbol tables. The first (and only the first) may be a system table.

Returns:

a new IonWriter instance; not null.

Throws:

IOException - if its thrown by the output stream.

See Also:

IonTextWriterBuilder

newBinaryWriter

IonWriter newBinaryWriter(OutputStream out,
                          SymbolTable... imports)

Creates a new writer that will encode binary Ion data, using the given shared symbol tables as imports.

The output stream will start with an Ion Version Marker and a local symbol table that uses the given imports.

Parameters:

out - the stream to receive binary Ion data; not null.

imports - a sequence of shared symbol tables to import. The first (and only the first) may be a system table.

Returns:

a new IonWriter instance; not null.

Throws:

IllegalArgumentException - if any import is a local table, or if any but the first is a system table.

NullPointerException - if any import is null.

newDatagram

IonDatagram newDatagram()

Creates a new empty datagram.

Returns:

a new datagram with no user values.

newDatagram

IonDatagram newDatagram(IonValue initialChild)

Creates a new datagram containing one value. If the given value is contained elsewhere, it is cloned before insertion.

Parameters:

initialChild - becomes the first and only (user) value in the datagram. The child's system must be this system. If null, then the returned datagram will have no user values.

Returns:

a new datagram.

Throws:

IllegalArgumentException - if initialChild is an IonDatagram.

newDatagram

IonDatagram newDatagram(SymbolTable... imports)

Creates a new datagram, bootstrapped with imported symbol tables. Generally an application will use this to acquire a datagram, then adds values to it, then calls IonDatagram.getBytes() (or similar) to extract binary data.

Parameters:

imports - the set of shared symbol tables to import. The first (and only the first) may be a system table.

Returns:

a new datagram with no user values.

Throws:

IllegalArgumentException - if any import is a local table, or if any but the first is a system table.

See Also:

newLocalSymbolTable(SymbolTable...)

newValue

IonValue newValue(IonReader reader)

Extracts the current value from a reader into an IonValue. The caller must position the reader on the correct value by calling IonReader.next() beforehand.

Returns:

a new value object, not null.

newUtcTimestampFromMillis

IonTimestamp newUtcTimestampFromMillis(long millis)

Constructs a new UTC timestamp initialized to represent the specified number of milliseconds since the standard base time known as "the epoch", namely 1970-01-01T00:00:00Z.

Parameters:

millis - the milliseconds since 1970-01-01T00:00:00Z.

newUtcTimestamp

IonTimestamp newUtcTimestamp(Date utcDate)

Constructs a new UTC timestamp instance initialized so that it represents the given time. As per Date class, this will have millisecond precision.

This is equivalent to newUtcTimestampFromMillis(utcDate.getTime()).

Parameters:

utcDate - the time of the new instance; may be null to make null.timestamp.

newCurrentUtcTimestamp

IonTimestamp newCurrentUtcTimestamp()

Constructs a new UTC timestamp instance initialized so that it represents the time at which it was allocated, measured to the nearest millisecond.