This is not intended as an alternative to Schema based validation such as XSD or Relax.  It provides additional layers of validation in areas not covered by these mechanisms.

Examples of validations one might perform on an Order message containing a collection of Order Item:

1. Use a Regex rule to validate that an orderId field follows a predefined format of “Uppercase Char, followed by 5 digits” e.g. “W12345″ or “U54321″.

2. Use an MVEL rule to enforce a business rule by validating that an order item total is not greater than 50.00 i.e. “price * quantity < 50.00″. Of course these can be more complex.

The easiest way to get familiar with the validation features is to look at an example, so here goes.

For the following example assume that we have the xml that looks like this:

<Order>
    <header>
        <orderId>A188127</orderId>
        <username>user1</username>
        <name>
            <firstname>Harry</firstname>
            <lastname>Fletcher</lastname>
        </name>
        <email>harry.fletcher@gmail.</email>
        <state>South Dakota</state>
    </header>
</Order>

An example of a validation configuration could look like this:

<?xml version="1.0"?>
<smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"
                   xmlns:rules="http://www.milyn.org/xsd/smooks/rules-1.0.xsd"
                   xmlns:validation="http://www.milyn.org/xsd/smooks/validation-1.0.xsd">

   <!-- ruleBases used by validation rules... -->
   <rules:ruleBases>
      <rules:ruleBase name="customer"
                    src="rules/customer.properties"
                    provider="org.milyn.rules.regex.RegexProvider"/>
   </rules:ruleBases>

   <!-- email validation rule targeted at the email element in the header... -->
   <validation:rule executeOn="Order/header/email" name="customer.email" onFail="WARN"/>

</smooks-resource-list>

The ‘exeuteOn‘ attribte specifies the fragment or attribute that you want the validation rule to be applied to. In the case of a Regex rule, it specifies a specific field of data (attribute or element text), while in the case of an MVEL rule, it simply identifies the fragment that triggers execution of that rule.

The next thing to notice is the ‘name‘ attribute. This attribute refers to a rule in one of the configured ruleBase. In the case of the example above, we refer to the ‘email‘ rule in the ‘customer‘ ruleBase i.e. ‘customer.email‘. You can define as many ruleBase elements and validation element as you need, but we are only using one of each here to keep this easy to read.

The ‘customer’ ruleBase is handled by the RegexProvider, as defined in the ‘provider’ attribute on the ruleBase configuration.  We can also see that the ‘customer’ ruleBase rules are located in a properties file named ‘rules/customer.properties‘:

# Email address...
email=^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$

Next, lets take a look at how we execute Smooks to capture some validation results in a ValidationResult instance:

final Smooks smooks = new Smooks("smooks-config.xml");
try
{
    // Create an exec context - no profiles....
    final ExecutionContext executionContext = smooks.createExecutionContext();
    final ValidationResult validationResult = new ValidationResult();

    // Filter the input message...
    smooks.filterSource(executionContext, new StringSource(messageIn), validationResult);

    for (OnFailResult result : results.getWarnings())
    {
        System.out.println("\t" + result.getMessage());
    }
}
finally
{
    smooks.close();
}

As you can see, Validation faiures can be reported at different levels of severity.  This is controlled by setting ‘onFail‘ to one of ‘OK‘, ‘WARN‘, ‘ERROR‘, or ‘FATAL‘. Setting onFail to ‘FATAL’ will cause an exception to be thrown and processing to halt.  The other three levels will not generate an exception.  Failures at these lower severity levels can be accessed through the ValidationResult instance supplied to the Smooks.filterSource method.  An example of getting WARN level failures is shown above with the result.getWarnings() call.

Having usable validation reports is important and Smooks validation supports localized messages for validation failures. These messages can be defined in standard Java ResourceBundle files (.properties format). A convention is used here, based on the rule source name (”src“). The validation message bundle base name is derived from the rule source (”src“) by dropping the rule source file extension and appending a “_messages“.

So for our example we could have a file named ‘customer_messages.properties‘ containing our default locale results:

email=ftl:Invalid email address '${ruleResult.text}' at '${path}'.

So calling result.getMessage() for a validation failure on ‘customer.email’ rule will result in the following message:

Invalid email address ‘harry.fletcher@gmail.’ at ‘/Order/header/email’.

And we could also add a message bundle file for Swedish users.  Following the ResourceBundle naming convention, it should be named ‘customer_messages_sv_SE.properties‘ and would contain the Sweish localized messages:

email=ftl:Felaktig epost adress '${ruleResult.text}' i '${path}'.

Calling result.getMessage(new Locale(”sv, “SE”)) will produce:

