Interface IonStruct
-
- All Superinterfaces:
java.lang.Cloneable
,IonContainer
,IonValue
,java.lang.Iterable<IonValue>
public interface IonStruct extends IonContainer
An Ionstruct
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 com.amazon.ion.IonValue
EMPTY_ARRAY
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
add(SymbolToken fieldName, IonValue child)
Adds a new field to this struct using a given name and/or SID.ValueFactory
add(java.lang.String fieldName)
Provides a factory that when invoked constructs a new value andadd
s it to this struct using the givenfieldName
.void
add(java.lang.String fieldName, IonValue child)
Adds a new field to this struct.IonStruct
clone()
Creates a copy of this value and all of its children.IonStruct
cloneAndRemove(java.lang.String... fieldNames)
Clones this struct, excluding certain fields.IonStruct
cloneAndRetain(java.lang.String... fieldNames)
Clones this struct, including only certain fields.boolean
containsKey(java.lang.Object fieldName)
Determines whether this struct contains one or more fields for the specified field name (i.e., key).boolean
containsValue(java.lang.Object value)
Determines whether this struct contains one or more fields with the specified value.IonValue
get(java.lang.String fieldName)
Gets the value of a field in this struct.ValueFactory
put(java.lang.String fieldName)
Provides a factory that when invoked constructs a new value andput
s it into this struct using the givenfieldName
.void
put(java.lang.String fieldName, IonValue child)
Puts a new field in this struct, replacing all existing fields with the same name.void
putAll(java.util.Map<? extends java.lang.String,? extends IonValue> m)
Copies all of the mappings from the specified map to this struct.IonValue
remove(java.lang.String fieldName)
Removes a field by name, returning a value that was previously associated with the field, ornull
if this struct contained no such field.boolean
removeAll(java.lang.String... fieldNames)
Removes from this struct all fields with names in the given list.boolean
retainAll(java.lang.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 com.amazon.ion.IonContainer
clear, isEmpty, iterator, makeNull, remove
-
Methods inherited from interface com.amazon.ion.IonValue
accept, addTypeAnnotation, clearTypeAnnotations, equals, getContainer, getFieldId, getFieldName, getFieldNameSymbol, getSymbolTable, getSystem, getType, getTypeAnnotations, getTypeAnnotationSymbols, hashCode, hasTypeAnnotation, isNullValue, isReadOnly, makeReadOnly, removeFromContainer, removeTypeAnnotation, setTypeAnnotations, setTypeAnnotationSymbols, topLevelValue, toPrettyString, toString, toString, writeTo
-
-
-
-
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 interfaceIonContainer
- Returns:
- the number of fields.
- Throws:
NullValueException
- ifthis.isNullValue()
.
-
containsKey
boolean containsKey(java.lang.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:
java.lang.ClassCastException
- if the specified field name is not aString
java.lang.NullPointerException
- if the specified field name isnull
-
containsValue
boolean containsValue(java.lang.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:
java.lang.ClassCastException
- if the specified value is not anIonValue
java.lang.NullPointerException
- if the specified value isnull
-
get
IonValue get(java.lang.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, callingget("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 isnull.struct
. - Throws:
java.lang.NullPointerException
- if thefieldName
isnull
.
-
put
void put(java.lang.String fieldName, IonValue child) throws ContainedValueException
Puts a new field in this struct, replacing all existing fields with the same name. Ifchild == null
then all existing fields with the given name will be removed.If this is
null.struct
andchild != null
then this becomes a single-field struct.The effect of this method is such that if
put(fieldName, child)
succeeds, thenget(fieldName) == child
will be true afterwards.- Parameters:
fieldName
- the name of the new field.child
- the value of the new field.- Throws:
java.lang.NullPointerException
- iffieldName
isnull
.ContainedValueException
- ifchild
is already part of a container.java.lang.IllegalArgumentException
- ifelement
is anIonDatagram
.
-
put
ValueFactory put(java.lang.String fieldName)
Provides a factory that when invoked constructs a new value andput
s it into this struct using the givenfieldName
.These two lines are equivalent:
str.put("f").newInt(3); str.put("f", str.getSystem().newInt(3));
- Throws:
java.lang.NullPointerException
- iffieldName
isnull
.- See Also:
put(String, IonValue)
-
putAll
void putAll(java.util.Map<? extends java.lang.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 callingput(k, v)
on this struct once for each mapping from keyk
to valuev
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:
java.lang.NullPointerException
- if the given map is null.ContainedValueException
- if any values in the map are already part of anIonContainer
(even this one).
-
add
void add(java.lang.String fieldName, IonValue child) throws ContainedValueException
Adds a new field to this struct. If this isnull.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:
java.lang.NullPointerException
- iffieldName
orchild
isnull
.ContainedValueException
- ifchild
is already part of a container.java.lang.IllegalArgumentException
- ifelement
is anIonDatagram
.
-
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 isnull.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:
java.lang.NullPointerException
- iffieldName
orchild
isnull
.ContainedValueException
- ifchild
is already part of a container.java.lang.IllegalArgumentException
- ifelement
is anIonDatagram
.
-
add
ValueFactory add(java.lang.String fieldName)
Provides a factory that when invoked constructs a new value andadd
s it to this struct using the givenfieldName
.These two lines are equivalent:
str.add("f").newInt(3); str.add("f", str.getSystem().newInt(3));
- Throws:
java.lang.NullPointerException
- iffieldName
isnull
.- See Also:
add(String, IonValue)
-
remove
IonValue remove(java.lang.String fieldName)
Removes a field by name, returning a value that was previously associated with the field, ornull
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(java.lang.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:
java.lang.NullPointerException
- iffieldNames
, or any element within it, isnull
.
-
retainAll
boolean retainAll(java.lang.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 infieldNames
.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:
java.lang.NullPointerException
- iffieldNames
, or any element within it, isnull
.
-
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 instanceIonValue.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 useValueFactory.clone(IonValue)
instead.- Specified by:
clone
in interfaceIonContainer
- Specified by:
clone
in interfaceIonValue
- Throws:
UnknownSymbolException
- if any part of this value has unknown text but known Sid for its field name, annotation or symbol.
-
cloneAndRemove
IonStruct cloneAndRemove(java.lang.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(java.lang.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:
java.lang.NullPointerException
- iffieldNames
, or any element within it, isnull
.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()
-
-