Package com.amazon.ion

Interface ValueFactory

All Known Subinterfaces:

_Private_IonSystem, _Private_ValueFactory, IonSystem

All Known Implementing Classes:

_Private_CurriedValueFactory

public interface ValueFactory

The factory for all IonValues.

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

Method Summary

Modifier and Type	Method	Description
<T extends IonValue> T	clone(T value)	Creates a deep copy of an Ion value.
IonBlob	newBlob(byte[] value)	Constructs a new Ion blob instance, copying bytes from an array.
IonBlob	newBlob(byte[] value, int offset, int length)	Constructs a new Ion blob, copying bytes from part of an array.
IonBool	newBool(boolean value)	Constructs a new bool instance with the given value.
IonBool	newBool(java.lang.Boolean value)	Constructs a new bool instance with the given value.
IonClob	newClob(byte[] value)	Constructs a new Ion clob instance from a byte array.
IonClob	newClob(byte[] value, int offset, int length)	Constructs a new Ion clob, copying bytes from part of an array.
IonDecimal	newDecimal(double value)	Constructs a new Ion decimal instance from a Java double.
IonDecimal	newDecimal(long value)	Constructs a new Ion decimal instance from a Java long.
IonDecimal	newDecimal(java.math.BigDecimal value)	Constructs a new Ion decimal instance from a Java BigDecimal.
IonDecimal	newDecimal(java.math.BigInteger value)	Constructs a new Ion decimal instance from a Java BigInteger.
IonList	newEmptyList()	Constructs a new empty (not null) list instance.
IonSexp	newEmptySexp()	Constructs a new empty (not null) sexp instance.
IonStruct	newEmptyStruct()	Constructs a new empty (not null) struct instance.
IonFloat	newFloat(double value)	Constructs a new Ion float instance from a Java double.
IonFloat	newFloat(long value)	Constructs a new Ion float instance from a Java long.
IonInt	newInt(int value)	Constructs a new int instance with the given value.
IonInt	newInt(long value)	Constructs a new int instance with the given value.
IonInt	newInt(java.lang.Number value)	Constructs a new int instance with the given value.
IonList	newList(int[] values)	Constructs a new list with given int children.
IonList	newList(long[] values)	Constructs a new list with given long child elements.
IonList	newList(IonSequence child)	Constructs a new list with the given child.
IonList	newList(IonValue... children)	Constructs a new list with the given children.
IonList	newList(java.util.Collection<? extends IonValue> values)	Deprecated. This method can be invoked (accidentally and incorrectly) with an IonSequence! Use either newList(IonValue...) or newList().addAll(Collection).
IonNull	newNull()	Constructs a new null.null instance.
IonValue	newNull(IonType type)	Constructs a new Ion null value with the given type.
IonBlob	newNullBlob()	Constructs a new null.blob instance.
IonBool	newNullBool()	Constructs a new null.bool instance.
IonClob	newNullClob()	Constructs a new null.clob instance.
IonDecimal	newNullDecimal()	Constructs a new null.decimal instance.
IonFloat	newNullFloat()	Constructs a new null.float instance.
IonInt	newNullInt()	Constructs a new null.int instance.
IonList	newNullList()	Constructs a new null.list instance.
IonSexp	newNullSexp()	Constructs a new null.sexp instance.
IonString	newNullString()	Constructs a new null.string instance.
IonStruct	newNullStruct()	Constructs a new null.struct instance.
IonSymbol	newNullSymbol()	Constructs a new null.symbol instance.
IonTimestamp	newNullTimestamp()	Constructs a new null.timestamp instance.
IonSexp	newSexp(int[] values)	Constructs a new sexp with given int child values.
IonSexp	newSexp(long[] values)	Constructs a new sexp with given long child elements.
IonSexp	newSexp(IonSequence child)	Constructs a new sexp with the given child.
IonSexp	newSexp(IonValue... children)	Constructs a new sexp with given child elements.
IonSexp	newSexp(java.util.Collection<? extends IonValue> values)	Deprecated. This method can be invoked (accidentally and incorrectly) with an IonSequence! Use either newSexp(IonValue...) or newSexp().addAll(Collection).
IonString	newString(java.lang.String value)	Constructs a new Ion string with the given value.
IonSymbol	newSymbol(SymbolToken value)	Constructs a new Ion symbol with the given symbol token.
IonSymbol	newSymbol(java.lang.String value)	Constructs a new Ion symbol with the given value.
IonTimestamp	newTimestamp(Timestamp value)	Constructs a new timestamp instance with the given value.

