Package com.amazon.ion

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

      • 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 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 - 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 - if ionText is null.
        IonException - if the source throws IOException.

      • iterate

        @Deprecated
java.util.Iterator<IonValue> iterate​(java.io.InputStream ionData)
        Deprecated.
        Will cause a memory leak when reading a gzipped stream. Use iterate(IonReader) instead.

        WARNING: Will cause a memory leak when reading a gzipped stream, use 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 - 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 - if ionData is null.
        IonException - if the source throws IOException.

      • 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 - if ionText is null.

      • iterate

        @Deprecated
java.util.Iterator<IonValue> iterate​(byte[] ionData)
        Deprecated.
        Will cause a memory leak when reading a gzipped byte[]. Use iterate(IonReader) instead.

        WARNING: Will cause a memory leak when reading a gzipped byte[], use 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 - 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 - if ionData 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 - if reader 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 - 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:
        java.lang.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

        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 at offset for len bytes. The data in that range may be either Ion binary data, or UTF-8 Ion text.
        offset - must be non-negative and less than ionData.length.
        len - must be non-negative and offset+len must not exceed
        Returns:
        the first (and only) user value in the data; not null.
        Throws:
        java.lang.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

        IonTextReader newReader​(java.lang.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​(java.io.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​(java.io.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.

        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. 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 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​(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; not null.
        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; not null.
        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; not null.
        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; not null.
        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​(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 - a sequence of shared symbol tables
        Returns:
        a new IonBinaryWriter instance; not 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:
        java.lang.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 aquire a datagram, then adds values to it, then calls IonDatagram.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 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​(java.util.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.