Felaktig epost adress ‘harry.fletcher@gmail.’ i ‘/Order/header/email’.

We have only shown a portion of the validation features here.  More information can be found in the Smooks User Guide.  An example of the validation features can be found in Validation Example.

This post is part of a multi post article. You can find the previous post here: Smooks Persistence part 1: The Introduction

In this post we will look at an example of how to persist Hibernate Entities. This example is based on the example of the previous post.

First, lets take a look at the data we are going to process. In this example we are processing XML data.  It should be noted however, that the input data could also be CSV, JSON, EDI, Java or any other structured/hierarchical data format.  The same principals apply, no matter what the data format is!

<order>
    <ordernumber>1</ordernumber>
    <customer>123456</customer>
    <order-items>
        <order-item>
            <product>11</product>
            <quantity>2</quantity>
        </order-item>
        <order-item>
            <product>22</product>
            <quantity>7</quantity>
        </order-item>
    </order-items>
</order>

These are the Hibernate entities we are going to use:

@Entity
@Table(name="orders")
public class Order {

	@Id
	private Integer ordernumber;

	@Basic
	private String customerId;

	@OneToMany(mappedBy = "order", cascade = CascadeType.ALL)
	private List orderItems = new ArrayList();

	public void addOrderLine(OrderLine orderLine) {
		orderItems.add(orderLine);
	}

       // Getters and Setters....
}

@Entity
@Table(name="orderlines")
public class OrderLine {

	@Id
	@GeneratedValue(strategy=GenerationType.IDENTITY)
	private Integer id;

	@ManyToOne
	@JoinColumn(name="orderid")
	private Order order;

	@Basic
	private Integer quantity;

	@ManyToOne
	@JoinColumn(name="productid")
	private Product product;

       // Getters and Setters....
}

@Entity
@Table(name = "products")
@NamedQuery(name="product.byId", query="from Product p where p.id = :id")
public class Product {

	@Id
	private Integer id;

	@Basic
	private String name;

       // Getters and Setters....
}

The Smooks configuration looks like this:

<!--
	In this example, we don't need to reference the Hibernate Session
	anywhere in the configuration. Later on, in the Smooks execution
	code (following snippet), you will see that we have set the
	Session as the default Session. This means that you don't need
	to reference it by name.  In the configuration of the previous
	post, we needed to reference every DAO by its name.
-->
<smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"
	xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.1.xsd" xmlns:dao="http://www.milyn.org/xsd/smooks/persistence-1.2.xsd">

	<!--
		This is a normal Javabean binding. It creates the order bean and binds
		data into it.
	-->
	<jb:bindings beanId="order" class="example.entity.Order"
		createOnElement="order">

		<jb:value property="ordernumber" data="ordernumber" />
		<jb:value property="customerId" data="customer" />
		<jb:wiring setterMethod="addOrderLine" beanIdRef="orderLine" />
	</jb:bindings>

	<!--
		This is a normal Javabean binding. Notice that we have a wiring on
		'product'. The Product entity will not be created, but looked up by a
		locator.
	-->
	<jb:bindings beanId="orderLine" class="example.entity.OrderLine"
		createOnElement="order-item">

		<jb:value property="quantity" data="quantity" decoder="Integer" />
		<jb:wiring property="order" beanIdRef="order" />
		<jb:wiring property="product" beanIdRef="product" />
	</jb:bindings>

	<!--
		This locator calls (via Scribe) the SessionDaoAdapter#lookupByQuery()
		method. The result will be added to the bean repository under the bean
		id 'product'. An exception is thrown when no result is found.
	-->
	<dao:locator beanId="product" lookupOnElement="order-item"
		onNoResult="EXCEPTION" uniqueResult="true">

		<dao:query>from Product p where p.id = :id</dao:query>
		<dao:params>
			<dao:value name="id" data="product" decoder="Integer" />
		</dao:params>
	</dao:locator>

	<!--
		The inserter calls (via Scribe) the SessionDaoAdapter#insert() method
		at the visitAfter of the Order element. The SessioDaoAdapter#insert()
		uses the Hibernate Session#save() method to persist the entity to the
		database.
	-->
	<dao:inserter beanId="order" insertOnElement="order" />

</smooks-resource-list>

If we want to use the named query ‘productById’ instead of the query string then the DAO locator configuration will look like this:

	<!--
		The lookup parameter is the query name
	-->
    <dao:locator beanId="product" lookupOnElement="order-item" lookup="product.byId"
    				onNoResult="EXCEPTION" uniqueResult="true">
    	<dao:params>
    		<dao:value name="id" data="product" decoder="Integer"/>
    	</dao:params>
    </dao:locator>

