Package com.amazon.ion

Interface IonValue

All Superinterfaces:
Cloneable
All Known Subinterfaces:
_Private_IonContainer, _Private_IonDatagram, _Private_IonSymbol, _Private_IonValue, IonBlob, IonBool, IonClob, IonContainer, IonDatagram, IonDecimal, IonFloat, IonInt, IonList, IonLob, IonNull, IonNumber, IonSequence, IonSexp, IonString, IonStruct, IonSymbol, IonText, IonTimestamp
public interface IonValue extends Cloneable
Base type for all Ion data nodes.

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

The IonValue hierarchy presents a "tree view" of Ion data; every node in the tree is an instance of this class. Since the Ion type system is highly orthogonal, most operations use this base type, and applications will need to examine individual instances and "downcast" the value to one of the "real" types (e.g., IonString) in order to access the Ion content.

Besides the real types, there are other generic interfaces that can be useful:

To determine the real type of a generic IonValue, there are three main mechanisms:

  • Use instanceof to look for a desired interface: 
        if (v instanceof IonString)
    {
        useString((IonString) v);
    }
    else if (v instanceof IonStruct)
    {
        useStruct((IonStruct) v);
    }
    // ...
  • Call getType() and then switch over the resulting IonType: 
        switch (v.getType())
    {
        case IonType.STRING: useString((IonString) v); break;
        case IonType.STRUCT: useStruct((IonStruct) v); break;
        // ...
    }
  • Implement ValueVisitor and call accept(ValueVisitor): 
        public class MyVisitor
        extends AbstractValueVisitor
    {
        public void visit(IonString value)
        {
            useString(v);
        }
        public void visit(IonStruct value)
        {
            useStruct(v);
        }
        // ...
     }
Use the most appropriate mechanism for your algorithm, depending upon how much validation you've done on the data.

Single-Parent Restriction

IonValue trees are strictly hierarchical: every node has at most one parent, as exposed through getContainer() (and, implicitly, getFieldName()). You cannot add an IonValue instance into two IonContainers; any attempt to do so will result in a ContainedValueException. You can of course add the same instance to multiple "normal" Collections, since that's stepping outside of the DOM.

The implication of this design is that you need to be careful when performing DOM transformations. You must remove a node from its parent before adding it to another one; removeFromContainer() is handy. Alternatively you can clone() a value, but be aware that cloning is a deep-copy operation (for the very same single-parent reason).

Thread Safety

Mutable IonValues are not safe for use by multiple threads! Your application must perform its own synchronization if you need to access IonValues from multiple threads. This is true even for read-only use cases, since implementations may perform lazy materialization or other state changes internally.

Alternatively, you can invoke makeReadOnly() from a single thread, after which point the value (and all recursively contained values) will be immutable and hence thread-safe.

It is important to note that makeReadOnly() is not guaranteed to implicitly provide a synchronization point between threads. This means it is the responsibility of the application to make sure operations on a thread other than the one that invoked makeReadOnly() causally happen after that invocation observing the rules of the Java Memory Model (JSR-133).

Here is an example of ensuring the correct ordering for multiple threads accessing an IonValue using a CountDownLatch to explicitly create a the temporal relationship: 

      // ...
      // Shared Between Threads
      // ...

      IonValue value = ...;
      CountDownLatch latch = new CountDownLatch(1);

      // ...
      // Thread 1
      // ...

      value.makeReadOnly();
      latch.countDown();

      // ...
      // Thread 2
      // ...

      // before this point operations on 'value' are not defined
      latch.await();
      // we can now operate (in a read-only way) on 'value'
      value.isNullValue();

