You can add constraint annotations to class fields that are checked when an object validation is performed. There exists a number of pre-built constraints that you can find in the package net.sf.oval.constraint .

An object can be validated by using the public validate(Object validatedObject) method of net.sf.oval.Validator

public class BusinessObject { 

  @NotNull 
  @NotEmpty 
  @Length(max=32)
  private String name;

  ...
}

Example usage:

Validator validator = new Validator();

BusinessObject bo = new BusinessObject(); // name is null

// collect the constraint violations List<ConstraintViolation> violations =
validator.validate(bo);

if(violations.size()>0)
{
  LOG.severe("Object " + bo + " is invalid.");
  throw new BussinessException(violations);
}

You can specify constraints for the return value of getter methods. When validating the object the values of all fields and the return values of the getter methods are checked against the specified constraints.

The methods need to be annotated with @net.sf.oval.configuration.annotation.IsInvariant Return value constraints specified for methods missing this annotation are ignored during validation.

Important: To retrieve the return value of the getter method OVal invokes the getter during the validation process. Therefore you need to ensure that the getter method really is just a getter method and does not change the object state.

public class BusinessObject
{
  private String name = null;

  @IsInvariant
  @NotNull 
  @Length(max = 4)
  public String getName() 
  {
    return name;
  }

  ...
}

Example usage:

Validator validator = new Validator();

BusinessObject bo = new BusinessObject("blabla");

// collect the constraint violations 
List<ConstraintViolation> violations = validator.validate(bo);

if(violations.size()>0)
{
  LOG.severe("Object " + bo + " is invalid.");
  throw new BussinessException(violations);
}

When you annotate a field or getter with multiple constraint annotations they are ANDed. If you require other logical constructs you can use a scripting language to express them. To do so annotate the field or getter with the @net.sf.oval.constraint.Assert annotation as shown in the following example:

public class BusinessObject 
{
  @NotNull
  public String deliveryAddress;

  @NotNull public String invoiceAddress;

  // mailingAddress must either be the delivery address or the invoice address 
  @Assert(expr = "_value ==_this.deliveryAddress || _value == _this.invoiceAddress", lang = "groovy")
  public String mailingAddress;
}

The expr parameter holds the script to be evaluated. If the script returns true the constraint is satisfied. OVal provides two special variables:

The lang parameter specifies the scripting language you want to use. In case the required libraries are loaded, OVal is aware of these languages:

Additional scripting languages can be registered via Validator.addExpressionLanguage(String, ExpressionLanguage) .

OVal's configuration mechanism is highly customizable. Using the net.sf.oval.configuration.Configurer interface you can write your own constraint configurers configuring OVal based on other XML schemas, other sets of annotations or anything else you like.

OVal comes with a configurer that is capable of translating certain EJB3 JPA annotations into equivalent OVal constraints. The net.sf.oval.configuration.annotation.JPAAnnotationsConfigurer interprets the EJB3 JPA annotations as follows:

@Entity public class MyEntity 
{
  @Basic(optional = false) 
  @Column(length = 4) 
  public String id;

  @Column(nullable = false) 
  public String descr;

  @ManyToOne(optional = false) 
  public MyEntity parent;
}

Example usage:

// configure OVal to interprete OVal constraint annotations as well as EJB3 JPA annotations
Validator validator = new Validator(new AnnotationsConfigurer(), new JPAAnnotationsConfigurer());

MyEntity entity = new MyEntity();

entity.id = "12345"; // violation - the max length is 4 
entity.descr = null; // violation - cannot be null 
entity.parent = null; // violation - cannot be null

// collect the constraint violations 
List<ConstraintViolation> violations = validator.validate(entity);

The easiest way to getting started is to use the Eclipse IDE in conjunction with the AspectJ plug-in .

Create a new AspectJ project or add AspectJ support to an existing Java project by right-clicking the project in the Package Explorer and selecting Convert To AspectJ Project

Add the net.sf.oval_x.x.jar file to your library path.

Create a new aspect via File -> New -> Aspect that extends the abstract aspect net.sf.oval.guard.GuardAspect . When the new aspect is created the AspectJ builder will automatically weave the validation related code into your compiled classes annotated with @net.sf.oval.guard.Guarded .

Now you can create all your business classes, add the @net.sf.oval.guard.Guarded annotation and define the required constraints using the built-in or custom constraint annotations.

OVal provides a so called probe mode in which you can execute all methods of an object and the guard will only check the preconditions (e.g. parameter constraints) and not execute the method.

This is especially useful if you want to test input values received from the end user in the UI layer against the setter methods of a business object. You can simply pass the values to the corresponding setters and have any detected violations collect by a ConstraintsViolatedListener . Afterwards you can report all violations back to the UI layer and have them displayed to the end user.

Example business object:

@net.sf.oval.guard.Guarded 
public class Person 
{
  @NotNegative 
  private int age;

  @Min(5)
  private String name = "";

  @Length(min=5, max=5)
  private String zipCode = "";

  public void setAge(@FieldConstraints int age)
  {
    this.age = age;
  }

  public void setName(@FieldConstraints String name) 
  {
    this.name = name;
  }

  public void setZipCode(@FieldConstraints String zipCode) 
  {
    this.zipCode = zipCode;
  }
  
  ...
}

Example usage:

/* *****************************************************
 * somewhere in the UI layer
 * *****************************************************/
 inputForm.setName("1234");
 inputForm.setAge(-4);
 inputForm.setZipCode("123");

...

/* *****************************************************
 * later in the business layer
 * *****************************************************/
