Package com.amazon.ion

Interface IonStruct

All Superinterfaces:
Cloneable, IonContainer, IonValue, Iterable<IonValue>
public interface IonStruct extends IonContainer
An Ion struct value.

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

Note that this cannot extend Map because that interface requires unique keys, while Ion's structs allow duplicate field names.

  • Method Details

    • size

      int size() throws NullValueException
      Gets the number of fields in this struct. If any field names are repeated, they are counted individually. For example, the size of {a:1,a:2} is 2.
      Specified by:
      size in interface IonContainer
      Returns:
      the number of fields.
      Throws:
      NullValueException - if this.isNullValue().

    • containsKey

      boolean containsKey(Object fieldName)
      Determines whether this struct contains one or more fields for the specified field name (i.e., key). If this struct is an Ion null value, it will behave like an empty struct.
      Parameters:
      fieldName - field name whose presence in this struct is to be tested
      Returns:
      true if this struct contains a field for the specified field name
      Throws:
      ClassCastException - if the specified field name is not a String
      NullPointerException - if the specified field name is null

    • containsValue

      boolean containsValue(Object value)
      Determines whether this struct contains one or more fields with the specified value. If this struct is an Ion null value, it will behave like an empty struct. This uses reference equality to compare the specified value with the value of the struct fields.
      Parameters:
      value - value whose presence in this struct is to be tested
      Returns:
      true if this struct contains a field for the specified value
      Throws:
      ClassCastException - if the specified value is not an IonValue
      NullPointerException - if the specified value is null

    • get

      IonValue get(String fieldName)
      Gets the value of a field in this struct. If the field name appears more than once, one of the fields will be selected arbitrarily. For example, calling get("a") on the struct: 
          { a:1, b:2, a:3 }
      will return either 1 or 3.
      Parameters:
      fieldName - the desired field.
      Returns:
      the value of the field, or null if it doesn't exist in this struct, or if this is null.struct.
      Throws:
      NullPointerException - if the fieldName is null.

    • put

      void put(String fieldName, IonValue child) throws ContainedValueException
      Puts a new field in this struct, replacing all existing fields with the same name. If child == null then all existing fields with the given name will be removed.

      If this is null.struct and child != null then this becomes a single-field struct.

      The effect of this method is such that if put(fieldName, child) succeeds, then get(fieldName) == child will be true afterwards.

      Parameters:
      fieldName - the name of the new field.
      child - the value of the new field.
      Throws:
      NullPointerException - if fieldName is null.
      ContainedValueException - if child is already part of a container.
      IllegalArgumentException - if element is an IonDatagram.

    • put

      ValueFactory put(String fieldName)
      Provides a factory that when invoked constructs a new value and puts it into this struct using the given fieldName.

      These two lines are equivalent: 

          str.put("f").newInt(3);
    str.put("f", str.getSystem().newInt(3));
      Throws:
      NullPointerException - if fieldName is null.
      See Also:

    • putAll

      void putAll(Map<? extends String,? extends IonValue> m)
      Copies all of the mappings from the specified map to this struct. The effect of this call is equivalent to that of calling put(k, v) on this struct once for each mapping from key k to value v in the specified map. The behavior of this operation is undefined if the specified map is modified while the operation is in progress.

      If a key in the map maps to null, then all fields with that name will be removed from this struct.

      Throws:
      NullPointerException - if the given map is null.
      ContainedValueException - if any values in the map are already part of an IonContainer (even this one).

    • add

      void add(String fieldName, IonValue child) throws ContainedValueException
      Adds a new field to this struct. If this is null.struct, then it becomes a single-field struct.

      If a field with the given name already exists in this struct, this call will result in repeated fields.

      Parameters:
      fieldName - the name of the new field.
      child - the value of the new field.
      Throws:
      NullPointerException - if fieldName or child is null.
      ContainedValueException - if child is already part of a container.
      IllegalArgumentException - if element is an IonDatagram.

    • add

      void add(SymbolToken fieldName, IonValue child) throws ContainedValueException
      Adds a new field to this struct using a given name and/or SID. If this is null.struct, then it becomes a single-field struct.

      If a field with the given name already exists in this struct, this call will result in repeated fields.

      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:
      fieldName - the name of the new field.
      child - the value of the new field.
      Throws:
      NullPointerException - if fieldName or child is null.
      ContainedValueException - if child is already part of a container.
      IllegalArgumentException - if element is an IonDatagram.

    • add

      ValueFactory add(String fieldName)
      Provides a factory that when invoked constructs a new value and adds it to this struct using the given fieldName.

      These two lines are equivalent: 

          str.add("f").newInt(3);
    str.add("f", str.getSystem().newInt(3));
      Throws:
      NullPointerException - if fieldName is null.
      See Also:

    • remove

      IonValue remove(String fieldName)
      Removes a field by name, returning a value that was previously associated with the field, or null if this struct contained no such field.

      Because Ion structs may have repeated fields, additional fields with the given name may still exist after this method returns.

      If this struct is an Ion null value or empty, then this method returns null and has no effect.

      Parameters:
      fieldName - must not be null.
      Returns:
      previous value associated with the specified field name, or null if there was no such field.

    • removeAll

      boolean removeAll(String... fieldNames)
      Removes from this struct all fields with names in the given list. If multiple fields with a given name exist in this struct, they will all be removed.

      If this struct is an Ion null value or empty, then this method returns false and has no effect.

      Parameters:
      fieldNames - the names of the fields to remove.
      Returns:
      true if this struct changed as a result of this call.
      Throws:
      NullPointerException - if fieldNames, or any element within it, is null.

    • retainAll

      boolean retainAll(String... fieldNames)
      Retains only the fields in this struct that have one of the given names. In other words, removes all fields with names that are not in fieldNames.

      If this struct is an Ion null value or empty, then this method returns false and has no effect.

      Parameters:
      fieldNames - the names of the fields to retain.
      Returns:
      true if this struct changed as a result of this call.
      Throws:
      NullPointerException - if fieldNames, or any element within it, is null.

    • clone

      IonStruct clone() throws UnknownSymbolException
      Description copied from interface: IonValue
      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 IonValue.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.

      Specified by:
      clone in interface IonContainer
      Specified by:
      clone in interface IonValue
      Throws:
      UnknownSymbolException - if any part of this value has unknown text but known Sid for its field name, annotation or symbol.

    • cloneAndRemove

      IonStruct cloneAndRemove(String... fieldNames) throws UnknownSymbolException
      Clones this struct, excluding certain fields. This can be more efficient than cloning the struct and removing fields later on.
      Parameters:
      fieldNames - the names of the fields to remove. A null field name causes removal of fields with unknown names.
      Throws:
      UnknownSymbolException - if any part of the cloned value would have unknown text but known SID for its field name, annotation or symbol.
      See Also:

    • cloneAndRetain

      IonStruct cloneAndRetain(String... fieldNames) throws UnknownSymbolException
      Clones this struct, including only certain fields. This can be more efficient than cloning the struct and removing fields later on.
      Parameters:
      fieldNames - the names of the fields to retain. Nulls are not allowed.
      Throws:
      NullPointerException - if fieldNames, or any element within it, is null.
      UnknownSymbolException - if any part of the cloned value would have unknown text but known SID for its field name, annotation or symbol.
      See Also: