net.sf.mmm.util.value.package-info Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mmm-util-core
provides core utilities that fill gaps in the jdk.
The newest version!
/* $Id: package-info.java 364 2007-11-06 22:41:51Z hohwille $
 * Copyright (c) The m-m-m Team, Licensed under the Apache License, Version 2.0
 * http://www.apache.org/licenses/LICENSE-2.0 */
/**
 * Contains utilities for generic handling of values.
 * Value Handling
 * 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 
 * {@link java.lang.String} to {@link java.lang.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 {@link java.lang.NullPointerException} the user can NOT know which 
 * configuration-file and what value is wrong.

 * This package provides an extendable {@link net.sf.mmm.util.value.ValueConverter} 
 * that makes your job a lot simpler and helps you to have precise 
 * exception-messages in situations of an error. Further you have 
 * {@link net.sf.mmm.util.nls 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 {@link net.sf.mmm.util.value.ValueConverter}:
 *  * String value = getValueFromSomewhere();
 * ValueConverter converter = ValueConverter.INSTANCE;
 * int valueAsInt = converter.{@link net.sf.mmm.util.value.ValueConverter#convertValue(String, Object, 
 * Number, Number) convertValue}(value, "somewhere", 0, 123456789);
 * 
 */
package net.sf.mmm.util.value;