public Person createPerson(PersonInputForm inputForm) throws ConstraintsViolatedException
{
  Person person = new Person();

  Guard guard = MyGuardAspect.aspectOf().getGuard();

  // enable the probe mode in the current thread for the person object
  guard.enableProbeMode(person);

  // simulate applying the values to the person bean
  person.setName(inputForm.getName());
  person.setAge(inputForm.getAge());
  person.setZipCode(inputForm.getZipCode());

  // disable the probe mode in the current thread for the person object
  ProbeModeListener result = guard.disableProbeMode(person);

  // check if any constraint violations occured
  if(result.getConstraintViolations().size() > 0)
  {
     // report the collected constraint violations to the UI layer
     throw new ConstraintsViolatedException(result.getConstraintViolations());
  }
  else
  {
    // apply the values to the person bean
    result.commit();

    dao.save(person);
    return person;
  }
}

When calling methods on guarded objects these methods will throw ConstraintsViolatedExceptions in case any pre- or postconditions are violated. Their might be good reasons why you may want to have other exceptions thrown instead of OVal's proprietary exceptions, e.g. JRE standard exceptions such as IllegalArgumentException or IllegalStateException .

OVal's Guard class allows you to register an exception translator. The exception translator defines a translateException() method that is executed for all occurring exceptions during runtime validation. This allows you to translate any OValException thrown during validation into another RuntimeException which will be thrown instead. As an example have a look at the net.sf.oval.exception.ExceptionTranslatorJDKExceptionsImpl class how an implementation could look like.

Example usage:

public aspect MyAspect extends GuardAspect 
{
  public MyAspect()
  {
    super();

    // specify an exception translator
    getGuard().setExceptionTranslator(new net.sf.oval.exception.ExceptionTranslatorJDKExceptionsImpl()); 
  }
}

You can write a method within the class that has a single parameter to receive the value to validate and that returns true if the constraint is satisfied and false if it is violated.

Example:

private static class TestEntity
{
  @Min(1960)
  private int year = 1977;

  @Range(min=1, max=12)
  private int month = 2;

  @ValidateWithMethod(methodName = "isValidDay", parameterType = int.class)
  private int day = 31;

  private boolean isValidDay(int day)
  {
    GregorianCalendar cal = new GregorianCalendar();
    cal.setLenient(false);
    cal.set(GregorianCalendar.YEAR, year); 
    cal.set(GregorianCalendar.MONTH, month - 1);
    cal.set(GregorianCalendar.DATE, day);
    try {
      cal.getTimeInMillis(); // throws IllegalArgumentException
    } catch (IllegalArgumentException e) { 
      return false;
    }
    return true;
  }
}

You can write an inner static class extending net.sf.oval.constraint.CheckWithCheck.SimpleCheck which then is referenced via a @net.sf.oval.constraint.CheckWith constraint annotation.

Example:

private static class DayEntity
{
  @Min(1960)
  private int year;

  @Range(min=1, max=12)
  private int month;

  @CheckWith(DayCheck.class)
  private int day;

  private static class DayCheck implements CheckWithCheck.SimpleCheck
  {
    public boolean isSatisfied(Object validatedObject, Object value)
    {
      try {
        GregorianCalendar cal = new GregorianCalendar();
        cal.setLenient(false);
        cal.set(GregorianCalendar.YEAR, ((DayEntity) validatedObject).year);
        cal.set(GregorianCalendar.MONTH, ((DayEntity) validatedObject).month - 1);
        cal.set(GregorianCalendar.DATE, ((DayEntity) validatedObject).day);
        cal.getTimeInMillis(); // may throw IllegalArgumentException return true;
      } catch (IllegalArgumentException e) {}
      return false;
    }
  }
}

You may come across the requirement to turn on or off the checking of certain constraints across your domain model, e.g. based on some global configuration settings of the application. OVal helps you to implement this by introducing constraint profiles. For each declared constraint you can specify an infinite number of profiles this constraint belongs to. During runtime you then can enable or disable all constraints associated with a given profile by using the disableProfile , and enableProfile methods of the Validator instance. Constraints not having any profiles declared are automatically assigned a profile named default.

public class Person
{
  @NotNull(profiles = {"profile1"})
  public String firstName;

  @NotNull(profiles = {"profile1"})
  public String lastName;

  @NotNull(profiles = {"profile2", "profile3"})
  public String zipCode;
}

Example usage:

Validator v = new Validator();
v.disableProfile("profile1");

Person p = new Person();
v.validate(p);

In this case only the null value zipCode property will result in a ConstraintViolation . The @NotNull constraints of firstName and lastName are ignored since they are associated with profile1 and profile1 has been disabled.

OVal instantiates all internally used collections indirectly via a CollectionFactory . OVal comes with three different implementations of the collection factory (Javolution Collections, GNU Trove Collections, and JDK Collections). If the Javolution or GNU Trove collection classes are detected in the classpath, OVal automatically uses the respective CollectionFactory otherwise the collection factory for standard JDK collections is used.

The Collection Factory to be used by OVal can be configured via the static Validator.setCollectionFactory(factory) method.

You can implement the net.sf.oval.collection.CollectionFactory interface to support other collection implementations.

If you want to express constraints in a scripting language not supported by OVal out of the box, you need to implement the net.sf.oval.expression.ExpressionLanguage interface for the desired language and register your implementation with OVal using the Validator.addExpressionLanguage(languageId, expressionLanguage) method. Then you can use the specified languageId with expression language aware constraint annotations such as @Assert, @Pre, or @Post and start expressing constraints in the new expression language.