com.programix.value
Interface Value

All Known Implementing Classes:

AbstractValue

public interface Value

Encapsulates a generic value with accessors to read the data as different data types. Note that depending on the encapsulated value, it might not be possible to read the value as all of the different data types (however, getString(), getRawString(), and getObject() will always return a value safely).

ValueException is potentially thrown from some of the methods on Value. It is used to indicate trouble—usually trouble interpreting the value as particular type. For example, if "abc" is returned from getString(), attempting to call getInt() would result in getInt() throwing a ValueException as no integer value can be parsed. ValueException is a subclass of RuntimeException so it does not have to be explicitly caught.

RangeValueException is potentially thrown from some of the methods on Value. This subclass of ValueException is used to specifically indicate that the value does not fit into the acceptable range. For example, if "5000000000" is returned from getString(), attempting to call getInt() would result in getInt() throwing a RangeValueException as this value is too large to fit into an int. RangleValueException is a subclass of RuntimeException so it does not have to be explicitly caught.

The documentation for many of the methods have code snippets labeled as "equivalent to". An implementation of Value may actually implement the method in a more efficient manner as appropriate.

Most implementations ensure that each instance is immutable (that is, the internal value can NOT be changed after construction). If mutability is needed (or can't be avoided), the isMutable() method returns true. See isMutable() for details.

Author:

Paul Hyde

Method Summary

BigDecimal	getBigDecimal() Returns the result as a BigDecimal.
BigDecimal	getBigDecimalOrNull() Returns the result as a BigDecimal or null if the value is empty.
byte	getByte() Returns the result as a rounded off byte value.
Byte	getByteNumber() Returns the result as a rounded off Byte value.
Byte	getByteNumberOrNull() Returns the result as a Byte or null if the value is empty.
byte[]	getBytes() Returns the encapsulated value interpreted as a byte[].
InputStream	getBytesAsStream() Returns the encapsulated value interpreted as bytes that are readable from InputStream.
DateTime	getDateTime() Returns the encapsulated value interpreted as a DateTime assuming the UTC timezone if necessary.
DateTime	getDateTime(TimeZone defaultTimeZone) Returns the encapsulated value interpreted as a DateTime assuming the specified timezone if necessary.
DateTime	getDateTimeLocal() Returns the encapsulated value interpreted as a DateTime assuming the local VM's timezone if necessary.
DateTime	getDateTimeLocalOrNull() Returns the result as a DateTime or null if the value is empty (using the local VM's timezone for interpretation if necessary).
DateTime	getDateTimeOrNull() Returns the result as a DateTime or null if the value is empty (using the UTC timezone for interpretation if necessary).
DateTime	getDateTimeOrNull(TimeZone defaultTimeZone) Returns the result as a DateTime or null if the value is empty (using the specified timezone for interpretation if necessary).
double	getDouble() Returns the result as a double value.
Double	getDoubleNumber() Returns the result as a Double value.
Double	getDoubleNumberOrNull() Returns the result as an Double or null if the value is empty.
float	getFloat() Returns the result as a float value.
Float	getFloatNumber() Returns the result as a Float value.
Float	getFloatNumberOrNull() Returns the result as an Float or null if the value is empty.
int	getInt() Returns the result as a rounded off int value.
Integer	getIntegerNumber() Returns the result as a rounded off Integer value.
Integer	getIntegerNumberOrNull() Returns the result as an Integer or null if the value is empty.
long	getLong() Returns the result as a rounded off long value.
Long	getLongNumber() Returns the result as a rounded off Long value.
Long	getLongNumberOrNull() Returns the result as a Long or null if the value is empty.
Number	getNumber() Returns the encapsulated value interpreted a Number value.
Number	getNumberOrNull() Returns the result as a Number or null if the value is empty.
Object	getObject() Returns the encapsulated value as a generic Object reference.
<T> T	getObject(Class<T> targetType) Returns the encapsulated value as a generic Object reference that is guaranteed to be able to be explicitly cast into the specified targetType.
<T> T	getObjectOrNull(Class<T> targetType) Returns the encapsulated value as a generic Object reference or null if the value is empty.
PlainDate	getPlainDate() Returns the encapsulated value interpreted as a PlainDate.
PlainDate	getPlainDateOrNull() Returns the result as a PlainDate or null if the value is empty.
String	getRawString() Returns the encapsulated value as a String value without trimming leading and trailing whitespace.
short	getShort() Returns the result as a rounded off short value.
Short	getShortNumber() Returns the result as a rounded off Short value.
Short	getShortNumberOrNull() Returns the result as a Short or null if the value is empty.
String	getString() Returns the encapsulated value as a String value after trimming leading and trailing whitespace.
String	getStringOrNull() Returns the result as a String or null if the value is empty.
TriState	getTriState() Returns the encapsulated value interpreted as a TriState.
boolean	isDateTime() Returns true if this value is, or if it can be interpreted as, a DateTime.
boolean	isEmpty() Returns true if the encapsulated value is either null, a zero-length String, or a String of all whitespace.
boolean	isFalse() Returns true if the encapsulated value can not be interpreted as something considered to be "true".
boolean	isMutable() Returns true if the public view of this Value might change over time.
boolean	isNotDateTime() Returns true if the encapsulated value can not be interpreted as a DateTime value.
boolean	isNotEmpty() Returns true if the encapsulated value is NOT empty.
boolean	isNotNull() Returns true if the encapsulated value is NOT null.
boolean	isNotNumeric() Returns true if the encapsulated value can not be interpreted as a numeric value.
boolean	isNotPlainDate() Returns true if the encapsulated value can not be interpreted as a PlainDate value.
boolean	isNotType(Class<?> targetType) Returns true if the result of getObject() is null or can not be cast into the specified type.
boolean	isNotTypeByteArray() Returns true if the result of getObject() is not an object of the type byte[].
boolean	isNotTypeDateTime() Returns true if the result of getObject() is not an object of the type DateTime.
boolean	isNotTypeNumber() Returns true if the result of getObject() is not an object of the type Number.
boolean	isNotTypePlainDate() Returns true if the result of getObject() is not an object of the type PlainDate.
boolean	isNull() Returns true if the encapsulated value is null.
boolean	isNumeric() Returns true if the encapsulated value can be interpreted as a number.
boolean	isPlainDate() Returns true if this value is, or if it can be interpreted as, a PlainDate.
boolean	isTrue() Returns the result as a boolean value.
boolean	isType(Class<?> targetType) Returns true if the result of getObject() is not null and can be cast into the specified type.
boolean	isTypeByteArray() Returns true if the result of getObject() is not null and can be cast to the type byte[].
boolean	isTypeDateTime() Returns true if the result of getObject() is not null and can be cast to the type DateTime.
boolean	isTypeNumber() Returns true if the result of getObject() is not null and can be cast to the type Number.
boolean	isTypePlainDate() Returns true if the result of getObject() is not null and can be cast to the type PlainDate.

Method Detail

getObject

Object getObject()

Returns the encapsulated value as a generic Object reference. If the caller knows the actual type that should be returned, the calling code can attempt to explicitly cast the value returned (the isType(Class target) method can be used to test the type first, if desired). If the value stored internally is null, then null will be returned.

getObject

<T> T getObject(Class<T> targetType)
            throws ValueException,
                   IllegalArgumentException

Returns the encapsulated value as a generic Object reference that is guaranteed to be able to be explicitly cast into the specified targetType. If the internal value is not of the specified type, a ValueException is thrown with details in its message about the actual type of the internal object. If the value stored internally is null, then a ValueException will be thrown. Equivalent to:

 if ( isNotType(targetType) ) {
     throw new ValueException( //...
 }

 return getObject();
 

Parameters:

targetType - type to check against, must not be null.

Returns:

the encapsulated value

Throws:

ValueException - if the encapsulated value is not of the specified type, or if it is null.

IllegalArgumentException - if targetType is null.

getObjectOrNull

<T> T getObjectOrNull(Class<T> targetType)
                  throws ValueException,
                         IllegalArgumentException

Returns the encapsulated value as a generic Object reference or null if the value is empty. The returned value is guaranteed to be able to be explicitly cast into the specified targetType (note: null can be cast into any type). If the internal value is not empty and is not of the specified type, a ValueException is thrown with details in its message about the actual type of the internal object. Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getObject(targetType);
 }
 

Parameters:

targetType - type to check against, must not be null.

Returns:

the encapsulated value, or null if empty.

Throws:

ValueException - if the encapsulated value is not empty and is not of the specified type.

IllegalArgumentException - if targetType is null. Note that ValueException and IllegalArgumentException are both a RuntimeException so neither has to be explicitly caught.

isNull

boolean isNull()

Returns true if the encapsulated value is null. Equivalent to:

 return getObject() == null;
 

isNotNull

boolean isNotNull()

Returns true if the encapsulated value is NOT null. Equivalent to:

 return !isNull();
 

isEmpty

boolean isEmpty()

Returns true if the encapsulated value is either null, a zero-length String, or a String of all whitespace. Equivalent to:

 return isNull() || (getString().length() == 0);
 

isNotEmpty

boolean isNotEmpty()

Returns true if the encapsulated value is NOT empty. See isEmpty() for an explanation of empty. Equivalent to:

 return !isEmpty();
 

isType

boolean isType(Class<?> targetType)
               throws IllegalArgumentException

Returns true if the result of getObject() is not null and can be cast into the specified type.

Throws:

IllegalArgumentException - if targetType is null.

isNotType

boolean isNotType(Class<?> targetType)
                  throws IllegalArgumentException

Returns true if the result of getObject() is null or can not be cast into the specified type. Equivalent to:

 return !isType(targetType);
 

Throws:

IllegalArgumentException - if targetType is null.

isTypeNumber

boolean isTypeNumber()

Returns true if the result of getObject() is not null and can be cast to the type Number. Number is the abstract superclass of Byte, Short, Integer, Long, Float, Double, BigDecimal, and BigInteger. This method's test is stricter than isNumeric() (which checks to see if there is any way to interpret the value as a number). Equivalent to:

 return isNotNull() && (getObject() instanceof Number);
 

isNotTypeNumber

boolean isNotTypeNumber()

Returns true if the result of getObject() is not an object of the type Number. Equivalent to:

 return !isTypeNumber();
 

isTypeDateTime

boolean isTypeDateTime()

Returns true if the result of getObject() is not null and can be cast to the type DateTime. This method's test is stricter than isDateTime() (which checks to see if there is any way to interpret the value as a DateTime). Equivalent to:

 return isNotNull() && (getObject() instanceof DateTime);
 

isNotTypeDateTime

boolean isNotTypeDateTime()

Returns true if the result of getObject() is not an object of the type DateTime. Equivalent to:

 return !isTypeDateTime();
 

isTypePlainDate

boolean isTypePlainDate()

Returns true if the result of getObject() is not null and can be cast to the type PlainDate. This method's test is stricter than isPlainDate() (which checks to see if there is any way to interpret the value as a PlainDate). Equivalent to:

 return isNotNull() && (getObject() instanceof PlainDate);
 

isNotTypePlainDate

boolean isNotTypePlainDate()

Returns true if the result of getObject() is not an object of the type PlainDate. Equivalent to:

 return !isTypePlainDate();
 

isTypeByteArray

boolean isTypeByteArray()

Returns true if the result of getObject() is not null and can be cast to the type byte[]. This method's test is stricter than getBytes() and getBytesAsStream() (they always find a way to interpret the value as a byte[]). Equivalent to:

 return isNotNull() && (getObject() instanceof byte[]);
 

isNotTypeByteArray

boolean isNotTypeByteArray()

Returns true if the result of getObject() is not an object of the type byte[]. Equivalent to:

 return !isTypeByteArray();
 

getString

String getString()

Returns the encapsulated value as a String value after trimming leading and trailing whitespace. If the encapsulated value is null, a zero-length String will be returned (null is never returned). Equivalent to:

 Object obj = getObject();
 return (obj == null) ? "" : obj.toString().trim();
 

getStringOrNull

String getStringOrNull()

Returns the result as a String or null if the value is empty. Note that this method returns null if the value is null, a zero-length string, or a string of all whitespace; a string is only returned if there are non-whitespace characters available. Look carefully at isEmpty() and getString(). Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getString();
 }
 

getRawString

String getRawString()

Returns the encapsulated value as a String value without trimming leading and trailing whitespace. If the encapsulated value is null, a zero-length String will be returned (null is never returned). Equivalent to:

 Object obj = getObject();
 return (obj == null) ? "" : obj.toString();
 

isNumeric

boolean isNumeric()

Returns true if the encapsulated value can be interpreted as a number. If getNumber() can be called without a throwing a ValueException, isNumeric returns true. See getNumber() for details. This method's test is more lenient than isTypeNumber() (which only checks to see if the encapsulated object is a subclass of Number).

Equivalent to (although typically implemented more efficiently):

 try {
     getNumber();
     return true;
 } catch ( ValueException x ) {
     return false;
 }
 

isNotNumeric

boolean isNotNumeric()

Returns true if the encapsulated value can not be interpreted as a numeric value. See isNumeric() for an explanation of how numeric is determined. Equivalent to:

 return !isNumeric();
 

getNumber

Number getNumber()
                 throws ValueException

Returns the encapsulated value interpreted a Number value. More specifically:

• If the encapsulated value is a subclass of Number, the value is simply returned.
• If the encapsulated value is a DateTime, a new Long is wrapped around the long returned by getTime().
• If the String returned by getString() is run through StringTools.winnowDecimal() and the result can be successfully parsed by the constructor of BigDecimal, then that BigDecimal is returned.
• If the encapsulated value is null, a ValueException is thrown.

Equivalent to:

 Object obj = getObject();
 if ( obj instanceof Number ) {
     return (Number) obj;
 } else if ( obj instanceof DateTime ) {
     DateTime dateTime = (DateTime) obj;
     return new Long(dateTime.getTime());
 } else if ( obj == null ) {
     throw new ValueException(//...
 }

 try {
     return new BigDecimal(StringTools.winnowDecimal(getString()));
 } catch ( NumberFormatException x ) {
     throw new ValueException(x);
 }
 

NOTE: if you really need a BigDecimal, then call getBigDecimal() instead.

Throws:

ValueException - if the encapsulated value can not be interpreted as a numeric value. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getNumberOrNull

Number getNumberOrNull()
                       throws ValueException

Returns the result as a Number or null if the value is empty. Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getNumber();
 }
 

Throws:

ValueException - if the value is not empty and can not be interpreted as a numeric value. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getBigDecimal

BigDecimal getBigDecimal()
                         throws ValueException

Returns the result as a BigDecimal. Equivalent to:

 Number num = getNumber();
 if ( num instanceof BigDecimal ) {
     return (BigDecimal) num;
 }

 try {
     return new BigDecimal(num.toString());
 } catch ( NumberFormatException x ) {
     throw new ValueException( //...
 }
 

Throws:

ValueException - if the value is null or can not be viewed as a BigDecimal. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getBigDecimalOrNull

BigDecimal getBigDecimalOrNull()
                               throws ValueException

Returns the result as a BigDecimal or null if the value is empty. Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getBigDecimal();
 }
 

Throws:

ValueException - if the value is not empty and can not be viewed as a BigDecimal. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getLong

long getLong()
             throws RangeValueException,
                    ValueException

Returns the result as a rounded off long value. Equivalent to:

 return NumberTools.toLong(getNumber());
 

Throws:

RangeValueException - if the value does not fit in the range of valid long values.

ValueException - if the value can not be interpreted as a numeric value.

See Also:

getLongNumber()

getLongNumber

Long getLongNumber()
                   throws RangeValueException,
                          ValueException

Returns the result as a rounded off Long value. Equivalent to:

 return NumberTools.toLongNumber(getNumber());
 

Throws:

RangeValueException - if the value does not fit in the range of valid long values.

ValueException - if the value can not be interpreted as a numeric value.

See Also:

getLong()

getLongNumberOrNull

Long getLongNumberOrNull()
                         throws RangeValueException,
                                ValueException

Returns the result as a Long or null if the value is empty. Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getLongNumber();
 }
 