Method Detail

newNullBlob

IonBlob newNullBlob()

Constructs a new null.blob instance.

newBlob

IonBlob newBlob(byte[] value)

Constructs a new Ion blob instance, copying bytes from an array.

Parameters:

value - the data for the new blob, to be copied from the given array into the new instance. May be null to create a null.blob value.

newBlob

IonBlob newBlob(byte[] value,
                int offset,
                int length)

Constructs a new Ion blob, copying bytes from part of an array.

This method copies length bytes from the given array into the new value, starting at the given offset in the array.

Parameters:

value - the data for the new blob, to be copied from the given array into the new instance. May be null to create a null.blob value.

offset - the offset within the array of the first byte to copy; must be non-negative and no larger than bytes.length.

length - the number of bytes to be copied from the given array; must be non-negative and no larger than bytes.length - offset.

Throws:

java.lang.IndexOutOfBoundsException - if the preconditions on the offset and length parameters are not met.

newNullBool

IonBool newNullBool()

Constructs a new null.bool instance.

newBool

IonBool newBool(boolean value)

Constructs a new bool instance with the given value.

Parameters:

value - the new bool's value.

Returns:

a bool with IonBool.booleanValue() == value.

newBool

IonBool newBool(java.lang.Boolean value)

Constructs a new bool instance with the given value.

Parameters:

value - the new bool's value. may be null to make null.bool.

newNullClob

IonClob newNullClob()

Constructs a new null.clob instance.

newClob

IonClob newClob(byte[] value)

Constructs a new Ion clob instance from a byte array.

Parameters:

value - the data for the new clob, to be copied from the given array into the new instance. May be null to create a null.clob value.

newClob

IonClob newClob(byte[] value,
                int offset,
                int length)

Constructs a new Ion clob, copying bytes from part of an array.

This method copies length bytes from the given array into the new value, starting at the given offset in the array.

Parameters:

value - the data for the new blob, to be copied from the given array into the new instance. May be null to create a null.clob value.

offset - the offset within the array of the first byte to copy; must be non-negative an no larger than bytes.length.

length - the number of bytes to be copied from the given array; must be non-negative an no larger than bytes.length - offset.

Throws:

java.lang.IndexOutOfBoundsException - if the preconditions on the offset and length parameters are not met.

newNullDecimal

IonDecimal newNullDecimal()

Constructs a new null.decimal instance.

newDecimal

IonDecimal newDecimal(long value)

Constructs a new Ion decimal instance from a Java long.

newDecimal

IonDecimal newDecimal(double value)

Constructs a new Ion decimal instance from a Java double.

Note that this does not generate the exact decimal representation of the double's binary floating-point value as via BigDecimal(double), but instead uses the more predictable behavior of matching the double's string representation as via BigDecimal.valueOf(double).

newDecimal

IonDecimal newDecimal(java.math.BigInteger value)

Constructs a new Ion decimal instance from a Java BigInteger.

newDecimal

IonDecimal newDecimal(java.math.BigDecimal value)

Constructs a new Ion decimal instance from a Java BigDecimal. To create negative zero values, pass a Decimal.

newNullFloat

IonFloat newNullFloat()

Constructs a new null.float instance.

newFloat

IonFloat newFloat(long value)

Constructs a new Ion float instance from a Java long.

newFloat

