Interface ValueFactory
- All Known Subinterfaces:
_Private_IonSystem
,_Private_ValueFactory
,IonSystem
- All Known Implementing Classes:
_Private_CurriedValueFactory
IonValue
s.
WARNING: This interface should not be implemented or extended by code outside of this library.
-
Method Summary
Modifier and TypeMethodDescription<T extends IonValue>
Tclone
(T value) Creates a deep copy of an Ion value.newBlob
(byte[] value) Constructs a new Ionblob
instance, copying bytes from an array.newBlob
(byte[] value, int offset, int length) Constructs a new Ionblob
, copying bytes from part of an array.newBool
(boolean value) Constructs a newbool
instance with the given value.Constructs a newbool
instance with the given value.newClob
(byte[] value) Constructs a new Ionclob
instance from a byte array.newClob
(byte[] value, int offset, int length) Constructs a new Ionclob
, copying bytes from part of an array.newDecimal
(double value) Constructs a new Iondecimal
instance from a Javadouble
.newDecimal
(long value) Constructs a new Iondecimal
instance from a Javalong
.newDecimal
(BigDecimal value) Constructs a new Iondecimal
instance from a JavaBigDecimal
.newDecimal
(BigInteger value) Constructs a new Iondecimal
instance from a JavaBigInteger
.Constructs a new empty (not null)list
instance.Constructs a new empty (not null)sexp
instance.Constructs a new empty (not null)struct
instance.newFloat
(double value) Constructs a new Ionfloat
instance from a Javadouble
.newFloat
(long value) Constructs a new Ionfloat
instance from a Javalong
.newInt
(int value) Constructs a newint
instance with the given value.newInt
(long value) Constructs a newint
instance with the given value.Constructs a newint
instance with the given value.newList
(int[] values) Constructs a newlist
with givenint
children.newList
(long[] values) Constructs a newlist
with givenlong
child elements.newList
(IonSequence child) Constructs a newlist
with the given child.Constructs a newlist
with the given children.newList
(Collection<? extends IonValue> values) Deprecated.newNull()
Constructs a newnull.null
instance.Constructs a new Ion null value with the given type.Constructs a newnull.blob
instance.Constructs a newnull.bool
instance.Constructs a newnull.clob
instance.Constructs a newnull.decimal
instance.Constructs a newnull.float
instance.Constructs a newnull.int
instance.Constructs a newnull.list
instance.Constructs a newnull.sexp
instance.Constructs a newnull.string
instance.Constructs a newnull.struct
instance.Constructs a newnull.symbol
instance.Constructs a newnull.timestamp
instance.newSexp
(int[] values) Constructs a newsexp
with givenint
child values.newSexp
(long[] values) Constructs a newsexp
with givenlong
child elements.newSexp
(IonSequence child) Constructs a newsexp
with the given child.Constructs a newsexp
with given child elements.newSexp
(Collection<? extends IonValue> values) Deprecated.This method can be invoked (accidentally and incorrectly) with anIonSequence
! Use eithernewSexp(IonValue...)
ornewSexp()
.addAll(Collection)
.Constructs a new Ion string with the given value.newSymbol
(SymbolToken value) Constructs a new Ion symbol with the given symbol token.Constructs a new Ion symbol with the given value.newTimestamp
(Timestamp value) Constructs a newtimestamp
instance with the given value.
-
Method Details
-
newNullBlob
IonBlob newNullBlob()Constructs a newnull.blob
instance. -
newBlob
Constructs a new Ionblob
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 benull
to create anull.blob
value.
-
newBlob
Constructs a new Ionblob
, 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 benull
to create anull.blob
value.offset
- the offset within the array of the first byte to copy; must be non-negative and no larger thanbytes.length
.length
- the number of bytes to be copied from the given array; must be non-negative and no larger thanbytes.length - offset
.- Throws:
IndexOutOfBoundsException
- if the preconditions on theoffset
andlength
parameters are not met.
-
newNullBool
IonBool newNullBool()Constructs a newnull.bool
instance. -
newBool
Constructs a newbool
instance with the given value.- Parameters:
value
- the newbool
's value.- Returns:
- a bool with
.IonBool.booleanValue()
== value
-
newBool
Constructs a newbool
instance with the given value.- Parameters:
value
- the newbool
's value. may benull
to makenull.bool
.
-
newNullClob
IonClob newNullClob()Constructs a newnull.clob
instance. -
newClob
Constructs a new Ionclob
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 benull
to create anull.clob
value.
-
newClob
Constructs a new Ionclob
, 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 benull
to create anull.clob
value.offset
- the offset within the array of the first byte to copy; must be non-negative an no larger thanbytes.length
.length
- the number of bytes to be copied from the given array; must be non-negative an no larger thanbytes.length - offset
.- Throws:
IndexOutOfBoundsException
- if the preconditions on theoffset
andlength
parameters are not met.
-
newNullDecimal
IonDecimal newNullDecimal()Constructs a newnull.decimal
instance. -
newDecimal
Constructs a new Iondecimal
instance from a Javalong
. -
newDecimal
Constructs a new Iondecimal
instance from a Javadouble
.Note that this does not generate the exact decimal representation of the
double
's binary floating-point value as viaBigDecimal(double)
, but instead uses the more predictable behavior of matching the double's string representation as viaBigDecimal.valueOf(double)
. -
newDecimal
Constructs a new Iondecimal
instance from a JavaBigInteger
. -
newDecimal
Constructs a new Iondecimal
instance from a JavaBigDecimal
. To create negative zero values, pass aDecimal
. -
newNullFloat
IonFloat newNullFloat()Constructs a newnull.float
instance. -
newFloat
Constructs a new Ionfloat
instance from a Javalong
. -
newFloat
Constructs a new Ionfloat
instance from a Javadouble
. -
newNullInt
IonInt newNullInt()Constructs a newnull.int
instance. -
newInt
Constructs a newint
instance with the given value.- Parameters:
value
- the new int's value.
-
newInt
Constructs a newint
instance with the given value.- Parameters:
value
- the new int's value.
-
newInt
Constructs a newint
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 benull
to makenull.int
.
-
newNullList
IonList newNullList()Constructs a newnull.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 anIonSequence
! Use eithernewList(IonValue...)
ornewList()
.addAll(Collection)
.Constructs a newlist
with given children.- Parameters:
values
- the initial set of children. Ifnull
, then the new instance will have
.IonValue.isNullValue()
== true- Throws:
ContainedValueException
- if any value invalues
has
.IonValue.getContainer()
!= nullNullPointerException
- if any value invalues
is null.IllegalArgumentException
- if any value invalues
is anIonDatagram
.
-
newList
Constructs a newlist
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 throwContainedValueException
.- Parameters:
child
- the initial child of the new list.- Throws:
NullPointerException
- ifchild
is null.IllegalArgumentException
- ifchild
is anIonDatagram
.ContainedValueException
- ifchild
has
.IonValue.getContainer()
!= null
-
newList
Constructs a newlist
with the given children.Some edge cases are worth examples:
factory.newList(); // returns [] factory.newList((IonValue[]) null); // returns null.list
For clarity, applications should prefernewEmptyList()
andnewNullList()
instead.- Parameters:
children
- the initial sequence of children. Ifnull
, then the new instance will have
.IonValue.isNullValue()
== true- Throws:
NullPointerException
- if any child is null.IllegalArgumentException
- if any child is anIonDatagram
.ContainedValueException
- if any child has
.IonValue.getContainer()
!= null
-
newList
Constructs a newlist
with givenint
children.- Parameters:
values
- the initial set of child values. Ifnull
, then the new instance will have
. Otherwise, the resulting sequence will contain newIonValue.isNullValue()
== trueIonInt
s with the given values.- Returns:
- a new list where each element is an
IonInt
.
-
newList
Constructs a newlist
with givenlong
child elements.- Parameters:
values
- the initial set of child values. Ifnull
, then the new instance will have
. Otherwise, the resulting sequence will contain newIonValue.isNullValue()
== trueIonInt
s with the given values.- Returns:
- a new list where each element is an
IonInt
.
-
newNull
IonNull newNull()Constructs a newnull.null
instance. -
newNull
Constructs a new Ion null value with the given type.- Parameters:
type
- must not be Java null, but it may beIonType.NULL
.- Returns:
- a new value such that
IonValue.isNullValue()
istrue
.
-
newNullSexp
IonSexp newNullSexp()Constructs a newnull.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 anIonSequence
! Use eithernewSexp(IonValue...)
ornewSexp()
.addAll(Collection)
.Constructs a newsexp
with given child elements.- Parameters:
values
- the initial set of children. Ifnull
, then the new instance will have
.IonValue.isNullValue()
== true- Throws:
ContainedValueException
- if any value invalues
has
.IonValue.getContainer()
!= nullNullPointerException
- if any value invalues
is null.IllegalArgumentException
- if any value invalues
is anIonDatagram
.
-
newSexp
Constructs a newsexp
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 throwContainedValueException
.- Parameters:
child
- the initial child of the new sexp.- Throws:
NullPointerException
- ifchild
is null.IllegalArgumentException
- ifchild
is anIonDatagram
.ContainedValueException
- ifchild
has
.IonValue.getContainer()
!= null
-
newSexp
Constructs a newsexp
with given child elements.Some edge cases are worth examples:
factory.newSexp(); // returns () factory.newSexp((IonValue[]) null); // returns null.sexp
For clarity, applications should prefernewEmptySexp()
andnewNullSexp()
instead.- Parameters:
children
- the initial set of children. Ifnull
, then the new instance will have
.IonValue.isNullValue()
== true- Throws:
NullPointerException
- if any child is null.IllegalArgumentException
- if any child is anIonDatagram
.ContainedValueException
- if any child has
.IonValue.getContainer()
!= null
-
newSexp
Constructs a newsexp
with givenint
child values.- Parameters:
values
- the initial set of child values. Ifnull
, then the new instance will have
. Otherwise, the resulting sequence will contain newIonValue.isNullValue()
== trueIonInt
s with the given values.- Returns:
- a new sexp where each element is an
IonInt
.
-
newSexp
Constructs a newsexp
with givenlong
child elements.- Parameters:
values
- the initial set of child values. Ifnull
, then the new instance will have
. Otherwise, the resulting sequence will contain newIonValue.isNullValue()
== trueIonInt
s with the given values.- Returns:
- a new sexp where each element is an
IonInt
.
-
newNullString
IonString newNullString()Constructs a newnull.string
instance. -
newString
Constructs a new Ion string with the given value.- Parameters:
value
- the text of the new string; may benull
to makenull.string
.
-
newNullStruct
IonStruct newNullStruct()Constructs a newnull.struct
instance. -
newEmptyStruct
IonStruct newEmptyStruct()Constructs a new empty (not null)struct
instance. -
newNullSymbol
IonSymbol newNullSymbol()Constructs a newnull.symbol
instance. -
newSymbol
Constructs a new Ion symbol with the given value.- Parameters:
value
- the text of the symbol; may benull
to makenull.symbol
.
-
newSymbol
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 benull
to makenull.symbol
.
-
newNullTimestamp
IonTimestamp newNullTimestamp()Constructs a newnull.timestamp
instance. -
newTimestamp
Constructs a newtimestamp
instance with the given value.- Parameters:
value
- may benull
to makenull.timestamp
.
-
clone
Creates a deep copy of an Ion value. This method can properly cloneIonDatagram
s.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
- ifvalue
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:
-
IonSequence
! Use eithernewList(IonValue...)
ornewList()
.addAll(Collection)
.