Throws:

RangeValueException - if the value does not fit in the range of valid long values.

ValueException - if the value is not empty and can not be viewed as a Long. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getInt

int getInt()
           throws RangeValueException,
                  ValueException

Returns the result as a rounded off int value. Equivalent to:

 return NumberTools.toInt(getNumber());
 

Throws:

RangeValueException - if the value does not fit in the range of valid int values.

ValueException - if the value can not be interpreted as a numeric value.

See Also:

getIntegerNumber()

getIntegerNumber

Integer getIntegerNumber()
                         throws RangeValueException,
                                ValueException

Returns the result as a rounded off Integer value. Equivalent to:

 return NumberTools.toIntegerNumber(getNumber());
 

Throws:

RangeValueException - if the value does not fit in the range of valid int values.

ValueException - if the value can not be interpreted as a numeric value.

See Also:

getInt()

getIntegerNumberOrNull

Integer getIntegerNumberOrNull()
                               throws RangeValueException,
                                      ValueException

Returns the result as an Integer or null if the value is empty. Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getIntegerNumber();
 }
 

Throws:

RangeValueException - if the value does not fit in the range of valid int values.

ValueException - if the value is not empty and can not be viewed as a Integer. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getShort

short getShort()
               throws RangeValueException,
                      ValueException

Returns the result as a rounded off short value. Equivalent to:

 return NumberTools.toShort(getNumber());
 

