Skip navigation links
Amazon Ion Java 1.0.2 API Reference

Amazon Ion Java 1.0.2 API Reference

Amazon Ion Java is the reference implementation of the Ion data notation for the JavaTM 2 Platform Standard Edition 5.0 and above.

See: Description

Package Description
Public interfaces of the core Ion system.
A design pattern for optional extension interfaces, in a manner more flexible than class inheritance.
Public implementation of the core Ion system.
Various utilites for working with Ion data.
Amazon Ion Java is the reference implementation of the Ion data notation for the JavaTM 2 Platform Standard Edition 5.0 and above.

This document describes all APIs intended for public consumption, limited to the packages listed here. The ion-java library distribution includes other packages not documented here; use of those packages is not supported.

More generally: Any behavior or features not present in this API documentation is unsupported, probably untested, and subject to change without notice.

In addition, unless otherwise noted, interfaces and classes listed here should not be implemented or extended by code outside of this library. We may add or remove API(s) of existing interfaces or classes in future releases.

Start at IonSystem

The central interface in ion-java is IonSystem, which is the main factory and facade for all Ion processing. The intended architectural pattern is for your application to build a single system instance and use it throughout the application. The IonSystem interface provides access to all other components, including the capability to construct IonValue hierarchies.

What all this means is that your first task is acquiring a system instance, and for that we turn to IonSystemBuilder. Here's the easiest way to bootstrap:

    IonSystem ion = IonSystemBuilder.standard().build();
That should be sufficient for many, but not all, applications. Long-running services will probably want to use a non-default catalog by configuring the builder before calling build().

An Important Caveat

Objects returned by one IonSystem cannot by mixed with objects returned by another IonSystem! For example, the following code is not guaranteed to work:
    IonSystem sys1 = IonSystemBuilder.standard().build();
    IonSystem sys2 = IonSystemBuilder.standard().build();

    IonList parent = sys1.newEmptyList();
    IonInt  child  = sys2.newInt(23);
    parent.add(child); // NOT SUPPORTED
Given any IonValue instance it is possible to retrieve the relevant system via IonValue.getSystem(). This is generally the best way to ensure that you're using the correct system while modifying existing trees. You can also use the "Curried" insertion methods to add new values to collections:

Getting Data In

This release defines three mechanisms for accepting Ion data: All mechanisms accept either text or binary Ion data, and applications should rarely care about the input format.

To construct an IonReader, call one of the newReader methods on IonSystem; for example IonSystem.newReader(InputStream). You can then pull data from the reader. Don't forget to close it when you're done!

Ion iterators are extensions of Iterator so they are used once and then discarded. Use the various iterate methods on IonSystem to create them; for example IonSystem.iterate(InputStream).

To construct an IonLoader, call IonSystem.newLoader() and configure it as necessary. IonLoaders are safe for use by multiple threads. The IonSystem also maintains a "default loader" so you don't have to pass one around, see IonSystem.getLoader().

Getting Data Out

There's also several mechanisms for generating Ion data: You can create IonWriters using methods on IonSystem, but the IonTextWriterBuilder provides more flexibility.

No Canonical Serialization

There is no specified canonical form of Ion serialized data, and none of the APIs in this library attempt to create one. Further, no API in this library guarantees repeatable or stable output for any data type. Different releases of this library, or even different invocations of the same API, may produce different encodings from the same input. This caveat applies to both Ion text and binary forms, although violations are far more common (and easier to make) using Ion text.

Therefore, applications and tests should never compare the serialized form of data to determine equality. For example, the following JUnit idiom is not supported:

    assertEquals(expectedIonValue.toString(), actualIonValue.toString());
The same goes for output via any other API, including IonWriters.

The correct approach to performing semantic equivalence checks over Ion data is to use documented equivalence APIs such as IonValue.equals().

JSON Integration

The Ion text format is a superset of JSON, so JSON data is Ion data. This means that you can read JSON data as-is using the Ion libraries, with a caveat:

To output JSON with this library, Ion data can be "downconverted" to JSON format using an IonTextWriterBuilder. This replaces Ion-only datatypes with more-or-less equivalent JSON values.

Thread Safety

All interfaces and classes are not safe for use by multiple threads unless documented otherwise.
Skip navigation links
Amazon Ion Java 1.0.2 API Reference

Copyright © 2007–2017 All Rights Reserved.