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

Field Summary

Fields inherited from interface software.amazon.ion.IonValue

EMPTY_ARRAY

Method Summary

Modifier and Type	Method and Description
ValueFactory	add(String fieldName) Provides a factory that when invoked constructs a new value and adds it to this struct using the given fieldName.
void	add(String fieldName, IonValue child) Adds a new field to this struct.
void	add(SymbolToken fieldName, IonValue child) Adds a new field to this struct using a given name and/or SID.
IonStruct	clone() Creates a copy of this value and all of its children.
IonStruct	cloneAndRemove(String... fieldNames) Clones this struct, excluding certain fields.
IonStruct	cloneAndRetain(String... fieldNames) Clones this struct, including only certain fields.
boolean	containsKey(Object fieldName) Determines whether this struct contains one or more fields for the specified field name (i.e., key).
boolean	containsValue(Object value) Determines whether this struct contains one or more fields with the specified value.
IonValue	get(String fieldName) Gets the value of a field in this struct.
ValueFactory	put(String fieldName) Provides a factory that when invoked constructs a new value and puts it into this struct using the given fieldName.
void	put(String fieldName, IonValue child) Puts a new field in this struct, replacing all existing fields with the same name.
void	putAll(Map<? extends String,? extends IonValue> m) Copies all of the mappings from the specified map to this struct.
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.
boolean	removeAll(String... fieldNames) Removes from this struct all fields with names in the given list.
boolean	retainAll(String... fieldNames) Retains only the fields in this struct that have one of the given names.
int	size() Gets the number of fields in this struct.

Methods inherited from interface software.amazon.ion.IonContainer

clear, isEmpty, iterator, makeNull, remove

Methods inherited from interface software.amazon.ion.IonValue

accept, addTypeAnnotation, clearTypeAnnotations, equals, getContainer, getFieldName, getFieldNameSymbol, getSymbolTable, getSystem, getType, getTypeAnnotations, getTypeAnnotationSymbols, hashCode, hasTypeAnnotation, isNullValue, isReadOnly, makeReadOnly, removeFromContainer, removeTypeAnnotation, setTypeAnnotations, setTypeAnnotationSymbols, topLevelValue, toPrettyString, toString, toString, writeTo

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

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:

put(String, IonValue)

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:

add(String, IonValue)

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:

IonValue.clone()

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:

IonValue.clone()