Throws:

RangeValueException - if the value does not fit in the range of valid short values.

ValueException - if the value can not be interpreted as a numeric value.

See Also:

getShortNumber()

getShortNumber

Short getShortNumber()
                     throws RangeValueException,
                            ValueException

Returns the result as a rounded off Short value. Equivalent to:

 return NumberTools.toShortNumber(getNumber());
 

Throws:

RangeValueException - if the value does not fit in the range of valid short values.

ValueException - if the value can not be interpreted as a numeric value.

See Also:

getShort()

getShortNumberOrNull

Short getShortNumberOrNull()
                           throws RangeValueException,
                                  ValueException

Returns the result as a Short or null if the value is empty. Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getShortNumber();
 }
 

Throws:

RangeValueException - if the value does not fit in the range of valid short values.

ValueException - if the value is not empty and can not be viewed as a Short. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getByte

byte getByte()
             throws RangeValueException,
                    ValueException

Returns the result as a rounded off byte value. Equivalent to:

 return NumberTools.toByte(getNumber());
 

Throws:

RangeValueException - if the value does not fit in the range of valid byte values.

ValueException - if the value can not be interpreted as a numeric value.

See Also:

getByteNumber()

getByteNumber

Byte getByteNumber()
                   throws RangeValueException,
                          ValueException

