Package net.sf.mmm.util.value.api

Provides the API for generic handling of values.

See: Description

Interface Summary

Interface	Description
ComposedValueConverter	This is the interface for a ValueConverter that is composed out of individual ValueConverters.
ComposedValueConverterFactory	This is the interface of a factory of ComposedValueConverter instances.
GenericValueConverter<SOURCE>	This is the interface for generic conversion of values from a specific source-type ( <SOURCE>) to a given target-type ( <TARGET>).
PropertyAccessor<POJO,VALUE>	This is the interface for an accessor to a specific property of a typed object.
SimpleGenericValueConverter	This is the interface for a SimpleValueConverter that is generic and can convert from Object to Object.
SimpleValueConverter<SOURCE,TARGET>	This is the interface for a converter that converts a value of the type <SOURCE> to the type <TARGET>.
StringValueConverter	This is a sub-interface of GenericValueConverter for the most common value type String.
ValueConverter<SOURCE,TARGET>	This is the interface for a converter that converts a value from a source-type to a specific target-type.

Class Summary

Class	Description
Range<V extends Comparable>	This class represents a range of two values, minimum and maximum.

Exception Summary

Exception	Description
ValueConvertException	The ValueConvertException is thrown if the conversion of some value failed.
ValueException	This exception is thrown if a something goes wrong about values.
ValueNotSetException	This is the exception thrown if a required value was not set.
ValueOutOfRangeException	This is the exception thrown if a numeric value is not in the expected range.
WrongValueTypeException	This exception is thrown if a value has the wrong type (a different value type was expected).

Package net.sf.mmm.util.value.api Description

Provides the API for generic handling of values.

Value-Util API

When reading values from sources like configuration data or user input you always need to handle failure situations. The value can be null and often has to be converted to a specific type (e.g. from String to Integer) but may have an invalid format. If you write this sort of code again and again you get tired and your error-handling gets bad and worse. If the user has tons of configurations to edit and the application starts with a NullPointerException the user can NOT know which configuration-file and what value is wrong.
This package provides the GenericValueConverter that makes your job a lot simpler and helps you to have precise exception-messages in situations of an error. Further you have NLS (see NlsMessage) build in.
Here is a little example of custom value handling:

 String value = getValueFromSomewhere();
 if (value == null) {
   throw new IllegalArgumentException("The value from somewhere is NOT defined!");
 }
 int valueAsInt;
 try {
   valueAsInt = Integer.valueOf(value);
 } catch (NumberFormatException e) {
   throw new IllegalArgumentException("The value '" + value + "' from somewhere is no integer!", e);
 }
 if (valueAsInt < 0) {
   throw new IllegalArgumentException("The value '" + value + "' from somewhere must NOT be negative!");
 }
 if (valueAsInt > 123456789) {
   throw new IllegalArgumentException("The value '" + value + "' from somewhere must be less than '123456789'!");
 }
 

Here is the same thing when using GenericValueConverter:

 String value = getValueFromSomewhere();
 GenericValueConverter converter = StringValueConverterImpl.getInstance();
 int valueAsInt = converter.convertValue(value, "somewhere", 0, 123456789);
 

Even more powerful is the ComposedValueConverter that allows conversions from and to arbitrary types, properly treats generics and is easily extendable via ValueConverters as plugins.