ValueFactory (ion-java 1.11.7 API)

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

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and 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(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`.
`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`.
`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(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)`.
`IonList`	`newList(int[] values)` Constructs a new `list` with given `int` children.
`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(long[] values)` Constructs a new `list` with given `long` child elements.
`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(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)`.
`IonSexp`	`newSexp(int[] values)` Constructs a new `sexp` with given `int` child values.
`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(long[] values)` Constructs a new `sexp` with given `long` child elements.
`IonString`	`newString(java.lang.String value)` Constructs a new Ion string with the given value.
`IonSymbol`	`newSymbol(java.lang.String value)` Constructs a new Ion symbol with the given value.
`IonSymbol`	`newSymbol(SymbolToken value)` Constructs a new Ion symbol with the given symbol token.
`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()

Interface ValueFactory

Method Summary

Method Detail

newNullBlob

newBlob

newBlob

newNullBool

newBool

newBool

newNullClob

newClob

newClob

newNullDecimal

newDecimal

newDecimal

newDecimal

newDecimal

newNullFloat

newFloat

newFloat

newNullInt

newInt

newInt

newInt

newNullList

newEmptyList

newList

newList

newList

newList

newList

newNull

newNull

newNullSexp

newEmptySexp

newSexp

newSexp

newSexp

newSexp

newSexp

newNullString

newString

newNullStruct

newEmptyStruct

newNullSymbol

newSymbol

newSymbol

newNullTimestamp

newTimestamp

clone