Returns the result as a rounded off Byte value. Equivalent to:

 return NumberTools.toByteNumber(getNumber());
 

Throws:

RangeValueException - if the value does not fit in the range of valid byte values.

ValueException - if the value can not be interpreted as a numeric value.

See Also:

getByte()

getByteNumberOrNull

Byte getByteNumberOrNull()
                         throws RangeValueException,
                                ValueException

Returns the result as a Byte or null if the value is empty. Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getByteNumber();
 }
 

Throws:

RangeValueException - if the value does not fit in the range of valid byte values.

ValueException - if the value is not empty and can not be viewed as a Byte. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getDouble

double getDouble()
                 throws ValueException

Returns the result as a double value. Equivalent to:

 return getNumber().doubleValue();
 

Throws:

ValueException - if the string can not be parsed into a numeric value. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getDoubleNumber

Double getDoubleNumber()
                       throws ValueException

Returns the result as a Double value. Equivalent to:

 return new Double(getDouble());
 

Throws:

ValueException - if the value can not be interpreted as a numeric value. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

See Also:

getDouble()

getDoubleNumberOrNull

Double getDoubleNumberOrNull()
                             throws ValueException

Returns the result as an Double or null if the value is empty. Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getDoubleNumber();
 }
 

Throws:

ValueException - if the value is not empty and can not be viewed as a Double. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getFloat

