ProgramixGenericLib v5.0.1

com.programix.value
Class AbstractValue

java.lang.Object
  extended by 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:

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: 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: 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: 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: 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:

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.

ProgramixGenericLib v5.0.1

Copyright © 2001-2009 Programix Incorporated. All rights reserved. ProgramixGenericLib is free and is OSI Certified Open Source Software under the BSD license.