Ion Java 1.11.10 · com.amazon.ion.IonStruct · APIdia, the JavaDoc alternative

Method Summary

Modifier and Type	Method and Description
public void	add(String the name of the new field. fieldName, IonValue the value of the new field. child) Adds a new field to this struct.
public void	add(SymbolToken the name of the new field. fieldName, IonValue the value of the new field. child) Adds a new field to this struct using a given name and/or SID.
public ValueFactory	add(String fieldName) Provides a factory that when invoked constructs a new value and `add`s it to this struct using the given `fieldName`.
public IonStruct	clone() Redeclares com.amazon.ion.IonContainer.clone. Creates a copy of this value and all of its children.
public IonStruct	cloneAndRemove(String... the names of the fields to remove. A null field name causes removal of fields with unknown names. fieldNames) Clones this struct, excluding certain fields.
public IonStruct	cloneAndRetain(String... the names of the fields to retain. Nulls are not allowed. fieldNames) Clones this struct, including only certain fields.
public boolean	Returns: `true` if this struct contains a field for the specified field name containsKey(Object field name whose presence in this struct is to be tested fieldName) Determines whether this struct contains one or more fields for the specified field name (i.e., key).
public boolean	Returns: `true` if this struct contains a field for the specified value containsValue(Object value whose presence in this struct is to be tested value) Determines whether this struct contains one or more fields with the specified value.
public IonValue	Returns: the value of the field, or `null` if it doesn't exist in this struct, or if this is `null.struct`. get(String the desired field. fieldName) Gets the value of a field in this struct.
public void	put(String the name of the new field. fieldName, IonValue the value of the new field. child) Puts a new field in this struct, replacing all existing fields with the same name.
public ValueFactory	put(String fieldName) Provides a factory that when invoked constructs a new value and `put`s it into this struct using the given `fieldName`.
public void	putAll(Map<? extends String, ? extends IonValue> m) Copies all of the mappings from the specified map to this struct.
public IonValue	Returns: previous value associated with the specified field name, or `null` if there was no such field. remove(String must not be null. 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.
public boolean	Returns: true if this struct changed as a result of this call. removeAll(String... the names of the fields to remove. fieldNames) Removes from this struct all fields with names in the given list.
public boolean	Returns: true if this struct changed as a result of this call. retainAll(String... the names of the fields to retain. fieldNames) Retains only the fields in this struct that have one of the given names.
public int	Returns: the number of fields. size() Redeclares com.amazon.ion.IonContainer.size. Gets the number of fields in this struct.

Inherited from com.amazon.ion.IonContainer:: clear isEmpty iterator makeNull remove

Method Detail

add back to summary

add	back to summary
public 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:String the name of the new field. child:IonValue the value of the new field. Exceptions ContainedValueException: if `child` is already part of a container. NullPointerException: if `fieldName` or `child` is `null`. IllegalArgumentException: if `element` is an `IonDatagram`.

public 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:String: the name of the new field.
child:IonValue: the value of the new field.

Exceptions

ContainedValueException:: if child is already part of a container.
NullPointerException:: if fieldName or child is null.
IllegalArgumentException:: if element is an IonDatagram.

add back to summary

add	back to summary
public 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:SymbolToken the name of the new field. child:IonValue the value of the new field. Exceptions ContainedValueException: if `child` is already part of a container. NullPointerException: if `fieldName` or `child` is `null`. IllegalArgumentException: if `element` is an `IonDatagram`.

public 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:SymbolToken: the name of the new field.
child:IonValue: the value of the new field.

Exceptions

ContainedValueException:: if child is already part of a container.
NullPointerException:: if fieldName or child is null.
IllegalArgumentException:: if element is an IonDatagram.

add back to summary

add	back to summary
public ValueFactory add(String fieldName) Provides a factory that when invoked constructs a new value and `add`s 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)); Exceptions NullPointerException: if `fieldName` is `null`. See Also `add(String, IonValue)`

public 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));

Exceptions

NullPointerException:: if fieldName is null.

See Also

add(String, IonValue)

clone back to summary

clone	back to summary
public IonStruct clone() throws UnknownSymbolException Redeclares com.amazon.ion.IonContainer.clone. Doc from com.amazon.ion.IonValue.clone. 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. Exceptions UnknownSymbolException: if any part of this value has unknown text but known Sid for its field name, annotation or symbol.

public IonStruct clone() throws UnknownSymbolException

Redeclares com.amazon.ion.IonContainer.clone.

Doc from com.amazon.ion.IonValue.clone.

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.

Exceptions

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

cloneAndRemove back to summary

