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 Details

    • 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:
      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(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:
      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(BigInteger value)
      Constructs a new Ion decimal instance from a Java BigInteger.

    • newDecimal

      IonDecimal newDecimal(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(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(Collection<? extends IonValue> values) throws ContainedValueException, 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.
      NullPointerException - if any value in values is null.
      IllegalArgumentException - if any value in values is an IonDatagram.

    • newList

      IonList newList(IonSequence child) throws ContainedValueException, 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:
      NullPointerException - if child is null.
      IllegalArgumentException - if child is an IonDatagram.
      ContainedValueException - if child has IonValue.getContainer() != null.

    • newList

      IonList newList(IonValue... children) throws ContainedValueException, 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:
      NullPointerException - if any child is null.
      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(Collection<? extends IonValue> values) throws ContainedValueException, 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.
      NullPointerException - if any value in values is null.
      IllegalArgumentException - if any value in values is an IonDatagram.

    • newSexp

      IonSexp newSexp(IonSequence child) throws ContainedValueException, 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:
      NullPointerException - if child is null.
      IllegalArgumentException - if child is an IonDatagram.
      ContainedValueException - if child has IonValue.getContainer() != null.

    • newSexp

      IonSexp newSexp(IonValue... children) throws ContainedValueException, 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:
      NullPointerException - if any child is null.
      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(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(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:
      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: