Database schema-level validation

Out of the box, NHibernate Validator will translate the constraints you have defined for your entities into mapping metadata. For example, if a property of your entity has the attribute [NotNull], its columns will be declared as not null in the DDL schema generated by NHibernate.

Using hbm2ddl, domain model constraints will be expressed into the database schema.

If, for some reason, the feature needs to be disabled, set apply_to_ddl to false.

ORM integration

NHibernate Validator integrates with NHibernate in a native way, and knows how to treat every persistent entity.

<hibernate-configuration>
    ...
    <event type="pre-update">
        <listener class="NHibernate.Validator.Event.ValidatePreUpdateEventListener, NHibernate.Validator"/>
    </event>
    <event type="pre-insert">
        <listener class="NHibernate.Validator.Event.ValidatePreInsertEventListener, NHibernate.Validator"/>
    </event>
</hibernate-configuration>

Application-level validation

In order to interact with NHibernate Validator in your application you must use the main class: ValidatorEngine.

ValidatorEngine validator = new ValidatorEngine();
bool isValid = validator.IsValid(customer);

These two lines are enough to validate an object with its validation rules, which can be configured using Attributes or XML. The first line is the instantiation of the validator engine of NHibernate Validator. The second line is the validation of an object, and the result of the IsValid(...)method indicates if the object is valid or not. In order to get the invalid values of an object, you can do:

ValidatorEngine validator = new ValidatorEngine();
InvalidValue[] validationMessages = validator.GetInvalidValues(customer);

Now instead of only knowing if the object is valid or not, we get an array of InvalidValues. If this array length is greater than zero then there are validation errors and you can traverse the InvalidValue array to get verbose information about the problems that cause the object to be invalid.

Presentation layer validation

[TODO]

Validation informations

NHibernate Validator provides an array of InvalidValue. Each InvalidValue has several methods describing the reasons that caused the entity to be invalid.

BeanClass retrieves the failing bean type

Bean retrieves the failing instance (if any ie not when using GetPotentialInvalidValues())

Value retrieves the failing value

Message retrieves the proper internationalized error message

RootBean retrieves the root bean instance generating the issue (useful in conjunction with [Valid]), is null if GetPotentialInvalidValues(...) is used.

PropertyPath retrieves the dotted path of the failing property starting from the root bean

What is a constraint?

A constraint is a rule that a given element (field, property or type) has to comply to. The rule semantic is expressed by an Attribute or configured in Xml files. A constraint may have some properties to configure the associated validator, for example a Min constraint will have a value property setting the minimum acceptable value for the element to be valid.

Built in constraints

Hibernate Validator comes with some built-in constraints, which cover most of the basic data checks. As we'll see later, you're not limited to them, you can literally in a minute write your own constraints.

Table Built-in constraints

Error messages

NHibernate Validator comes with a default set of error messages translated in several languages (if yours is not present, please send us a patch). You can add your own additional set of messages while writing your validator Attributes or at XML. If NHibernate Validator cannot resolve a key from your ResourceManager nor from ValidatorMessage, it falls back to the default built-in values.

Alternatively you can provide a ResourceManager while checking programmatically the validation rules on a bean or if you want a completly different interpolation mechanism, you can provide an implementation of NHibernate.Validator.Engine.IMessageInterpolator.

Writing your own constraints

Extending the set of built-in constraints is extremely easy. Any constraint consists of two pieces: the constraint descriptor (the attribute) and the constraint validator (the implementation class). Here is a simple user-defined descriptor:

[AttributeUsage(AttributeTargets.Field | AttributeTargets.Property)]
[ValidatorClass(typeof(PhoneValidator))]
public class PhoneAttribute : Attribute, IRuleArgs
{
    private string message = string.Empty;
    public string Message
    {
        get { return message; }
        set { message = value; }
    }
}

To link a descriptor to its validator implementation, we use the [ValidatorClass] meta-attribute. Here you can see an implementation of a constraint validator:

public class PhoneValidator : IValidator
{
     public bool IsValid(object value)
     {
         Regex regex = new Regex(@"^[2-9]\d{2}-\d{3}-\d{4}$");
         if (value == null) return true;
         return regex.IsMatch(value.ToString());
     }
}