The following code executes Smooks. Note that we use a SessionRegister object so that we can access the Hibernate Session from within Smooks.

        // Note: In a real world application you should cache the Smooks instance
        // else you will have enormous performance penalties.
        Smooks smooks = new Smooks("smooks-config.xml");

        ExecutionContext executionContext = smooks.createExecutionContext();

        // The SessionRegister provides the bridge between Hibernate and the
        // Persistence Cartridge. We provide it with the Hibernate session.
        // The Hibernate Session is set as default Session.
        DaoRegister register = new SessionRegister(session);

        // This sets the DAO Register in the executionContext for Smooks
        // to access it.
        PersistenceUtil.setDAORegister(executionContext, register);

        Transaction transaction = session.beginTransaction();

        Source source = new StreamSource(new File("order.xml"));        

        smooks.filter(source, null, executionContext);

        transaction.commit();

If you want to take a JPA version of this example for a spin, simply check out the examples from subversion (http://svn.codehaus.org/milyn/trunk/smooks-examples/) and you’ll find it in the “dao-router” folder. It also shows you how to use custom DOA’s with the Persistence Cartridge.

With Scribe and the Persistence Cartridge it is very easy to use Hibernate, JPA and most other persistence frameworks within Smooks. Later on in this series I will explain how too write your own DAO Adapters, so that you can add support for other persistence frameworks.

In the next post of the series I will explain how you can use Ibatis with the Persistence Cartridge.

This cartridge is great for those cases where you already have your data access layer and want to use its power from within Smooks. It also allows you to reuse these persistence resources on any format of data, not just XML e.g. EDI, CSV, JSON etc.

This is the first post of a series of posts about the persistence cartridge. This post is an introduction of the cartridge.  I will give an overview of what the cartridge can do and also show an example where I use custom DAO’s to persist the data of an XML document.  In the next posts in this series, I will show examples of how Hibernate, JPA and Ibatis entities can be used.

The Persistence cartridge is build around a data access layer abstraction library called “Scribe”.  Scribe is a new Milyn subproject, born out of the needs of the Persistence cartridge. It enables the Persistence cartridge to use your DAOs without it actually needing to know the details of your DAOs. In fact, they don’t need to be DAOs at all.  You can also use any entity persistence framework without the Persistence cartridge seeing the difference.  Scribe supports abstracting the default actions you can expect from any DAO or persistence library like inserting, updating, deleting and querying for entities.

For Scribe to understand how to use your DAOs, it needs a mapping. Scribe offers two methods for doing this:

• Java Annotations
  Scribe has a set of Java Annotations like @Insert, @Update, @Delete and @Locate. These annotations enable you to map your DAOs to the DAO actions.
• Java Interfaces
  Scribe defines a set of Java interfaces like DAO, Locator and Queryable.  You build your DAOs By combining and implementing these interfaces. These interfaces are primarily meant to be used for implementing adapters for persistence frameworks.

The Persistence Cartridge defines a set of Smooks Visitor components that use the DAO actions defined by Scribe.  For example, the Inserter visitor can insert your entities by calling the method defined by the DAO action mapping.  We see an example of this later.

The cartridge has the following Smooks Visitor components:

• Inserter
  Inserts/Persists entities
• Updater
  Updates/Merges entities
• Deleter
  Deletes entities
• Locator
  Locates entities with a query or with your own lookup method.

Now that you have an idea of what the Persistence cartridge can do, let’s take a look at a DAO based example.  We will see Hibernate, IBatis and JPA examples in the followup posts in this series.

The example will read an XML file containing order information (note that this works just the same for EDI, CSV etc).  Using the javabean cartridge, it will bind the XML data into a set of entity beans.  Using the id of the products within the order items (the <product> element) it will locate the product entities and bind them to the order entity bean.  Finally, the order bean will be persisted.

The order XML message looks like this:

<order>
    <ordernumber>1</ordernumber>
    <customer>123456</customer>
    <order-items>
        <order-item>
            <product>11</product>
            <quantity>2</quantity>
        </order-item>
        <order-item>
            <product>22</product>
            <quantity>7</quantity>
        </order-item>
    </order-items>
</order>

The following custom DAO will be used to persist the Order entity:

@Dao
public class OrderDao {

   private final EntityManager em;

   public OrderDao(EntityManager em) {
     this.em = em;
   }

   @Insert
   public void insertOrder(Order order) {
     em.persist(order);
   }
}

When looking at this class you should notice the @Dao and @Insert annotations. The @Dao annotation declares that the OrderDao is a DAO object. The @Insert annotation declares that the insertOrder method should be used to insert Order entities.

The following custom DAO will be used to lookup the Product entities:

@Dao
public class ProductDao {

   private final EntityManager em;

   public ProductDao(EntityManager em) {
      this.em = em;
   }

   @Lookup(name="id")
   public Product findProductById(@Param("id") int id) {
      return em.find(Product.class, id);
   }
}

When looking at this class, you should notice the @Lookup and @Param annotation. The @Lookup annotation declares that the ProductDao#findByProductId method is used to lookup Product entities. The name parameter in the @Lookup annotation sets the lookup name reference for that method. When the name isn’t declared, the method name will be used. The optional @Param annotation let’s you name the parameters. This creates a better  abstraction between Smooks and the DAO. If you don’t declare the @Param annotation the parameters are resolved by there position.

The Smooks configuration look likes this:

<!--
    In this configuration you will see that we reference to the
    DAO's via the names 'order'  and 'product'. The persistence cartridge uses
    a DAO Register to map the DAO's to there names.
    Later on, in the java code that executes Smooks, you will see how that is done.
-->
<smooks-resource-list
   xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"
   xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.1.xsd"
   xmlns:dao="http://www.milyn.org/xsd/smooks/persistence-1.2.xsd">

   <!--
    This is a normal Javabean binding. It creates the order bean
    and binds data into it.
   -->
   <jb:bindings beanId="order" class="example.entity.Order"
                 createOnElement="order">
      <jb:value property="ordernumber" data="ordernumber"/>
      <jb:value property="customerId" data="customer"/>
      <jb:wiring setterMethod="addOrderLine" beanIdRef="orderLine" />
   </jb:bindings>

   <!--
    This is a normal Javabean binding. Notice that we have a wiring on
    'product'. The Product entity will not be created, but looked up
    by a locator.
   -->
   <jb:bindings beanId="orderLine" class="example.entity.OrderLine"
                 createOnElement="order-item">
      <jb:value property="quantity" data="quantity"/>
      <jb:wiring property="order" beanIdRef="order"/>
      <jb:wiring property="product" beanIdRef="product"/>
   </jb:bindings>

   <!--
    This locator calls (via Scribe) the ProductDao#findById() method.
    The result will be added to the bean repository under
    the bean id 'product'.
    An exception is thrown when no result is found.
   -->
   <dao:locator beanId="product" dao="product" lookup="id"
           lookupOnElement="order-item" onNoResult="EXCEPTION">
      <dao:params>
         <dao:value name="id" data="product" decoder="Integer"/>
      </dao:params>
   </dao:locator>

   <!--
    The inserter calls the OrderDao#insertOrder() method at
    end of Order message.
   -->
   <dao:inserter beanId="order" dao="order" insertOnElement="order" />

</smooks-resource-list>

The following code executes Smooks:

Smooks smooks = new Smooks("./smooks-configs/smooks-dao-config.xml");
ExecutionContext executionContext = smooks.createExecutionContext();

// The register is used to map the DAO's to a DAO name. The DAO name isbe used in
// the configuration.
// The MapRegister is a simple Map like implementation of the DaoRegister.
DaoRegister<object> register =
	MapRegister.builder()
		.put("product", new ProductDao(em))
		.put("order", new OrderDao(em))
		.build();

PersistenceUtil.setDAORegister(executionContext, mapRegister);

// Transaction management from within Smooks isn't supported yet,
// so we need to do it outside the filter execution
EntityTransaction tx = em.getTransaction();
tx.begin();

smooks.filter(new StreamSource(messageIn), null, executionContext);

tx.commit();

If you want to take this example for a spin, simply check out the examples from subversion (http://svn.codehaus.org/milyn/trunk/smooks-examples/) and you’ll find it in the “dao-router” folder.  It also shows you how to use JPA directly, without any DAOs in between.

The cartridge is almost ready for it’s first release.  There is one thing that I am still not completely sure about and it would be great if people could provide some feedback.  I am not completely happy about the action names: insert, update and delete.  In the world of persistence frameworks, different sets of names are used for these actions.  JPA, for instance, uses persist, merge and remove.  Hibernate (outside of JPA) uses save, update and delete and Ibatis uses insert, update and delete. Which names would you choose and why?

In the next post of the series I will explain how to use Hibernate directly.

You can listen to the podcast via the player on the end of this post or you can go to the original Mule blog post.  I hope that you find it interesting and useful.

I would like to thank MuleSource for enabling this interview.

The blog itself is in it’s Beta phase right now. So you can expect this blog to change  it’s appearance over the next couple of months.

I hope you will enjoy this blog and find it usefull. Please place comments if you comments or questions. We will try to answer them all.

Regards,

Maurice