float getFloat()
               throws ValueException

Returns the result as a float value. Equivalent to:

 return getNumber().floatValue();
 

Throws:

ValueException - if the string can not be parsed into a numeric value. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getFloatNumber

Float getFloatNumber()
                     throws ValueException

Returns the result as a Float value. Equivalent to:

 return new Float(getFloat());
 

Throws:

ValueException - if the value can not be interpreted as a numeric value. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

See Also:

getFloat()

getFloatNumberOrNull

Float getFloatNumberOrNull()
                           throws ValueException

Returns the result as an Float or null if the value is empty. Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getFloatNumber();
 }
 

Throws:

ValueException - if the value is not empty and can not be viewed as a Float. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

isTrue

boolean isTrue()

Returns the result as a boolean value. Returns true if the result of getString() matches (case-insensitively) any one of the following:

     true, t,
     yes, y,
     on,
     1
 

isFalse

boolean isFalse()

Returns true if the encapsulated value can not be interpreted as something considered to be "true". See isTrue() for an explanation of how "true" is interpreted. This method can be thought of more as a "is not true" as opposed to confirming that something is "false" (for example, blank and null are consider to be "not true"). Equivalent to:

 return !isTrue();
 

getTriState

TriState getTriState()

Returns the encapsulated value interpreted as a TriState. More specifically:

• If the encapsulated value is a TriState, the value is simply returned.
• If the encapsulated value is null, then TriState.UNKNOWN is returned.
• If the encapsulated value is a Boolean and that Boolean is holding true, then TriState.YES is returned.
• If the encapsulated value is a Boolean and that Boolean is holding false, then TriState.NO is returned.
• If the result of getString() matches (case-insensitively) any one of the following: "yes", "y", "true", "t", "on", or "1", then TriState.YES is returned.
• If the result of getString() matches (case-insensitively) any one of the following: "no", "n", "false", "f", "off", or "0", then TriState.NO is returned.
• Otherwise, TriState.UNKNOWN is returned.

This method always returns one of the instances of TriState, null is never returned.

Equivalent to:

 Object obj = getObject();
 if ( obj instanceof TriState ) {
     return (TriState) obj;
 } else if ( obj == null ) {
     return TriState.UNKNOWN;
 } else if ( obj instanceof Boolean ) {
     if ( ((Boolean) obj).booleanValue() == true ) {
         return TriState.YES;
     } else {
         return TriState.NO;
     }
 }

 String s = getString();
 if ( "yes".equalsIgnoreCase(s) || "y".equalsIgnoreCase(s) ||
      "true".equalsIgnoreCase(s) || "t".equalsIgnoreCase(s) ||
      "on".equalsIgnoreCase(s) || "1".equals(s) ) {

     return TriState.YES;
 }

 if ( "no".equalsIgnoreCase(s) || "n".equalsIgnoreCase(s) ||
      "false".equalsIgnoreCase(s) || "f".equalsIgnoreCase(s) ||
      "off".equalsIgnoreCase(s) || "0".equals(s) ) {

     return TriState.NO;
 }

 return TriState.UNKNOWN;
 

isDateTime

boolean isDateTime()

Returns true if this value is, or if it can be interpreted as, a DateTime. Specifically, true is returned if calling getDateTime() will not result in an exception being thrown.

isNotDateTime

boolean isNotDateTime()

Returns true if the encapsulated value can not be interpreted as a DateTime value. See getDateTime() for an explanation of how DateTime is determined. Equivalent to:

 return !isDateTime();
 

getDateTime

DateTime getDateTime()
                     throws ValueException

Returns the encapsulated value interpreted as a DateTime assuming the UTC timezone if necessary. More specifically:

• If the encapsulated value is a DateTime, the value is simply returned. The default timezone of UTC is neither needed nor used.
• If the String returned by getString() can be successfully parsed by the DateTools.parseUTC(String) method, the resulting DateTime is returned, if not, a ValueException is thrown instead.
• If the encapsulated value is null, ValueException is thrown.