This PhoneValidator class is simple. The method IsValid() receives a string that should be validated with a Regex expression. The IsValid() method should return false if the constraint has been violated.

If you need to initialize the class validator you can implement the interface IInitializableValidator<A> and the class should look like this:

public class PhoneValidator : IInitializableValidator<PhoneAttribute>
{
    private Regex regex;

    public bool IsValid(object value)
    {
        if (value == null) return true;
        return regex.IsMatch(value.ToString());
    }

    public void Initialize(PhoneAttribute parameters)
    {
        regex = new Regex(@"^[2-9]\d{2}-\d{3}-\d{4}$");
    }
}

As you can see, implementing the IInitializableValidator<A> interface we have to implement the method Initialize(...) that initializes the validator, and it's executed first of all.

The IsValid() method should return false if the constraint has been violated. For more examples, refer to the built-in validator implementations.

We now have to implement the validator (ie. the rule checking implementation). A validation implementation can check the value of the a property (by implementing PropertyConstraint ) and/or can modify the NHibernate mapping metadata to express the constraint at the database level (by implementing PersistentClassConstraint)

We have only seen property level validation, but you can write a class level validation attribute. Instead of receiving the return instance of a property, the bean itself will be passed to the validator. To activate the validation checking, just put the validation attribute to the class itself instead of in a property. A small sample can be found in the unit test suite.

If your constraint can be applied multiple times (with different parameters) on the same property or type, you can use set the AllowMultiple parameter to true on the AttributeUsage attribute. An example of this it's the built-in validator Pattern, have a look:

[Serializable]
[AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, AllowMultiple = true)]
[ValidatorClass(typeof (PatternValidator))]
public class PatternAttribute : Attribute, IRuleArgs
{
    …
}

Configuring your domain model with .Net Attributes

Since you are already familiar with attributes now, the syntax should be very familiar

public class Address
{ 
    // a static non null field  
    [NotNull]
    public static string blacklistedZipCode;
    
    // field a not null string of 20 characters maximum
    [Length(Max = 20), NotNull]    
    private string country;
    private long id;
    private bool internalValid = true;
    private string line1;
    private string line2;
    private string state;
    private string zip;
    
    // a numeric between 1 and 2000
    [Min(1), Range(Max = 2000)]
    public long Id
    {
        get { return id; }
        set { id = value; }
    }

    // respond to the constraint in the field: country
    public string Country
    {
        get { return country; }
        set { country = value; }
    }

    // a non null string
    [NotNull]
    public string Line1
    {
        get { return line1; }
        set { line1 = value; }
    }

    // a not null string of 3 characters maximum
    [Length(Max = 3), NotNull]
    public string State
    {
        get { return state; }
        set { state = value; }
    }

    // a not null numeric string of 5 characters maximum
    // if the string is longer, the message will
    // be searched in the resource bundle at key 'long'
    [Length(Max = 5, Message = "{long}")]
    [Pattern(Regex = "[0-9]+")]
    [NotNull]
    public string Zip
    {

        get { return zip; }
        set { zip = value; }
    }

    // no constraint
    public string Line2
    {
        get { return line2; }
        set { line2 = value; }
    }

    // should always be true
    [AssertTrue]
    public bool InternalValid
    {
        get { return internalValid; }
        set { internalValid = value; }
    }
} 

While the example only shows public property validation, you can also annotate fields of any kind of visibility. In the example MyBeanConstraint is a custom Class Validator, we will talk about this later.

[MyBeanConstraint(Max=45)]
public class Dog 
{
    [AssertTrue] private bool IsMale;
    [NotNull] protected string Name { get {...} set{...} }
    …
}     

You can also annotate interfaces. NHibernate Validator will check all superclasses and interfaces extended or implemented by a given type to read the appropriate validator attributes.

public interface Named 
{
    [NotNull] string Name {get; set;}
    ...
}

public class Dog : Named 
{
    [AssertTrue] private bool isMale;
    public string Name { get {...} set{...} }
}

The name property will be checked for nullity when the Dog type is validated.

Configuring your domain model with XML