cloneAndRemove	back to summary
public 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:String[] the names of the fields to remove. A null field name causes removal of fields with unknown names. Exceptions 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()`

public 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:String[]: the names of the fields to remove. A null field name causes removal of fields with unknown names.

Exceptions

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 back to summary

cloneAndRetain	back to summary
public 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:String[] the names of the fields to retain. Nulls are not allowed. Exceptions UnknownSymbolException: if any part of the cloned value would have unknown text but known SID for its field name, annotation or symbol. NullPointerException: if `fieldNames`, or any element within it, is `null`. See Also `IonValue#clone()`

public 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:String[]: the names of the fields to retain. Nulls are not allowed.

Exceptions

UnknownSymbolException:: if any part of the cloned value would have unknown text but known SID for its field name, annotation or symbol.
NullPointerException:: if fieldNames, or any element within it, is null.

See Also

IonValue#clone()

containsKey back to summary

containsKey	back to summary
public 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:Object field name whose presence in this struct is to be tested Returns:boolean `true` if this struct contains a field for the specified field name Exceptions ClassCastException: if the specified field name is not a `String` NullPointerException: if the specified field name is `null`

public 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:Object: field name whose presence in this struct is to be tested

Returns:boolean

true if this struct contains a field for the specified field name

Exceptions

ClassCastException:: if the specified field name is not a String
NullPointerException:: if the specified field name is null

containsValue back to summary

containsValue	back to summary
public 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:Object value whose presence in this struct is to be tested Returns:boolean `true` if this struct contains a field for the specified value Exceptions ClassCastException: if the specified value is not an `IonValue` NullPointerException: if the specified value is `null`

public 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:Object: value whose presence in this struct is to be tested

Returns:boolean

true if this struct contains a field for the specified value

Exceptions

ClassCastException:: if the specified value is not an IonValue
NullPointerException:: if the specified value is null

get back to summary

get	back to summary
public 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:String the desired field. Returns:IonValue the value of the field, or `null` if it doesn't exist in this struct, or if this is `null.struct`. Exceptions NullPointerException: if the `fieldName` is `null`.

public 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:String: the desired field.

Returns:IonValue

the value of the field, or null if it doesn't exist in this struct, or if this is null.struct.

Exceptions

NullPointerException:: if the fieldName is null.

put back to summary

put	back to summary
public 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:String the name of the new field. child:IonValue the value of the new field. Exceptions ContainedValueException: if `child` is already part of a container. NullPointerException: if `fieldName` is `null`. IllegalArgumentException: if `element` is an `IonDatagram`.

public 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:String: the name of the new field.
child:IonValue: the value of the new field.

Exceptions

ContainedValueException:: if child is already part of a container.
NullPointerException:: if fieldName is null.
IllegalArgumentException:: if element is an IonDatagram.

put back to summary

put	back to summary
public ValueFactory put(String fieldName) Provides a factory that when invoked constructs a new value and `put`s 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)); Exceptions NullPointerException: if `fieldName` is `null`. See Also `put(String, IonValue)`

public 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));

Exceptions

NullPointerException:: if fieldName is null.

See Also

put(String, IonValue)

putAll back to summary

putAll	back to summary
public 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. Exceptions NullPointerException: if the given map is null. ContainedValueException: if any values in the map are already part of an `IonContainer` (even this one).

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

Exceptions

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

remove back to summary

remove	back to summary
public 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:String must not be null. Returns:IonValue previous value associated with the specified field name, or `null` if there was no such field.

public 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:String: must not be null.

Returns:IonValue

previous value associated with the specified field name, or null if there was no such field.

removeAll back to summary

removeAll	back to summary
public 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:String[] the names of the fields to remove. Returns:boolean true if this struct changed as a result of this call. Exceptions NullPointerException: if `fieldNames`, or any element within it, is `null`.

public 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:String[]: the names of the fields to remove.

Returns:boolean

true if this struct changed as a result of this call.

Exceptions

NullPointerException:: if fieldNames, or any element within it, is null.

retainAll back to summary

retainAll	back to summary
public 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:String[] the names of the fields to retain. Returns:boolean true if this struct changed as a result of this call. Exceptions NullPointerException: if `fieldNames`, or any element within it, is `null`.

public 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:String[]: the names of the fields to retain.

Returns:boolean

true if this struct changed as a result of this call.

Exceptions

NullPointerException:: if fieldNames, or any element within it, is null.

size back to summary

size	back to summary
public int size() throws NullValueException Redeclares com.amazon.ion.IonContainer.size. 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. Returns:int the number of fields. Exceptions NullValueException: if `this.isNullValue()`.

public int size() throws NullValueException

Redeclares com.amazon.ion.IonContainer.size.

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.

Returns:int

the number of fields.

Exceptions

NullValueException:: if this.isNullValue().

public Interface IonStruct

Method Summary

Method Detail