This method assumes the UTC timezone should be used to interpret the time if (and only if) no understandable timezone information is present at the end of the supplied String.

Equivalent to:

 Object obj = getObject();
 if ( obj instanceof DateTime ) {
     return (DateTime) obj;
 }

 try {
     return DateTools.parseUTC(getString());
 } catch ( DateTimeException x ) {
     throw new ValueException(x);
 }
 

Throws:

ValueException - if the encapsulated value is null or if it is not a instance of DateTime and the result of getString() can not be parsed into a DateTime. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getDateTimeOrNull

DateTime getDateTimeOrNull()
                           throws ValueException

Returns the result as a DateTime or null if the value is empty (using the UTC timezone for interpretation if necessary). Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getDateTime();
 }
 

Throws:

ValueException - if the value is not empty and can not be viewed as a DateTime. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getDateTimeLocal

DateTime getDateTimeLocal()
                          throws ValueException

Returns the encapsulated value interpreted as a DateTime assuming the local VM's timezone if necessary. More specifically:

• If the encapsulated value is a DateTime, the value is simply returned. The default timezone of the local VM is neither needed nor used.
• If the String returned by getString() can be successfully parsed by the DateTools.parseLocal(String) method, the resulting DateTime is returned, if not, a ValueException is thrown instead.
• If the encapsulated value is null, ValueException is thrown.

This method assumes the VM's local timezone should be used to interpret the time if (and only if) no understandable timezone information is present at the end of the supplied String.

Equivalent to:

 Object obj = getObject();
 if ( obj instanceof DateTime ) {
     return (DateTime) obj;
 }

 try {
     return DateTools.parseLocal(getString());
 } catch ( DateTimeException x ) {
     throw new ValueException(x);
 }
 

Throws:

ValueException - if the encapsulated value is null or if it is not a instance of DateTime and the result of getString() can not be parsed into a DateTime. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getDateTimeLocalOrNull

DateTime getDateTimeLocalOrNull()
                                throws ValueException

Returns the result as a DateTime or null if the value is empty (using the local VM's timezone for interpretation if necessary). Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getDateTimeLocal();
 }
 

Throws:

ValueException - if the value is not empty and can not be viewed as a DateTime. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getDateTime

DateTime getDateTime(TimeZone defaultTimeZone)
                     throws ValueException,
                            IllegalArgumentException

Returns the encapsulated value interpreted as a DateTime assuming the specified timezone if necessary. More specifically:

• If the encapsulated value is a DateTime, the value is simply returned. The timezone passed in is neither needed nor used.
• If the String returned by getString() can be successfully parsed by the DateTools.parse(String, TimeZone) method, the resulting DateTime is returned, if not, a ValueException is thrown instead.
• If the encapsulated value is null, ValueException is thrown.

This method uses the timezone passed in as a parameter to interpret the time if (and only if) no understandable timezone information is present at the end of the supplied String.

Equivalent to:

 Object obj = getObject();
 if ( obj instanceof DateTime ) {
     return (DateTime) obj;
 }

 try {
     return DateTools.parse(getString(), defaultTimeZone);
 } catch ( DateTimeException x ) {
     throw new ValueException(x);
 }
 

Parameters:

defaultTimeZone - the timezone to use to interpret the value as a DateTime if necessary.

Throws:

ValueException - if the encapsulated value is null or if it is not a instance of DateTime and the result of getString() can not be parsed into a DateTime. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

IllegalArgumentException - if defaultTimeZone is null.

getDateTimeOrNull

DateTime getDateTimeOrNull(TimeZone defaultTimeZone)
                           throws ValueException,
                                  IllegalArgumentException

Returns the result as a DateTime or null if the value is empty (using the specified timezone for interpretation if necessary). Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getDateTime(defaultTimeZone);
 }
 

Throws:

ValueException - if the value is not empty and can not be viewed as a DateTime. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

IllegalArgumentException - if defaultTimeZone is null.

isPlainDate

boolean isPlainDate()

Returns true if this value is, or if it can be interpreted as, a PlainDate. Specifically, true is returned if calling getPlainDate() will not result in an exception being thrown.

