Ion Java 1.11.10 · com.amazon.ion.IonSystem · APIdia, the JavaDoc alternative

Method Summary

Modifier and Type	Method and Description
public IonCatalog	Returns: this system's default catalog; not null. getCatalog() Gets the catalog used by this system.
public IonLoader	Returns: not `null`. getLoader() Gets the default system loader.
public SymbolTable	Returns: not null. getSystemSymbolTable() Gets the default system symbol table.
public SymbolTable	Returns: the requested system table. getSystemSymbolTable(String must be of the form `"$ion_X_Y"`. ionVersionId) Gets a system symbol table for a specific version of Ion.
public Iterator<IonValue>	Returns: a new iterator instance. iterate(Reader a stream of Ion text data. The caller is responsible for closing the Reader after iteration is complete. ionText) Creates an iterator over a stream of Ion text data.
public Iterator<IonValue>	Returns: a new iterator instance. iterate(InputStream a stream of Ion data. The caller is responsible for closing the InputStream after iteration is complete. ionData) Deprecated Will cause a memory leak when reading a gzipped stream. Use `IonSystem#iterate(IonReader)` instead. Warning Will cause a memory leak when reading a gzipped stream, use `IonSystem#iterate(IonReader)` instead.
public Iterator<IonValue>	Returns: a new iterator instance. iterate(String must not be null. ionText) Creates an iterator over a string containing Ion text data.
public Iterator<IonValue>	Returns: a new iterator instance. iterate(byte[] 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. ionData) Deprecated Will cause a memory leak when reading a gzipped byte[]. Use `IonSystem#iterate(IonReader)` instead. Warning Will cause a memory leak when reading a gzipped byte[], use `IonSystem#iterate(IonReader)` instead.
public Iterator<IonValue>	Returns: a new iterator instance. iterate(IonReader source of the Ion data to iterate over. reader) Creates an iterator over Ion data.
public IonWriter	Returns: a new `IonWriter` instance; not null. newBinaryWriter(OutputStream the stream to receive binary Ion data; not null. out, SymbolTable... a sequence of shared symbol tables to import. The first (and only the first) may be a system table. imports) Creates a new writer that will encode binary Ion data, using the given shared symbol tables as imports.
public IonBinaryWriter	Returns: a new `IonBinaryWriter` instance; not `null`. newBinaryWriter() Deprecated Use `newBinaryWriter(OutputStream, SymbolTable...)` instead. Creates a new writer that will encode binary Ion data.
public IonBinaryWriter	Returns: a new `IonBinaryWriter` instance; not `null`. newBinaryWriter(SymbolTable... a sequence of shared symbol tables imports) Deprecated Use `newBinaryWriter(OutputStream, SymbolTable...)` instead. Creates a new writer that will encode binary Ion data, using the given shared symbol tables as imports.
public 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.
public IonDatagram	Returns: a new datagram with no user values. newDatagram() Creates a new empty datagram.
public IonDatagram	Returns: a new datagram. newDatagram(IonValue 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. initialChild) Creates a new datagram containing one value.
public IonDatagram	Returns: a new datagram with no user values. newDatagram(SymbolTable... the set of shared symbol tables to import. The first (and only the first) may be a system table. imports) Creates a new datagram, bootstrapped with imported symbol tables.
public IonLoader	newLoader() Constructs a new loader instance using the default system catalog.
public IonLoader	newLoader(IonCatalog may be null, in which case the loader will use the default system catalog. catalog) Constructs a new loader instance using the given catalog.
public SymbolTable	Returns: a new local symbol table. newLocalSymbolTable(SymbolTable... the set of shared symbol tables to import. The first (and only the first) may be a system table. imports) Creates a new local symbol table based on specific imported tables.
public IonTextReader	newReader(String must not be null. ionText) References Deprecated `IonTextReader` is deprecated or references (maybe indirectly) at least one deprecated element. Creates an new `IonReader` instance over Ion text data.
public IonReader	newReader(byte[] 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. ionData) Creates an new `IonReader` instance over a block of Ion data, detecting whether it's text or binary data.
public IonReader	newReader(byte[] 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. ionData, int must be non-negative and less than `ionData.length`. offset, int must be non-negative and `offset+len` must not exceed `ionData.length`. len) Creates an new `IonReader` instance over a block of Ion data, detecting whether it's text or binary data.
public IonReader	Returns: a new reader instance. Callers must call `IonReader#close()` when finished with it. newReader(InputStream must not be null. ionData) Creates a new `IonReader` instance over a stream of Ion data, detecting whether it's text or binary data.
public IonReader	newReader(Reader ionText) Creates an new `IonReader` instance over Ion text data.
public IonReader	newReader(IonValue must not be null. value) Creates an new `IonReader` instance over an `IonValue` data model.
public SymbolTable	Returns: a new shared symbol table with the given name and version. newSharedSymbolTable(String the symbol table name, a non-empty string. name, int at least one. version, Iterator<String> provides symbol names; may be null. newSymbols, SymbolTable... other tables from which to import symbols. imports) Creates a new shared symbol table containing a given set of symbols.
public SymbolTable	Returns: a new symbol table instance. newSharedSymbolTable(IonReader must not be null. reader) Materializes a shared symbol table from its serialized form.
public SymbolTable	Returns: a new symbol table instance. newSharedSymbolTable(IonReader must not be null. reader, boolean is true if the caller has aleady next-ed onto the struct, false if a next call is needed alreadyOnStruct) Materializes a shared symbol table from its serialized form.
public IonWriter	Returns: a new `IonWriter` instance; not `null`. newTextWriter(OutputStream the stream that will receive UTF-8 Ion text data. Must not be null. out) Creates a new writer that will write UTF-8 text to the given output stream.
public IonWriter	Returns: a new `IonWriter` instance; not `null`. newTextWriter(Appendable the stream that will receive Ion text data. Must not be null. out) Creates a new writer that will write text to the given output stream.
public IonWriter	Returns: a new `IonWriter` instance; not `null`. newTextWriter(OutputStream the stream that will receive UTF-8 Ion text data. Must not be null. out, SymbolTable... a sequence of shared symbol tables imports) Creates a new writer that will write UTF-8 text to the given output stream, using the given shared symbol tables as imports.
public IonWriter	Returns: a new `IonWriter` instance; not `null`. newTextWriter(Appendable the stream that will receive Ion text data. Must not be null. out, SymbolTable... a sequence of shared symbol tables. The first (and only the first) may be a system table. imports) Creates a new writer that will write text to the given output stream, using the given shared symbol tables as imports.
public IonTimestamp	newUtcTimestamp(Date the time of the new instance; may be `null` to make `null.timestamp`. utcDate) Constructs a new UTC `timestamp` instance initialized so that it represents the given time.
public IonTimestamp	newUtcTimestampFromMillis(long the milliseconds since 1970-01-01T00:00:00Z. 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.
public IonValue	Returns: a new value object, not null. newValue(IonReader reader) Extracts the current value from a reader into an `IonValue`.
public IonWriter	Returns: a new `IonWriter` instance; not `null`. newWriter(IonContainer a container that will receive new children from the the returned writer. Must not be null. container) Creates a new writer that will add `IonValue`s to the given container.
public IonValue	Returns: the first (and only) user value in the data; not null. singleValue(String must not be null. ionText) Extracts a single value from Ion text data.
public IonValue	Returns: the first (and only) user value in the data; not null. singleValue(byte[] 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. ionData) Extracts a single value from Ion text or binary data.
public IonValue	Returns: the first (and only) user value in the data; not null. singleValue(byte[] 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. ionData, int must be non-negative and less than `ionData.length`. offset, int must be non-negative and `offset+len` must not exceed len) Extracts a single value from Ion text or binary data.

Method Detail

getCatalog	back to summary
public IonCatalog getCatalog() Gets the catalog used by this system. Unless otherwise noted, all objects derived from this system will use this catalog. Returns:IonCatalog this system's default catalog; not null.

getCatalog

back to summary

public IonCatalog getCatalog()

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

Returns:IonCatalog: this system's default catalog; not null.

getLoader back to summary

getLoader	back to summary
public IonLoader getLoader() Gets the default system loader. Applications may replace this loader with one configured appropriately, and then access it here. Returns:IonLoader not `null`.

public IonLoader getLoader()

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

Returns:IonLoader: not null.

getSystemSymbolTable	back to summary
public SymbolTable getSystemSymbolTable() Gets the default system symbol table. Returns:SymbolTable not null.

getSystemSymbolTable

back to summary

public SymbolTable getSystemSymbolTable()

Gets the default system symbol table.

Returns:SymbolTable: not null.

getSystemSymbolTable back to summary

getSystemSymbolTable	back to summary
public SymbolTable getSystemSymbolTable(String ionVersionId) throws UnsupportedIonVersionException Gets a system symbol table for a specific version of Ion. Parameters ionVersionId:String must be of the form `"$ion_X_Y"`. Returns:SymbolTable the requested system table. Exceptions UnsupportedIonVersionException: if the requested version of Ion is not supported by this implementation.

public SymbolTable getSystemSymbolTable(String ionVersionId) throws UnsupportedIonVersionException

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

Parameters

ionVersionId:String: must be of the form "$ion_X_Y".

Returns:SymbolTable

the requested system table.

Exceptions

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

iterate back to summary

iterate	back to summary
public 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 Unicode 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:Reader a stream of Ion text data. The caller is responsible for closing the Reader after iteration is complete. Returns:Iterator<IonValue> a new iterator instance. Exceptions NullPointerException: if `ionText` is null. IonException: if the source throws `IOException`.

public 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 Unicode 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:Reader: a stream of Ion text data. The caller is responsible for closing the Reader after iteration is complete.

Returns:Iterator<IonValue>

a new iterator instance.

Exceptions

NullPointerException:: if ionText is null.
IonException:: if the source throws IOException.

iterate back to summary

iterate	back to summary
public Iterator<IonValue> iterate(InputStream ionData) Deprecated Will cause a memory leak when reading a gzipped stream. Use `IonSystem#iterate(IonReader)` instead. Warning Will cause a memory leak when reading a gzipped stream, use `IonSystem#iterate(IonReader)` instead. 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:InputStream a stream of Ion data. The caller is responsible for closing the InputStream after iteration is complete. Returns:Iterator<IonValue> a new iterator instance. Annotations @Deprecated Exceptions NullPointerException: if `ionData` is null. IonException: if the source throws `IOException`.

public Iterator<IonValue> iterate(InputStream ionData)

Deprecated

Will cause a memory leak when reading a gzipped stream. Use IonSystem#iterate(IonReader) instead.

Warning

Will cause a memory leak when reading a gzipped stream, use IonSystem#iterate(IonReader) instead.

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:InputStream: a stream of Ion data. The caller is responsible for closing the InputStream after iteration is complete.

Returns:Iterator<IonValue>

a new iterator instance.

Annotations

@Deprecated

Exceptions

NullPointerException:: if ionData is null.
IonException:: if the source throws IOException.

iterate back to summary

iterate	back to summary
public 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:String must not be null. Returns:Iterator<IonValue> a new iterator instance. Exceptions NullPointerException: if `ionText` is null.

public 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:String: must not be null.

Returns:Iterator<IonValue>

a new iterator instance.

Exceptions

NullPointerException:: if ionText is null.

iterate back to summary

iterate	back to summary
public Iterator<IonValue> iterate(byte[] ionData) Deprecated Will cause a memory leak when reading a gzipped byte[]. Use `IonSystem#iterate(IonReader)` instead. Warning Will cause a memory leak when reading a gzipped byte[], use `IonSystem#iterate(IonReader)` instead. 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:byte[] 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:Iterator<IonValue> a new iterator instance. Annotations @Deprecated Exceptions NullPointerException: if `ionData` is null.

public Iterator<IonValue> iterate(byte[] ionData)

Deprecated

Will cause a memory leak when reading a gzipped byte[]. Use IonSystem#iterate(IonReader) instead.

Warning

Will cause a memory leak when reading a gzipped byte[], use IonSystem#iterate(IonReader) instead.

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:byte[]: 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:Iterator<IonValue>

a new iterator instance.

Annotations

@Deprecated

Exceptions

NullPointerException:: if ionData is null.

iterate back to summary

iterate	back to summary
public Iterator<IonValue> iterate(IonReader reader) 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. Parameters reader:IonReader source of the Ion data to iterate over. Returns:Iterator<IonValue> a new iterator instance. Exceptions NullPointerException: if `reader` is null.

public Iterator<IonValue> iterate(IonReader reader)

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.

Parameters

reader:IonReader: source of the Ion data to iterate over.

Returns:Iterator<IonValue>

a new iterator instance.

Exceptions

NullPointerException:: if reader is null.

newBinaryWriter back to summary

newBinaryWriter	back to summary
public 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:OutputStream the stream to receive binary Ion data; not null. imports:SymbolTable[] a sequence of shared symbol tables to import. The first (and only the first) may be a system table. Returns:IonWriter a new `IonWriter` instance; not null. Exceptions IllegalArgumentException: if any import is a local table, or if any but the first is a system table. NullPointerException: if any import is null.

public 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:OutputStream: the stream to receive binary Ion data; not null.
imports:SymbolTable[]: a sequence of shared symbol tables to import. The first (and only the first) may be a system table.

Returns:IonWriter

a new IonWriter instance; not null.

Exceptions

IllegalArgumentException:: if any import is a local table, or if any but the first is a system table.
NullPointerException:: if any import is null.

newBinaryWriter back to summary

newBinaryWriter	back to summary
public IonBinaryWriter newBinaryWriter() Deprecated Use `newBinaryWriter(OutputStream, SymbolTable...)` instead. Creates a new writer that will encode binary Ion data. Returns:IonBinaryWriter a new `IonBinaryWriter` instance; not `null`. Annotations @Deprecated

public IonBinaryWriter newBinaryWriter()

Deprecated

Use newBinaryWriter(OutputStream, SymbolTable...) instead.

Creates a new writer that will encode binary Ion data.

Returns:IonBinaryWriter

a new IonBinaryWriter instance; not null.

Annotations

@Deprecated

newBinaryWriter back to summary

newBinaryWriter	back to summary
public IonBinaryWriter newBinaryWriter(SymbolTable... imports) Deprecated Use `newBinaryWriter(OutputStream, SymbolTable...)` instead. Creates a new writer that will encode binary Ion data, using the given shared symbol tables as imports. The output stream will be start with an Ion Version Marker and a local symbol table that uses the given `imports`. Parameters imports:SymbolTable[] a sequence of shared symbol tables Returns:IonBinaryWriter a new `IonBinaryWriter` instance; not `null`. Annotations @Deprecated

public IonBinaryWriter newBinaryWriter(SymbolTable... imports)

Deprecated

Use newBinaryWriter(OutputStream, SymbolTable...) instead.

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

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

Parameters

imports:SymbolTable[]: a sequence of shared symbol tables

Returns:IonBinaryWriter

a new IonBinaryWriter instance; not null.

Annotations

@Deprecated

newCurrentUtcTimestamp	back to summary
public 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.

newDatagram	back to summary
public IonDatagram newDatagram() Creates a new empty datagram. Returns:IonDatagram a new datagram with no user values.

newDatagram

back to summary

public IonDatagram newDatagram()

Creates a new empty datagram.

Returns:IonDatagram: a new datagram with no user values.

newDatagram back to summary

newDatagram	back to summary
public 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:IonValue 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:IonDatagram a new datagram. Exceptions IllegalArgumentException: if `initialChild` is an `IonDatagram`.

public 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:IonValue: 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:IonDatagram

a new datagram.

Exceptions

IllegalArgumentException:: if initialChild is an IonDatagram.

newDatagram back to summary

newDatagram	back to summary
public IonDatagram newDatagram(SymbolTable... imports) Creates a new datagram, bootstrapped with imported symbol tables. Generally an application will use this to aquire a datagram, then adds values to it, then calls `IonDatagram#getBytes(byte[])` (or similar) to extract binary data. Parameters imports:SymbolTable[] the set of shared symbol tables to import. The first (and only the first) may be a system table. Returns:IonDatagram a new datagram with no user values. Annotations @SuppressWarnings:javadoc Exceptions IllegalArgumentException: if any import is a local table, or if any but the first is a system table. See Also `newLocalSymbolTable(SymbolTable...)`

public IonDatagram newDatagram(SymbolTable... imports)

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

Parameters

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

Returns:IonDatagram

a new datagram with no user values.

Annotations

@SuppressWarnings:javadoc

Exceptions

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

See Also

newLocalSymbolTable(SymbolTable...)

newLoader	back to summary
public IonLoader newLoader() Constructs a new loader instance using the default system catalog.

newLoader back to summary

newLoader	back to summary
public IonLoader newLoader(IonCatalog catalog) Constructs a new loader instance using the given catalog. Parameters catalog:IonCatalog may be null, in which case the loader will use the default system catalog. See Also `newLoader()`

public IonLoader newLoader(IonCatalog catalog)

Constructs a new loader instance using the given catalog.

Parameters

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

See Also

newLoader()

newLocalSymbolTable	back to summary
public 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:SymbolTable[] the set of shared symbol tables to import. The first (and only the first) may be a system table. Returns:SymbolTable a new local symbol table. Exceptions IllegalArgumentException: if any import is a local table, or if any but the first is a system table. NullPointerException: if any import is null.

newLocalSymbolTable

back to summary

public 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:SymbolTable[]: the set of shared symbol tables to import. The first (and only the first) may be a system table.

Returns:SymbolTable

a new local symbol table.

Exceptions

IllegalArgumentException:: if any import is a local table, or if any but the first is a system table.
NullPointerException:: if any import is null.

newReader back to summary

newReader	back to summary
public IonTextReader newReader(String ionText) References Deprecated `IonTextReader` is deprecated or references (maybe indirectly) at least one deprecated element. See corresponding docs for further information. 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:String must not be null. Annotations @SuppressWarnings:deprecation

public IonTextReader newReader(String ionText)

References Deprecated

IonTextReader is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

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:String: must not be null.

Annotations

@SuppressWarnings:deprecation

newReader back to summary

newReader	back to summary
public 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:byte[] 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.

public 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:byte[]: 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 back to summary

newReader	back to summary
public 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:byte[] 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:int must be non-negative and less than `ionData.length`. len:int must be non-negative and `offset+len` must not exceed `ionData.length`.

public 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:byte[]: 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:int: must be non-negative and less than ionData.length.
len:int: must be non-negative and offset+len must not exceed ionData.length.

newReader back to summary

newReader	back to summary
public 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:InputStream must not be null. Returns:IonReader a new reader instance. Callers must call `IonReader#close()` when finished with it. Exceptions IonException: if the source throws `IOException`.

public 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:InputStream: must not be null.

Returns:IonReader

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

Exceptions

IonException:: if the source throws IOException.

newReader back to summary

newReader	back to summary
public 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 Unicode 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. Exceptions IonException: if the source throws `IOException`.

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

Exceptions

IonException:: if the source throws IOException.

newReader back to summary

newReader	back to summary
public 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`. The given value and its children, if any, must not be modified until after the IonReader constructed by this method is closed. Violating this constraint results in undefined behavior. Parameters value:IonValue must not be null.

public 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. The given value and its children, if any, must not be modified until after the IonReader constructed by this method is closed. Violating this constraint results in undefined behavior.

Parameters

value:IonValue: must not be null.

newSharedSymbolTable back to summary

newSharedSymbolTable	back to summary
public 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: 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. For each non-system table in `imports`, add all of its declared symbols. 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:String the symbol table name, a non-empty string. version:int at least one. newSymbols:Iterator<String> provides symbol names; may be null. imports:SymbolTable[] other tables from which to import symbols. Returns:SymbolTable a new shared symbol table with the given name and version. Exceptions IonException: if `version > 1` and the prior version does not exist in this system's catalog.

public 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:

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.
For each non-system table in imports, add all of its declared symbols.
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:String: the symbol table name, a non-empty string.
version:int: at least one.
newSymbols:Iterator<String>: provides symbol names; may be null.
imports:SymbolTable[]: other tables from which to import symbols.

Returns:SymbolTable

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

Exceptions

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

newSharedSymbolTable	back to summary
public 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:IonReader must not be null. Returns:SymbolTable a new symbol table instance.

newSharedSymbolTable

back to summary

public 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:IonReader: must not be null.

Returns:SymbolTable

a new symbol table instance.

newSharedSymbolTable	back to summary
public SymbolTable newSharedSymbolTable(IonReader reader, boolean alreadyOnStruct) Materializes a shared symbol table from its serialized form. Parameters reader:IonReader must not be null. alreadyOnStruct:boolean is true if the caller has aleady next-ed onto the struct, false if a next call is needed Returns:SymbolTable a new symbol table instance.

newSharedSymbolTable

back to summary

public SymbolTable newSharedSymbolTable(IonReader reader, boolean alreadyOnStruct)

Materializes a shared symbol table from its serialized form.

Parameters

reader:IonReader: must not be null.
alreadyOnStruct:boolean: is true if the caller has aleady next-ed onto the struct, false if a next call is needed

Returns:SymbolTable

a new symbol table instance.

newTextWriter back to summary

newTextWriter	back to summary
public IonWriter newTextWriter(OutputStream out) Creates a new writer that will write UTF-8 text to the given output stream. Parameters out:OutputStream the stream that will receive UTF-8 Ion text data. Must not be null. Returns:IonWriter a new `IonWriter` instance; not `null`. See Also `IonTextWriterBuilder`

public IonWriter newTextWriter(OutputStream out)

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

Parameters

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

Returns:IonWriter

a new IonWriter instance; not null.

See Also

IonTextWriterBuilder

newTextWriter back to summary

newTextWriter	back to summary
public IonWriter newTextWriter(Appendable out) Creates a new writer that will write text to the given output stream. Parameters out:Appendable the stream that will receive Ion text data. Must not be null. Returns:IonWriter a new `IonWriter` instance; not `null`. See Also `IonTextWriterBuilder`

public IonWriter newTextWriter(Appendable out)

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

Parameters

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

Returns:IonWriter

a new IonWriter instance; not null.

See Also

IonTextWriterBuilder

newTextWriter back to summary

newTextWriter	back to summary
public 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:OutputStream the stream that will receive UTF-8 Ion text data. Must not be null. imports:SymbolTable[] a sequence of shared symbol tables Returns:IonWriter a new `IonWriter` instance; not `null`. Exceptions IOException: if its thrown by the output stream. See Also `IonTextWriterBuilder`

public 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:OutputStream: the stream that will receive UTF-8 Ion text data. Must not be null.
imports:SymbolTable[]: a sequence of shared symbol tables

Returns:IonWriter

a new IonWriter instance; not null.

Exceptions

IOException:: if its thrown by the output stream.

See Also

IonTextWriterBuilder

newTextWriter back to summary

newTextWriter	back to summary
public 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:Appendable the stream that will receive Ion text data. Must not be null. imports:SymbolTable[] a sequence of shared symbol tables. The first (and only the first) may be a system table. Returns:IonWriter a new `IonWriter` instance; not `null`. Exceptions IOException: if its thrown by the output stream. See Also `IonTextWriterBuilder`

public 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:Appendable: the stream that will receive Ion text data. Must not be null.
imports:SymbolTable[]: a sequence of shared symbol tables. The first (and only the first) may be a system table.

Returns:IonWriter

a new IonWriter instance; not null.

Exceptions

IOException:: if its thrown by the output stream.

See Also

IonTextWriterBuilder

newUtcTimestamp back to summary

newUtcTimestamp	back to summary
public 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:Date the time of the new instance; may be `null` to make `null.timestamp`.

public 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:Date: the time of the new instance; may be null to make null.timestamp.

newUtcTimestampFromMillis back to summary

newUtcTimestampFromMillis	back to summary
public 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:long the milliseconds since 1970-01-01T00:00:00Z.

public 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:long: the milliseconds since 1970-01-01T00:00:00Z.

newValue back to summary

newValue	back to summary
public 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:IonValue a new value object, not null.

public 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:IonValue: a new value object, not null.

newWriter back to summary

newWriter	back to summary
public IonWriter newWriter(IonContainer container) Creates a new writer that will add `IonValue`s to the given container. Parameters container:IonContainer a container that will receive new children from the the returned writer. Must not be null. Returns:IonWriter a new `IonWriter` instance; not `null`.

public IonWriter newWriter(IonContainer container)

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

Parameters

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

Returns:IonWriter

a new IonWriter instance; not null.

singleValue back to summary

singleValue	back to summary
public IonValue singleValue(String ionText) Extracts a single value from Ion text data. Parameters ionText:String must not be null. Returns:IonValue the first (and only) user value in the data; not null. Exceptions 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.

public IonValue singleValue(String ionText)

Extracts a single value from Ion text data.

Parameters

ionText:String: must not be null.

Returns:IonValue

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

Exceptions

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 back to summary

singleValue	back to summary
public 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:byte[] 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:IonValue the first (and only) user value in the data; not null. Exceptions 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.

public 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:byte[]: 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:IonValue

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

Exceptions

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.

singleValue back to summary

singleValue	back to summary
public IonValue singleValue(byte[] ionData, int offset, int len) Extracts a single value from Ion text or binary data. This method will auto-detect and uncompress GZIPped Ion data. Parameters ionData:byte[] 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. offset:int must be non-negative and less than `ionData.length`. len:int must be non-negative and `offset+len` must not exceed Returns:IonValue the first (and only) user value in the data; not null. Exceptions 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.

public IonValue singleValue(byte[] ionData, int offset, int len)

Extracts a single value from Ion text or binary data.

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

Parameters

ionData:byte[]: 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.
offset:int: must be non-negative and less than ionData.length.
len:int: must be non-negative and offset+len must not exceed

Returns:IonValue

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

Exceptions

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.

public Interface IonSystem

Method Summary

Method Detail