Interface IonSystem
-
- All Superinterfaces:
ValueFactory
- All Known Subinterfaces:
_Private_IonSystem
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 singleIonSystem
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, useValueFactory.clone(IonValue)
.To create an
IonSystem
, seeIonSystemBuilder
.Implementations of this interface are safe for use by multiple threads.
- See Also:
IonSystemBuilder
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method 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(java.lang.String ionVersionId)
Gets a system symbol table for a specific version of Ion.java.util.Iterator<IonValue>
iterate(byte[] ionData)
Deprecated.Will cause a memory leak when reading a gzipped byte[].java.util.Iterator<IonValue>
iterate(IonReader reader)
Creates an iterator over Ion data.java.util.Iterator<IonValue>
iterate(java.io.InputStream ionData)
Deprecated.Will cause a memory leak when reading a gzipped stream.java.util.Iterator<IonValue>
iterate(java.io.Reader ionText)
Creates an iterator over a stream of Ion text data.java.util.Iterator<IonValue>
iterate(java.lang.String ionText)
Creates an iterator over a string containing Ion text data.IonBinaryWriter
newBinaryWriter()
Deprecated.UseĀnewBinaryWriter(OutputStream, SymbolTable...)
instead.IonBinaryWriter
newBinaryWriter(SymbolTable... imports)
Deprecated.UsenewBinaryWriter(OutputStream, SymbolTable...)
instead.IonWriter
newBinaryWriter(java.io.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 UTCtimestamp
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 newIonReader
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 newIonReader
instance over a block of Ion data, detecting whether it's text or binary data.IonReader
newReader(IonValue value)
IonReader
newReader(java.io.InputStream ionData)
Creates a newIonReader
instance over a stream of Ion data, detecting whether it's text or binary data.IonReader
newReader(java.io.Reader ionText)
Creates an newIonReader
instance over Ion text data.IonTextReader
newReader(java.lang.String ionText)
Creates an newIonReader
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(java.lang.String name, int version, java.util.Iterator<java.lang.String> newSymbols, SymbolTable... imports)
Creates a new shared symbol table containing a given set of symbols.IonWriter
newTextWriter(java.io.OutputStream out)
Creates a new writer that will write UTF-8 text to the given output stream.IonWriter
newTextWriter(java.io.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.IonWriter
newTextWriter(java.lang.Appendable out)
Creates a new writer that will write text to the given output stream.IonWriter
newTextWriter(java.lang.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.IonTimestamp
newUtcTimestamp(java.util.Date utcDate)
Constructs a new UTCtimestamp
instance initialized so that it represents the given time.IonTimestamp
newUtcTimestampFromMillis(long millis)
Constructs a new UTCtimestamp
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 anIonValue
.IonWriter
newWriter(IonContainer container)
Creates a new writer that will addIonValue
s to the given container.IonValue
singleValue(byte[] ionData)
Extracts a single value from Ion text or binary data.IonValue
singleValue(byte[] ionData, int offset, int len)
Extracts a single value from Ion text or binary data.IonValue
singleValue(java.lang.String ionText)
Extracts a single value from Ion text data.-
Methods inherited from interface com.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, newList, newNull, newNull, newNullBlob, newNullBool, newNullClob, newNullDecimal, newNullFloat, newNullInt, newNullList, newNullSexp, newNullString, newNullStruct, newNullSymbol, newNullTimestamp, newSexp, 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(java.lang.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:
java.lang.IllegalArgumentException
- if any import is a local table, or if any but the first is a system table.java.lang.NullPointerException
- if any import is null.
-
newSharedSymbolTable
SymbolTable newSharedSymbolTable(java.lang.String name, int version, java.util.Iterator<java.lang.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
.
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 viaSymbolTable.writeTo(IonWriter)
and materialized vianewSharedSymbolTable(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
- ifversion > 1
and the prior version does not exist in this system's catalog.
-
If
-
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
java.util.Iterator<IonValue> iterate(java.io.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 anIonException
. 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
- a stream of Ion text data. The caller is responsible for closing the Reader after iteration is complete.- Returns:
- a new iterator instance.
- Throws:
java.lang.NullPointerException
- ifionText
is null.IonException
- if the source throwsIOException
.
-
iterate
@Deprecated java.util.Iterator<IonValue> iterate(java.io.InputStream ionData)
Deprecated.Will cause a memory leak when reading a gzipped stream. Useiterate(IonReader)
instead.WARNING: Will cause a memory leak when reading a gzipped stream, use
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.iterate(IonReader)
instead.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 anIonException
. 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:
java.lang.NullPointerException
- ifionData
is null.IonException
- if the source throwsIOException
.
-
iterate
java.util.Iterator<IonValue> iterate(java.lang.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:
java.lang.NullPointerException
- ifionText
is null.
-
iterate
@Deprecated java.util.Iterator<IonValue> iterate(byte[] ionData)
Deprecated.Will cause a memory leak when reading a gzipped byte[]. Useiterate(IonReader)
instead.WARNING: Will cause a memory leak when reading a gzipped byte[], use
Creates an iterator over Ion data. Values returned by the iterator have no container.iterate(IonReader)
instead.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:
java.lang.NullPointerException
- ifionData
is null.
-
iterate
java.util.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
- source of the Ion data to iterate over.- Returns:
- a new iterator instance.
- Throws:
java.lang.NullPointerException
- ifreader
is null.
-
singleValue
IonValue singleValue(java.lang.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:
java.lang.NullPointerException
- ifionText
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:
java.lang.NullPointerException
- ifionData
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, 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
- is used only within the range of bytes starting atoffset
forlen
bytes. The data in that range may be either Ion binary data, or UTF-8 Ion text.offset
- must be non-negative and less thanionData.length
.len
- must be non-negative andoffset+len
must not exceed- Returns:
- the first (and only) user value in the data; not null.
- Throws:
java.lang.NullPointerException
- ifionData
is null.UnexpectedEofException
- if the data doesn't contain any user values.IonException
- if the data does not contain exactly one user value.
-
newReader
IonTextReader newReader(java.lang.String ionText)
Creates an newIonReader
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 newIonReader
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 newIonReader
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 atoffset
forlen
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 thanionData.length
.len
- must be non-negative andoffset+len
must not exceedionData.length
.
-
newReader
IonReader newReader(java.io.InputStream ionData)
Creates a newIonReader
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 throwsIOException
.
-
newReader
IonReader newReader(java.io.Reader ionText)
Creates an newIonReader
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.
- Throws:
IonException
- if the source throwsIOException
.
-
newReader
IonReader newReader(IonValue value)
Creates an newIonReader
instance over anIonValue
data model. Typically this is used to iterate over a collection, such as anIonStruct
. 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
- must not be null.
-
newWriter
IonWriter newWriter(IonContainer container)
Creates a new writer that will addIonValue
s 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; notnull
.
-
newTextWriter
IonWriter newTextWriter(java.io.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; notnull
. - See Also:
IonTextWriterBuilder
-
newTextWriter
IonWriter newTextWriter(java.lang.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; notnull
. - See Also:
IonTextWriterBuilder
-
newTextWriter
IonWriter newTextWriter(java.io.OutputStream out, SymbolTable... imports) throws java.io.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; notnull
. - Throws:
java.io.IOException
- if its thrown by the output stream.- See Also:
IonTextWriterBuilder
-
newTextWriter
IonWriter newTextWriter(java.lang.Appendable out, SymbolTable... imports) throws java.io.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; notnull
. - Throws:
java.io.IOException
- if its thrown by the output stream.- See Also:
IonTextWriterBuilder
-
newBinaryWriter
IonWriter newBinaryWriter(java.io.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:
java.lang.IllegalArgumentException
- if any import is a local table, or if any but the first is a system table.java.lang.NullPointerException
- if any import is null.
-
newBinaryWriter
@Deprecated IonBinaryWriter newBinaryWriter()
Deprecated.UseĀnewBinaryWriter(OutputStream, SymbolTable...)
instead.Creates a new writer that will encode binary Ion data.- Returns:
- a new
IonBinaryWriter
instance; notnull
.
-
newBinaryWriter
@Deprecated IonBinaryWriter newBinaryWriter(SymbolTable... imports)
Deprecated.UsenewBinaryWriter(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
- a sequence of shared symbol tables- Returns:
- a new
IonBinaryWriter
instance; notnull
.
-
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'ssystem
must be this system. Ifnull
, then the returned datagram will have no user values.- Returns:
- a new datagram.
- Throws:
java.lang.IllegalArgumentException
- ifinitialChild
is anIonDatagram
.
-
newDatagram
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 callsIonDatagram.getBytes(byte[])
(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:
java.lang.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 anIonValue
. The caller must position the reader on the correct value by callingIonReader.next()
beforehand.- Returns:
- a new value object, not null.
-
newUtcTimestampFromMillis
IonTimestamp newUtcTimestampFromMillis(long millis)
Constructs a new UTCtimestamp
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(java.util.Date utcDate)
Constructs a new UTCtimestamp
instance initialized so that it represents the given time. As perDate
class, this will have millisecond precision.This is equivalent to
newUtcTimestampFromMillis(utcDate.getTime())
.- Parameters:
utcDate
- the time of the new instance; may benull
to makenull.timestamp
.
-
newCurrentUtcTimestamp
IonTimestamp newCurrentUtcTimestamp()
Constructs a new UTCtimestamp
instance initialized so that it represents the time at which it was allocated, measured to the nearest millisecond.
-
-