isNotPlainDate

boolean isNotPlainDate()

Returns true if the encapsulated value can not be interpreted as a PlainDate value. See getPlainDate() for an explanation of how PlainDate is determined. Equivalent to:

 return !isPlainDate();
 

getPlainDate

PlainDate getPlainDate()
                       throws ValueException

Returns the encapsulated value interpreted as a PlainDate. More specifically:

• If the encapsulated value is a PlainDate, the value is simply returned.
• If the String returned by getString() can be successfully parsed by the DateTools.parsePlainDate(String) method, the resulting PlainDate is returned, if not, a ValueException is thrown instead.
• If the encapsulated value is null, ValueException is thrown.

Equivalent to:

 Object obj = getObject();
 if ( obj instanceof PlainDate ) {
     return (PlainDate) obj;
 }

 try {
     return DateTools.parsePlainDate(getString());
 } catch ( PlainDateException x ) {
     throw new ValueException(x);
 }
 

Throws:

ValueException - if the encapsulated value is null or if it is not a instance of PlainDate and the result of getString() can not be parsed into a PlainDate. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getPlainDateOrNull

PlainDate getPlainDateOrNull()
                             throws ValueException

Returns the result as a PlainDate or null if the value is empty. Equivalent to:

 if ( isEmpty() ) {
     return null;
 } else {
     return getPlainDate();
 }
 

Throws:

ValueException - if the value is not empty and can not be viewed as a PlainDate. Note that ValueException is a RuntimeException so it does not have to be explicitly caught.

getBytes

byte[] getBytes()

Returns the encapsulated value interpreted as a byte[]. If the underlying value is actually a byte[], it is simply returned. Otherwise, the result of getString() is passed through StringTools.parseHexString(String).

Equivalent to:

 Object obj = getObject();
 if ( obj instanceof byte[] ) {
     return (byte[]) ((byte[]) obj).clone();
 }

 return StringTools.parseHexString(getString());
 

The byte[] returned is a copy of the internal data, so there is no chance that an outsider could manipulate the bytes held internally. To avoid making copies of large amounts of data, you may want to consider using getBytesAsStream() instead.

Returns:

the value as an array of bytes. This method never returns null. If the stored value is not a byte[] and the parsing does not find any valid hex digits, then a zero-length byte[] is returned. The byte[] returned is a copy of the internal data, so there is no chance that an outsider could manipulate the bytes held internally.

See Also:

getBytesAsStream()

getBytesAsStream

InputStream getBytesAsStream()

Returns the encapsulated value interpreted as bytes that are readable from InputStream. Internally, the byte[] that serves as a data source for an InputStream is byte[] derived by getBytes() (however, there is no need to make a copy of the internal byte[] as the InputStream provides no mechanism for altering the source of the data). Every call to this method returns a new lightweight InputStream that can be independently read, but the bulky byte[] is efficiently shared among all of the InputStream's that are constructed.

This method is a more memory efficient than calling getBytes() as no copy of the binary data needs to be made.

Equivalent to:

 Object obj = getObject();
 if ( obj instanceof byte[] ) {
     return new ByteArrayInputStream((byte[]) obj);
 }

 return new ByteArrayInputStream(
     StringTools.parseHexString(getString()));
 

Returns:

the value as an stream of bytes available on an InputStream. This method never returns null. If the stored value is not a byte[] and the parsing does not find any valid hex digits, then a zero-length byte[] is used as the source for the InputStream.

See Also:

getBytes()

isMutable

boolean isMutable()

Returns true if the public view of this Value might change over time. Note that most of the common implementations of Value return false for this method. If this method returns false then callers can be sure that two calls to the same method on this particular Value instance will always return the same result (the value returned never changes).

If implementors of Value want to use internal caching for efficiency, they are free to return false from isMutable() as long as the return values for all of the non-private methods never change.

Ironically, the return value from this method must be fixed at the time of construction and may never change. If this method ever returns false is must continue to return false during any subsequent calls.

Returns:

true if the return values from other methods might change over time, false if return values from all methods are always the same.