IonFloat newFloat(double value)

Constructs a new Ion float instance from a Java double.

newNullInt

IonInt newNullInt()

Constructs a new null.int instance.

newInt

IonInt newInt(int value)

Constructs a new int instance with the given value.

Parameters:

value - the new int's value.

newInt

IonInt newInt(long value)

Constructs a new int instance with the given value.

Parameters:

value - the new int's value.

newInt

IonInt newInt(java.lang.Number value)

Constructs a new int instance with the given value. The integer portion of the number is used, any fractional portion is ignored.

Parameters:

value - the new int's value; may be null to make null.int.

newNullList

IonList newNullList()

Constructs a new null.list instance.

newEmptyList

IonList newEmptyList()

Constructs a new empty (not null) list instance.

newList

@Deprecated
IonList newList(java.util.Collection<? extends IonValue> values)
         throws ContainedValueException,
                java.lang.NullPointerException

Deprecated.

This method can be invoked (accidentally and incorrectly) with an IonSequence! Use either newList(IonValue...) or newList().addAll(Collection).

Constructs a new list with given children.

Parameters:

values - the initial set of children. If null, then the new instance will have IonValue.isNullValue() == true.

Throws:

ContainedValueException - if any value in values has IonValue.getContainer() != null.

java.lang.NullPointerException - if any value in values is null.

java.lang.IllegalArgumentException - if any value in values is an IonDatagram.

newList

IonList newList(IonSequence child)
         throws ContainedValueException,
                java.lang.NullPointerException

Constructs a new list with the given child.

This method is temporary until newList(Collection) is removed. It's sole purpose is to avoid the doomed attempt to add all of the parameter's children to the new list; that will always throw ContainedValueException.

Parameters:

child - the initial child of the new list.

Throws:

java.lang.NullPointerException - if child is null.

java.lang.IllegalArgumentException - if child is an IonDatagram.

ContainedValueException - if child has IonValue.getContainer() != null.

newList

IonList newList(IonValue... children)
         throws ContainedValueException,
                java.lang.NullPointerException

Constructs a new list with the given children.

Some edge cases are worth examples:

    factory.newList();                     // returns []
    factory.newList((IonValue[]) null);    // returns null.list

For clarity, applications should prefer newEmptyList() and newNullList() instead.

Parameters:

children - the initial sequence of children. If null, then the new instance will have IonValue.isNullValue() == true.

Throws:

java.lang.NullPointerException - if any child is null.

java.lang.IllegalArgumentException - if any child is an IonDatagram.

ContainedValueException - if any child has IonValue.getContainer() != null.

newList

IonList newList(int[] values)

Constructs a new list with given int children.

Parameters:

values - the initial set of child values. If null, then the new instance will have IonValue.isNullValue() == true. Otherwise, the resulting sequence will contain new IonInts with the given values.

Returns:

a new list where each element is an IonInt.

newList

IonList newList(long[] values)

Constructs a new list with given long child elements.

Parameters:

values - the initial set of child values. If null, then the new instance will have IonValue.isNullValue() == true. Otherwise, the resulting sequence will contain new IonInts with the given values.

Returns:

a new list where each element is an IonInt.

newNull

IonNull newNull()

Constructs a new null.null instance.

newNull

IonValue newNull(IonType type)

Constructs a new Ion null value with the given type.

Parameters:

type - must not be Java null, but it may be IonType.NULL.

Returns:

a new value such that IonValue.isNullValue() is true.

newNullSexp

IonSexp newNullSexp()

Constructs a new null.sexp instance.

newEmptySexp

IonSexp newEmptySexp()

Constructs a new empty (not null) sexp instance.

newSexp

@Deprecated
IonSexp newSexp(java.util.Collection<? extends IonValue> values)
         throws ContainedValueException,
                java.lang.NullPointerException

Deprecated.

This method can be invoked (accidentally and incorrectly) with an IonSequence! Use either newSexp(IonValue...) or newSexp().addAll(Collection).