In the above, two threads have a reference to value. latch in this example provides a way to synchronize when makeReadOnly() happens in the first thread relative to isNullValue() being invoked on the second thread.

  • Field Details

    • EMPTY_ARRAY

      static final IonValue[] EMPTY_ARRAY
      A zero-length immutable IonValue array.

  • Method Details

    • getType

      IonType getType()
      Gets an enumeration value identifying the core Ion data type of this object.
      Returns:
      a non-null enumeration value.

    • isNullValue

      boolean isNullValue()
      Determines whether this in an Ion null value, e.g., null or null.string. Note that there are unique null values for each Ion type.
      Returns:
      true if this value is one of the Ion null values.

    • isReadOnly

      boolean isReadOnly()
      Determines whether this value is read-only. Such values are safe for simultaneous read from multiple threads.
      Returns:
      true if this value is read-only and safe for multi-threaded reads.
      See Also:

    • getSymbolTable

      SymbolTable getSymbolTable()
      Gets the symbol table used to encode this value. The result is either a local or system symbol table (or null).
      Returns:
      the symbol table, or null if this value is not currently backed by binary-encoded data.

    • getFieldName

      String getFieldName()
      Gets the field name attached to this value, or null if this is not part of an IonStruct.
      Throws:
      UnknownSymbolException - if the field name has unknown text.

    • getFieldNameSymbol

      SymbolToken getFieldNameSymbol()
      Gets the field name attached to this value as an interned symbol (text + ID).
      Returns:
      null if this value isn't a struct field.

    • getFieldId

      @Deprecated int getFieldId()
      Deprecated.
      Use getFieldNameSymbol() instead.
      Gets the symbol ID of the field name attached to this value.
      Returns:
      the symbol ID of the field name, if this is part of an IonStruct. If this is not a field, or if the symbol ID cannot be determined, this method returns a value less than one.

    • getContainer

      IonContainer getContainer()
      Gets the container of this value, or null if this is not part of one.

    • removeFromContainer

      boolean removeFromContainer()
      Removes this value from its container, if any.
      Returns:
      true if this value was in a container before this method was called.

    • topLevelValue

      IonValue topLevelValue()
      Finds the top level value above this value. If this value has no container, or if it's immediate container is a datagram, then this value is returned.
      Returns:
      the top level value above this value, never null, and never an IonDatagram.
      Throws:
      UnsupportedOperationException - if this is an IonDatagram.

    • getTypeAnnotations

      String[] getTypeAnnotations()
      Gets this value's user type annotations as text.
      Returns:
      the (ordered) annotations on the current value, or an empty array (not null) if there are none.
      Throws:
      UnknownSymbolException - if any annotation has unknown text.

    • getTypeAnnotationSymbols

      SymbolToken[] getTypeAnnotationSymbols()
      Gets this value's user type annotations as interned symbols (text + ID).
      Returns:
      the (ordered) annotations on the current value, or an empty array (not null) if there are none.

    • hasTypeAnnotation

      boolean hasTypeAnnotation(String annotation)
      Determines whether or not the value is annotated with a particular user type annotation.
      Parameters:
      annotation - as a string value.
      Returns:
      true if this value has the annotation.

    • setTypeAnnotations

      void setTypeAnnotations(String... annotations)
      Replaces all type annotations with the given text.
      Parameters:
      annotations - the new annotations. If null or empty array, then all annotations are removed. Any duplicates are preserved.
      Throws:
      NullPointerException - if any of the annotations are null

    • setTypeAnnotationSymbols

      void setTypeAnnotationSymbols(SymbolToken... annotations)
      Replaces all type annotations with the given symbol tokens. The contents of the annotations array are copied into this writer, so the caller does not need to preserve the array.

      This is an "expert method": correct use requires deep understanding of the Ion binary format. You almost certainly don't want to use it.

      Parameters:
      annotations - the new annotations. If null or empty array, then all annotations are removed. Any duplicates are preserved.

    • clearTypeAnnotations

      void clearTypeAnnotations()
      Removes all the user type annotations attached to this value.

    • addTypeAnnotation

      void addTypeAnnotation(String annotation)
      Adds a user type annotation to the annotations attached to this value. If the annotation exists the list does not change.
      Parameters:
      annotation - as a string value.

    • removeTypeAnnotation

      void removeTypeAnnotation(String annotation)
      Removes a user type annotation from the list of annotations attached to this value. If the annotation appears more than once, only the first occurrance is removed. If the annotation does not exist, the value does not change.
      Parameters:
      annotation - as a string value. If null or empty, the method has no effect.

    • writeTo

      void writeTo(IonWriter writer)
      Copies this value to the given IonWriter.

      This method writes annotations and field names (if in a struct), and performs a deep write, including the contents of any containers encountered.

    • accept

      void accept(ValueVisitor visitor) throws Exception
      Entry point for visitor pattern. Implementations of this method by concrete classes will simply call the appropriate visit method on the visitor. For example, instances of IonBool will invoke ValueVisitor.visit(IonBool).
      Parameters:
      visitor - will have one of its visit methods called.
      Throws:
      Exception - any exception thrown by the visitor is propagated.
      NullPointerException - if visitor is null.

    • makeReadOnly

      void makeReadOnly()
      Marks this instance and its children to be immutable. In addition, read-only values are safe for simultaneous use from multiple threads. This may require materializing the Java forms of the values.

      After this method completes, any attempt to change the state of this instance, or of any contained value, will trigger a ReadOnlyValueException.

      See Also:

    • getSystem

      IonSystem getSystem()
      Gets the system that constructed this value.
      Returns:
      not null.

    • clone

      IonValue clone() throws UnknownSymbolException
      Creates a copy of this value and all of its children. The cloned value may use the same shared symbol tables, but it will have an independent local symbol table if necessary. The cloned value will be modifiable regardless of whether this instance isReadOnly().

      The cloned value will be created in the context of the same ValueFactory as this instance; if you want a copy using a different factory, then use ValueFactory.clone(IonValue) instead.

      Throws:
      UnknownSymbolException - if any part of this value has unknown text but known Sid for its field name, annotation or symbol.

    • toString

      String toString()
      Returns a non-canonical Ion-formatted ASCII representation of this value. All data will be on a single line, with (relatively) minimal whitespace. There is no guarantee that multiple invocations of this method will return identical results, only that they will be equivalent per the Ion data model. For this reason it is erroneous for code to compare two strings returned by this method.

      For more configurable rendering, see IonTextWriterBuilder.

      This is not the correct way to retrieve the content of an IonString or IonSymbol! Use IonText.stringValue() for that purpose. 

          ionSystem.newString("Levi's").toString()     =>  "\"Levi's\""
    ionSystem.newString("Levi's").stringValue()  =>  "Levi's"
    ionSystem.newSymbol("Levi's").toString()     =>  "'Levi\\'s'"
    ionSystem.newSymbol("Levi's").stringValue()  =>  "Levi's"
      Overrides:
      toString in class Object
      Returns:
      Ion text data equivalent to this value.
      See Also:

    • toPrettyString

      String toPrettyString()
      Returns a pretty-printed Ion text representation of this value, using the settings of IonTextWriterBuilder.pretty().

      The specific configuration may change between releases of this library, so automated processes should not depend on the exact output formatting. In particular, there's currently no promise regarding handling of system data.

      Returns:
      Ion text data equivalent to this value.

    • toString

      String toString(IonTextWriterBuilder writerBuilder)
      Returns an Ion text representation of this value, using the settings from the given builder.
      Parameters:
      writerBuilder - the configuration that will be used for writing data to a string.
      Returns:
      Ion text data equivalent to this value.

    • equals

      boolean equals(Object other)
      Compares two Ion values for structural equality, which means that they represent the exact same semantics, including annotations, numeric precision, and so on. This is a "deep" comparison that recursively traverses the hierarchy, and as such it should be considered an expensive operation.
      Overrides:
      equals in class Object
      Parameters:
      other - The value to compare with.
      Returns:
      A boolean, true if the argument is an IonValue that is semantically identical within the Ion data model, including precision and annotations.
      See Also:

    • hashCode

      int hashCode()
      Returns a hash code consistent with equals(Object).

      Overrides:
      hashCode in class Object