Smooks Data Integration » Scribe

Smooks Persistence part 2: How to use Hibernate/JPA

Maurice — Wed, 25 Mar 2009 11:20:09 +0000

With the new Smooks Persistence cartridge in Smooks 1.2 you can directly use several entity persistence frameworks from within Smooks. In this post I will show you how this works with Hibernate and any other JPA compatible framework.

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!

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:




	
	

		
		
		
	

	
	

		
		
		
	

	
	

		from Product p where p.id = :id

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

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.

posted in Java Binding by Maurice Leave A Comment

Smooks Persistence part 1: The Introduction

Maurice — Thu, 26 Feb 2009 11:31:44 +0000

One of the major new features in Smooks v1.2 will be the new Persistence Cartridge. This cartridge enables the use of several entity persistence frameworks from within Smooks, currently targeting Hibernate, Ibatis and any JPA compatible framework. It also allows you to use your own Data Access Objects (DAOs).

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 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:

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:

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 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.

posted in Java Binding by Maurice Leave A Comment