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

Provides the API for generic handling of values.

See:
Description

Interface Summary

ComposedValueConverter	This is the interface for a ValueConverter that is composed out of individual ValueConverters.
GenericValueConverter<SOURCE>	This is the interface for generic conversion of values from a specific source-type (<SOURCE>) to a given target-type ( <TARGET>).
PojoValidator	A PojoValidator is a ValueValidator for Pojos.
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.
ValueValidator<V>	A ValueValidator allows to validate according values.

Exception Summary

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