com.programix.value
Class AbstractValue

java.lang.Object
  com.programix.value.AbstractValue

All Implemented Interfaces:

Value

public abstract class AbstractValue
extends Object
implements Value

A simple partial implementation of Value. See Value for a full explanation of all of the methods. Check out ValueFactory to see if there is a create method available that might eliminate your need to extend AbstractValue. Check out ValueMap for key-value mappings, reading and writing to files and other streams, and more.

Author:

Paul Hyde

Constructor Summary

protected

AbstractValue() This constructor is protected because it only makes sense to be called from a subclass as AbstractValue is not a concrete class (it's abstract after all).

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.
abstract 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractValue

protected AbstractValue()

This constructor is protected because it only makes sense to be called from a subclass as AbstractValue is not a concrete class (it's abstract after all).

Method Detail

getObject

public abstract Object getObject()

Description copied from interface: Value

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.

Specified by:

getObject in interface Value

getObject

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

Description copied from interface: Value

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();
 

Specified by:

getObject in interface Value

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

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

Description copied from interface: Value

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);
 }
 

Specified by:

getObjectOrNull in interface Value

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

public boolean isNull()

Description copied from interface: Value

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

 return getObject() == null;
 

Specified by:

isNull in interface Value

isNotNull

public boolean isNotNull()

Description copied from interface: Value

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

 return !isNull();
 

Specified by:

isNotNull in interface Value

isEmpty

public boolean isEmpty()

Description copied from interface: Value

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);
 

Specified by:

isEmpty in interface Value

isNotEmpty

public boolean isNotEmpty()

Description copied from interface: Value

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

 return !isEmpty();
 

Specified by:

isNotEmpty in interface Value

isType

public boolean isType(Class<?> targetType)
               throws IllegalArgumentException

Description copied from interface: Value

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

Specified by:

isType in interface Value

Throws:

IllegalArgumentException - if targetType is null.

isNotType

public boolean isNotType(Class<?> targetType)
                  throws IllegalArgumentException

Description copied from interface: Value

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

 return !isType(targetType);
 

Specified by:

isNotType in interface Value

Throws:

IllegalArgumentException - if targetType is null.

isTypeNumber

public boolean isTypeNumber()

Description copied from interface: Value

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 Value.isNumeric() (which checks to see if there is any way to interpret the value as a number). Equivalent to:

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

Specified by:

isTypeNumber in interface Value

isNotTypeNumber

public boolean isNotTypeNumber()

Description copied from interface: Value

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

 return !isTypeNumber();
 

Specified by:

isNotTypeNumber in interface Value

isTypeDateTime

public boolean isTypeDateTime()

Description copied from interface: Value

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 Value.isDateTime() (which checks to see if there is any way to interpret the value as a DateTime). Equivalent to:

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

Specified by:

isTypeDateTime in interface Value

isNotTypeDateTime

public boolean isNotTypeDateTime()

Description copied from interface: Value

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

 return !isTypeDateTime();
 

Specified by:

isNotTypeDateTime in interface Value

isTypePlainDate

public boolean isTypePlainDate()

Description copied from interface: Value

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 Value.isPlainDate() (which checks to see if there is any way to interpret the value as a PlainDate). Equivalent to:

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

Specified by:

isTypePlainDate in interface Value

isNotTypePlainDate

public boolean isNotTypePlainDate()

Description copied from interface: Value

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

 return !isTypePlainDate();
 

Specified by:

isNotTypePlainDate in interface Value

isTypeByteArray

public boolean isTypeByteArray()

Description copied from interface: Value

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 Value.getBytes() and Value.getBytesAsStream() (they always find a way to interpret the value as a byte[]). Equivalent to:

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

Specified by:

isTypeByteArray in interface Value

isNotTypeByteArray

public boolean isNotTypeByteArray()

Description copied from interface: Value

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

 return !isTypeByteArray();
 

Specified by:

isNotTypeByteArray in interface Value

getString

public String getString()

Description copied from interface: Value

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();
 

Specified by:

getString in interface Value

getStringOrNull

public String getStringOrNull()

Description copied from interface: Value

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 Value.isEmpty() and Value.getString(). Equivalent to:

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

Specified by:

getStringOrNull in interface Value

getRawString

public String getRawString()

Description copied from interface: Value

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();
 

Specified by:

getRawString in interface Value

isNumeric

public boolean isNumeric()

Description copied from interface: Value

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 Value.getNumber() for details. This method's test is more lenient than Value.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;
 }
 

Specified by:

isNumeric in interface Value

isNotNumeric

public boolean isNotNumeric()

Description copied from interface: Value

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();
 

Specified by:

isNotNumeric in interface Value

getNumber

public Number getNumber()
                 throws ValueException

Description copied from interface: Value

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.

Specified by:

getNumber in interface Value

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

public Number getNumberOrNull()
                       throws ValueException

Description copied from interface: Value

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

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

Specified by:

getNumberOrNull in interface Value

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

public BigDecimal getBigDecimal()
                         throws ValueException

Description copied from interface: Value

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( //...
 }
 

Specified by:

getBigDecimal in interface Value

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

public BigDecimal getBigDecimalOrNull()
                               throws ValueException

Description copied from interface: Value

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

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

Specified by:

getBigDecimalOrNull in interface Value

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

public long getLong()
             throws RangeValueException,
                    ValueException

Description copied from interface: Value

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

 return NumberTools.toLong(getNumber());
 

Specified by:

getLong in interface Value

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:

Value.getLongNumber()

getLongNumber

public Long getLongNumber()
                   throws RangeValueException,
                          ValueException

Description copied from interface: Value

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

 return NumberTools.toLongNumber(getNumber());
 

Specified by:

getLongNumber in interface Value

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:

Value.getLong()

getLongNumberOrNull

public Long getLongNumberOrNull()
                         throws RangeValueException,
                                ValueException

Description copied from interface: Value

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

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

Specified by:

getLongNumberOrNull in interface Value

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

public int getInt()
           throws RangeValueException,
                  ValueException

Description copied from interface: Value

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

 return NumberTools.toInt(getNumber());
 

Specified by:

getInt in interface Value

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:

Value.getIntegerNumber()

getIntegerNumber

public Integer getIntegerNumber()
                         throws RangeValueException,
                                ValueException

Description copied from interface: Value

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

 return NumberTools.toIntegerNumber(getNumber());
 

Specified by:

getIntegerNumber in interface Value

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:

Value.getInt()

getIntegerNumberOrNull

public Integer getIntegerNumberOrNull()
                               throws RangeValueException,
                                      ValueException

Description copied from interface: Value

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

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

Specified by:

getIntegerNumberOrNull in interface Value

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

public short getShort()
               throws RangeValueException,
                      ValueException

Description copied from interface: Value

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

 return NumberTools.toShort(getNumber());
 

Specified by:

getShort in interface Value

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:

Value.getShortNumber()

getShortNumber

public Short getShortNumber()
                     throws RangeValueException,
                            ValueException

Description copied from interface: Value

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

 return NumberTools.toShortNumber(getNumber());
 

Specified by:

getShortNumber in interface Value

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:

Value.getShort()

getShortNumberOrNull

public Short getShortNumberOrNull()
                           throws RangeValueException,
                                  ValueException

Description copied from interface: Value

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

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

Specified by:

getShortNumberOrNull in interface Value

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

public byte getByte()
             throws RangeValueException,
                    ValueException

Description copied from interface: Value

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

 return NumberTools.toByte(getNumber());
 

Specified by:

getByte in interface Value

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:

Value.getByteNumber()

getByteNumber

public Byte getByteNumber()
                   throws RangeValueException,
                          ValueException

Description copied from interface: Value

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

 return NumberTools.toByteNumber(getNumber());
 

Specified by:

getByteNumber in interface Value

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:

Value.getByte()

getByteNumberOrNull

public Byte getByteNumberOrNull()
                         throws RangeValueException,
                                ValueException

Description copied from interface: Value

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

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

Specified by:

getByteNumberOrNull in interface Value

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

public double getDouble()
                 throws ValueException

Description copied from interface: Value

Returns the result as a double value. Equivalent to:

 return getNumber().doubleValue();
 