You also can configurate your domain model with constraints using xml files: the nhv.xml files. We prefer to embed these Xml files into the assemblies, and NHibernate Validator is prepared to inspect them and retrieve the resources with constrains, like NHibernate does with hbm.xml files.

<?xml version="1.0" encoding="utf-8" ?>
<nhv-mapping xmlns="urn:nhibernate-validator-1.0"
                        namespace="NHibernate.Validator.Tests.Base"
                        assembly="NHibernate.Validator.Tests">
    <class name="Address">
    <property name="blacklistedZipCode">
                  <not-null/>
    </property>
    
    <property name="country">
           <length max="20"/>
           <not-null />    
    </property>
    
    <property name="floor">    
          <range min="-2" max="50" message="{floor.out.of.range} (escaping #{el})" />
    </property>
    
    <property name="Id">    
          <min value="1" />
          <range max="2000" />
          <max value="2500"/>
    </property>
    
    <property name="Line1" >    
          <not-null/>
    </property>
    
    <property name="State">    
          <not-null/>
          <length max="3"/>
    </property>

    <property name="Zip">
          <length max="5" message="{long}"/>
          <pattern regex="[0-9]+" />
          <not-null/>
    </property>
    
    <property name="InternalValid">    
          <asserttrue />
    </property>
    </class>
</nhv-mapping>      

We strongly recommend to validate every nhv.xml file of your application with the respective XSD file. Every nhv.xml file should be validated with the nhv-mapping.xsd file included within the NHibernate Validator distribution whether in source or binaries. Indeed, if you are using an IDE like Visual Studio it offers IntelliSense support in the nhv.xml file if you add the schema to Visual Studio's xml schemas folder.

Xml beauties: The nicest part of Xml for validation is that you can put xml validators in a different dll so you don't need to recompile your domain when validation rules change. Only the dll with the Xml files..

Programmatic configuration

You can use the following code to configure NHibernate.Validator programmatically:

using NHibernate.Validator.Cfg;
using NHibernate.Validator.Engine;
using using Environment=NHibernate.Validator.Cfg.Environment;
…
ValidatorEngine ve = new ValidatorEngine();

NHVConfiguration nhvc = new NHVConfiguration();
nhvc.Properties[Environment.ApplyToDDL] = "false";
nhvc.Properties[Environment.AutoregisterListeners] = "false";
nhvc.Properties[Environment.ValidatorMode] = GetMode();
nhvc.Mappings.Add(new MappingConfiguration("NHibernate.Validator.Demo.Model",null));
ve.Configure(nhvc);  

The ValidatorEngine will be set with the configuration. The NHibernate Validator configuration is represented by the NHibernate.Validator.Cfg.NHVConfiguration type. Other class used to configure all the stuff is the NHibernate.Validator.Cfg.Environment type, this class contain the string with the names of the properties of the configuration of NHibernate Validator.

Declarative configuration: using Xml files

The declarative configuration keeps configuration out of the code. This means configuring the application using a different file, in this case a XML file. But the options don't end here: you can choose to configure NHibernate Validator using a simple Xml file or you can put the configuration in the well known App.Config/Web.Config.

<?xml version="1.0" encoding="utf-8" ?>
<nhv-configuration xmlns='urn:nhv-configuration-1.0'>
  <property name='apply_to_ddl'>true</property>
  <property name='autoregister_listeners'>true</property>
  <property name='default_validator_mode'>UseXml</property>
  <mapping assembly='NHibernate.Validator.Demo.Model'/>
</nhv-configuration>

ValidatorEngine engine = new ValidatorEngine();
engine.Configure(); // by convention reads the nhvalidator.cfg.xml file.

ValidatorEngine engine = new ValidatorEngine();
engine.Configure("path/to/MyNHVConfigurationFile.xml"); // you can use whatever path to point to the configuration file

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <configSections>
        <section name="nhv-configuration" 
                            type="NHibernate.Validator.Cfg.ConfigurationSectionHandler, NHibernate.Validator" />
        ...
    </configSections>
    ...
    <nhv-configuration xmlns='urn:nhv-configuration-1.0'>
        <shared_engine_provider 
         class='NHibernate.Validator.Event.NHibernateSharedEngineProvider, NHibernate.Validator'/>
    </nhv-configuration>
    ...
</configuration>