Constructs a new sexp with given child elements.

Parameters:

values - the initial set of children. If null, then the new instance will have IonValue.isNullValue() == true.

Throws:

ContainedValueException - if any value in values has IonValue.getContainer() != null.

java.lang.NullPointerException - if any value in values is null.

java.lang.IllegalArgumentException - if any value in values is an IonDatagram.

newSexp

IonSexp newSexp(IonSequence child)
         throws ContainedValueException,
                java.lang.NullPointerException

Constructs a new sexp with the given child.

This method is temporary until newSexp(Collection) is removed. It's sole purpose is to avoid the doomed attempt to add all of the parameter's children to the new sequence; that will always throw ContainedValueException.

Parameters:

child - the initial child of the new sexp.

Throws:

java.lang.NullPointerException - if child is null.

java.lang.IllegalArgumentException - if child is an IonDatagram.

ContainedValueException - if child has IonValue.getContainer() != null.

newSexp

IonSexp newSexp(IonValue... children)
         throws ContainedValueException,
                java.lang.NullPointerException

Constructs a new sexp with given child elements.

Some edge cases are worth examples:

    factory.newSexp();                     // returns ()
    factory.newSexp((IonValue[]) null);    // returns null.sexp

For clarity, applications should prefer newEmptySexp() and newNullSexp() instead.

Parameters:

children - the initial set of children. If null, then the new instance will have IonValue.isNullValue() == true.

Throws:

java.lang.NullPointerException - if any child is null.

java.lang.IllegalArgumentException - if any child is an IonDatagram.

ContainedValueException - if any child has IonValue.getContainer() != null.

newSexp

IonSexp newSexp(int[] values)

Constructs a new sexp with given int child values.

Parameters:

values - the initial set of child values. If null, then the new instance will have IonValue.isNullValue() == true. Otherwise, the resulting sequence will contain new IonInts with the given values.

Returns:

a new sexp where each element is an IonInt.

newSexp

IonSexp newSexp(long[] values)

Constructs a new sexp with given long child elements.

Parameters:

values - the initial set of child values. If null, then the new instance will have IonValue.isNullValue() == true. Otherwise, the resulting sequence will contain new IonInts with the given values.

Returns:

a new sexp where each element is an IonInt.

newNullString

IonString newNullString()

Constructs a new null.string instance.

newString

IonString newString(java.lang.String value)

Constructs a new Ion string with the given value.

Parameters:

value - the text of the new string; may be null to make null.string.

newNullStruct

IonStruct newNullStruct()

Constructs a new null.struct instance.

newEmptyStruct

IonStruct newEmptyStruct()

Constructs a new empty (not null) struct instance.

newNullSymbol

IonSymbol newNullSymbol()

Constructs a new null.symbol instance.

newSymbol

IonSymbol newSymbol(java.lang.String value)

Constructs a new Ion symbol with the given value.

Parameters:

value - the text of the symbol; may be null to make null.symbol.

newSymbol

IonSymbol newSymbol(SymbolToken value)

Constructs a new Ion symbol with the given symbol token.

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:

value - the text and/or SID of the symbol; may be null to make null.symbol.

newNullTimestamp

IonTimestamp newNullTimestamp()

Constructs a new null.timestamp instance.

newTimestamp

IonTimestamp newTimestamp(Timestamp value)

Constructs a new timestamp instance with the given value.

Parameters:

value - may be null to make null.timestamp.

clone

<T extends IonValue> T clone(T value)
                      throws IonException

Creates a deep copy of an Ion value. This method can properly clone IonDatagrams.

The given value can be in the context of any ValueFactory, and the result will be in the context of this one. This allows you to shift data from one factory instance to another.

Parameters:

value - the value to copy.

Returns:

a deep copy of value, with no container.

Throws:

java.lang.NullPointerException - if value is null.

IonException - if there's a problem creating the clone.

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

See Also:

IonValue.clone()