Specified by:

getDouble in interface Value

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

public Double getDoubleNumber()
                       throws ValueException

Description copied from interface: Value

Returns the result as a Double value. Equivalent to:

 return new Double(getDouble());
 

Specified by:

getDoubleNumber in interface Value

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:

Value.getDouble()

getDoubleNumberOrNull

public Double getDoubleNumberOrNull()
                             throws ValueException

Description copied from interface: Value

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

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

Specified by:

getDoubleNumberOrNull in interface Value

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

public float getFloat()
               throws ValueException

Description copied from interface: Value

Returns the result as a float value. Equivalent to:

 return getNumber().floatValue();
 

Specified by:

getFloat in interface Value

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

public Float getFloatNumber()
                     throws ValueException

Description copied from interface: Value

Returns the result as a Float value. Equivalent to:

 return new Float(getFloat());
 

Specified by:

getFloatNumber in interface Value

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:

Value.getFloat()

getFloatNumberOrNull

public Float getFloatNumberOrNull()
                           throws ValueException

Description copied from interface: Value

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

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

Specified by:

getFloatNumberOrNull in interface Value

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

public boolean isTrue()

Description copied from interface: Value

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
 

Specified by:

isTrue in interface Value

isFalse

public boolean isFalse()

Description copied from interface: Value

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();
 

Specified by:

isFalse in interface Value

getTriState

public TriState getTriState()

Description copied from interface: Value

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;
 

Specified by:

getTriState in interface Value

isDateTime

public boolean isDateTime()

Description copied from interface: Value

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

Specified by:

isDateTime in interface Value

isNotDateTime

public boolean isNotDateTime()

Description copied from interface: Value

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();
 

Specified by:

isNotDateTime in interface Value

getDateTime

public DateTime getDateTime()
                     throws ValueException

Description copied from interface: Value

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);
 }
 

Specified by:

getDateTime in interface Value

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

public DateTime getDateTimeOrNull()
                           throws ValueException

Description copied from interface: Value

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();
 }
 

Specified by:

getDateTimeOrNull in interface Value

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

public DateTime getDateTimeLocal()
                          throws ValueException

Description copied from interface: Value

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);
 }
 

Specified by:

getDateTimeLocal in interface Value

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

public DateTime getDateTimeLocalOrNull()
                                throws ValueException

Description copied from interface: Value

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();
 }
 

Specified by:

getDateTimeLocalOrNull in interface Value

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

public DateTime getDateTime(TimeZone defaultTimeZone)
                     throws ValueException,
                            IllegalArgumentException

Description copied from interface: Value

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);
 }
 

Specified by:

getDateTime in interface Value

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

public DateTime getDateTimeOrNull(TimeZone defaultTimeZone)
                           throws ValueException,
                                  IllegalArgumentException

Description copied from interface: Value

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);
 }
 

Specified by:

getDateTimeOrNull in interface Value

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

public boolean isPlainDate()

Description copied from interface: Value

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

Specified by:

isPlainDate in interface Value

isNotPlainDate

public boolean isNotPlainDate()

Description copied from interface: Value

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();
 

Specified by:

isNotPlainDate in interface Value

getPlainDate

public PlainDate getPlainDate()
                       throws ValueException

Description copied from interface: Value

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);
 }
 

Specified by:

getPlainDate in interface Value

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

public PlainDate getPlainDateOrNull()
                             throws ValueException

Description copied from interface: Value

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

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

Specified by:

getPlainDateOrNull in interface Value

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

public byte[] getBytes()

Description copied from interface: Value

Returns the encapsulated value interpreted as a byte[]. If the underlying value is actually a byte[], it is simply returned. Otherwise, the result of Value.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 Value.getBytesAsStream() instead.

Specified by:

getBytes in interface Value

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:

Value.getBytesAsStream()

getBytesAsStream

public InputStream getBytesAsStream()

Description copied from interface: Value

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 Value.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 Value.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()));
 

Specified by:

getBytesAsStream in interface Value

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:

Value.getBytes()

isMutable

public boolean isMutable()

Description copied from interface: Value

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.

Specified by:

isMutable in interface Value

Returns:

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