@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class) @Copyright(value="Copyright © 2008, Iparelan Solutions, LLC. All rights reserved.")

Package com.iparelan.util.validation

Iparelan Validation Utilities
This file is part of Virtual Team Tools.
Copyright © 2008, Iparelan Solutions, LLC.

See:
Description

Interface Summary

ValidationStrategy<T>

A strategy for validating a value.

Class Summary

AbstractValidationStrategy<T>	Provides logic common to all validation strategies.
NonEmptyStringValidationStrategy	A validator that ensures a string is not empty.
NonNullClassValidationStrategy	A validator that ensures a class is not null.
NonNullNonEmptyStringValidationStrategy	A validator that ensures a string is neither empty nor null.
NonNullObjectValidationStrategy	A validator that ensures an object is not null.
NonNullStringValidationStrategy	A validator that ensures a string is not null.
NonNullValidationStrategy<T>	A validator that ensures an object of some arbitrary type is not null.
NoValidationStrategy<T>	A validator that does no validation.
RangeValidationStrategy<T extends Comparable<? super T>>	A validator that ensures that a value of a total ordering is within some range of values.

Enum Summary

AbstractValidationStrategy.ContextIndex	The default position of the value description in the validation context.
RangeValidationStrategy.ContextMinMaxIndexOffset	Offsets from the context position where the minimum is specified.

Exception Summary

ValidationException

A validation exception.

Package com.iparelan.util.validation Description

Iparelan Validation Utilities
This file is part of Virtual Team Tools.
Copyright © 2008, Iparelan Solutions, LLC. All rights reserved.

Virtual Team Tools is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Virtual Team Tools is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with Virtual Team Tools. If not, see <http://www.gnu.org/licenses/>.

The validation package provides general, standard, reusable ways to write guard clauses.

For example, this:

     public void setWebAddress(final URL webAddress) {
         if (webAddress == null) {
             throw new IllegalArgumentException("web address is null");
         }
         this.webAddress = webAddress;
     }
 

is replaced with this slightly more concise form:

     public void setWebAddress(final URL webAddress) {
         NON_NULL_OBJECT.validate(webAddress, "web address");
         this.webAddress = webAddress;
     }
 

Which behaves like this:

If webAddress is not "valid," i.e. null in this case, then a ValidationException is raised with an error message that includes "web address" for debugging/auditing purposes.

This package provides two kinds of validators in addition to the general validator interface. Both validator forms are immutable so they are thread-safe:

Pre-defined Validator

A general purpose validator class. Example: NonNullObjectValidationStrategy. Pre-defined validators classes may be instantiated as-is or they may be extended through inheritance to create application specific validation behaviors. Such extensions should strive to be immutable to promote reuse of particular validator instances.

Pre-fabricated Validator

An instantiation of a pre-defined validator. Pre-fabricated validators may be used instead of consuming memory to instantiate new validators for each validation. Example: NON_NULL_OBJECT.

This package is influenced by, though not based on the implementation of, the well-written treatment of constraints in the book "Hardcore Java." The validators here differ significantly from the pre-Java 5.0 HCJ constraints. The HCJ constraints are concerned with checking data type and whether a value is within some range in data models. The validators in this package do not do any type checking beyond that provided by the generics language feature. The use of generics also means that no collection scans are done for type safety. No primitive validators are included in this package, autoboxing brings primitives into the fold. The HCJ constraints seem to be intended for use on data models only, these validators are intended for broad use on any parameter of any method. The validators here have no explicit notion of an "optional" value, though a non-null validator can always be composed with any other validator. Finally, the validators here have a variable arity validation() method that accepts validator specific context allowing application developers to create rich validation behaviors.

Note: The name ValidationStrategy was chosen instead of Validator to avoid confusion and name clashes with existing Validator types like those in the javax.xml and javax.xml.bind packages.

Note: Validation is an interesting aspect candidate for aspect-oriented programming.

Version:

July 2008

Author:

Greg Mattes

See Also:

"Hardcore Java," Simmons, Chapter 8, "Reusable Data Constraints", "Replace Nested Conditional with Guard Clauses" at refactoring.com