Spring, Hibernate and Oracle Stored Procedures

Motivation: While there are a few resources available online for calling stored procedures from Hibernate, it took me a while to stumble across one that mostly captures what I need. The intention of this blog entry is to put a similar example into my own words, to extend it slightly and hopefully to help anyone not experienced with Hibernate and Oracle to integrate Stored Procedures and Functions into an application quickly.

Setup Oracle 10g

For this example, we will be using Oracle 10g. We can initialize our schema user with SQLPlus with the following commands:

• sqlplus connect as sysdba
• create user my_orcl identified by my_orcl;
• grant create session to my_orcl;
• grant resource to my_orcl;
• grant create table to my_orcl;

Setup a Project For Spring and Hibernate

We will download spring-framework-2.5.5-with-dependencies.zip, hibernate-distribution-3.3.1.GA-dist.zip and hibernate-annotations-3.4.0.GA.zip. We can create a standard project layout of src, test and lib folders with the following jars on the classpath:

• spring-framework-2.5.5/dist/spring.jar
• spring-framework-2.5.5/dist/modules/spring-test.jar
• spring-framework-2.5.5/lib/jakarta-commons/commons-logging.jar
• spring-framework-2.5.5/lib/jakarta-commons/commons-dbcp.jar
• spring-framework-2.5.5/lib/jakarta-commons/commons-pool.jar
• spring-framework-2.5.5/lib/jakarta-commons/commons-collections.jar
• spring-framework-2.5.5/lib/dom4j/dom4j-1.6.1.jar
• spring-framework-2.5.5/lib/log4j/log4j-1.2.15.jar
• spring-framework-2.5.5/lib/slf4j/slf4j-api-1.5.0.jar
• spring-framework-2.5.5/lib/slf4j/slf4j-log4j12-1.5.0.jar
• spring-framework-2.5.5/lib/j2ee/*.jar
• hibernate-annotations-3.4.0.GA/hibernate-annotations.jar
• hibernate-annotations-3.4.0.GA/lib/hibernate-commons-annotations.jar
• hibernate-distribution-3.3.1.GA/hibernate3.jar
• hibernate-distribution-3.3.1.GA/lib/required/javassist-3.4.GA.jar
• hibernate-distribution-3.3.1.GA/lib/required/slf4j-api-1.5.2.jar

Because we will be using Oracle Stored Procedures, we will also need a database driver such as

• oracle/product/10.2.0/db_1/jdbc/lib/ojdbc14.jar

Create Domain Objects

We can setup our domain using annotated Java. For these examples, we need one simple domain Object.

package spring.hibernate.oracle.stored.procedures.domain;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.Table;

@Entity
@Table(name = "AUTHOR", schema = "MY_ORCL")
public class Author implements java.io.Serializable {

  private static final long serialVersionUID = 8676058601610931698L;
  private int id;
  private String firstName;
  private String lastName;

  @Id
  @Column(name = "ID", nullable = false)
  public int getId() {
    return this.id;
  }

  public void setId(final int id) {
    this.id = id;
  }

  @Column(name = "FIRST_NAME", nullable = false, length = 50)
  public String getFirstName() {
    return this.firstName;
  }

  public void setFirstName(final String firstName) {
    this.firstName = firstName;
  }

  @Column(name = "LAST_NAME", nullable = false, length = 50)
  public String getLastName() {
    return this.lastName;
  }

  public void setLastName(final String lastName) {
    this.lastName = lastName;
  }
}

Create a DAO

Now that we have a domain Object, we can create a DAO for a simple operation, such as looking up Authors by last name. Fortunately, Spring provides a convenient base class for DAO operations.

package spring.hibernate.oracle.stored.procedures.dao;

import java.util.List;
import org.springframework.orm.hibernate3.support.HibernateDaoSupport;
import spring.hibernate.oracle.stored.procedures.domain.Author;

public class AuthorDAO extends HibernateDaoSupport {

 @SuppressWarnings("unchecked")
 public List<Author> findByLastNameUsingHQL(final String lastName) {
  return getHibernateTemplate().find("from Author author where author.lastName = ?", lastName);
 }
}

The Spring Application Context Configuration

The Spring applicationContext.xml can reside directly at the root of our src classpath, and it will contain information for configuring Spring to manage our Hibernate sessions, transactions and datasources, as well as our DAO.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans-2.5.xsd"
    default-autowire="constructor">
  <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource"
    destroy-method="close">
    <property name="driverClassName" value="oracle.jdbc.driver.OracleDriver" />
    <property name="url" value="jdbc:oracle:thin:@localhost:1521:orcl" />
    <property name="username" value="my_orcl" />
    <property name="password" value="my_orcl" />
  </bean>
  <bean id="sessionFactory"
    class="org.springframework.orm.hibernate3.LocalSessionFactoryBean">
    <property name="dataSource" ref="dataSource" />
    <property name="configLocation" value="classpath:/hibernate.cfg.xml" />
    <property name="configurationClass" value="org.hibernate.cfg.AnnotationConfiguration" />
    <property name="hibernateProperties">
      <props>
        <prop key="hibernate.query.factory_class">org.hibernate.hql.classic.ClassicQueryTranslatorFactory</prop>
        <prop key="hibernate.dialect">org.hibernate.dialect.Oracle10gDialect</prop>
        <prop key="hibernate.hbm2ddl.auto">create</prop>
        <prop key="hibernate.show_sql">true</prop>
      </props>
    </property>
  </bean>
  <bean id="transactionManager"
    class="org.springframework.orm.hibernate3.HibernateTransactionManager">
    <property name="sessionFactory" ref="sessionFactory" />
  </bean>
  <bean name="authorDAO"
    class="spring.hibernate.oracle.stored.procedures.dao.AuthorDAO">
    <property name="sessionFactory" ref="sessionFactory" />
  </bean>
</beans>

The Hibernate Configuration

The hibernate.cfg.xml can also reside directly in our src/ folder. The primary purpose of this file is to let Hibernate know about our domain class.

<!DOCTYPE hibernate-configuration PUBLIC
  "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
  "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
  <session-factory>
    <mapping class="spring.hibernate.oracle.stored.procedures.domain.Author" />
  </session-factory>
</hibernate-configuration>

Testing the Setup

Now that our project is setup, we can write a simple test to very that all of our configuration files can be properly loaded and that all of our connections work. We will begin by setting up some simple test data in the database, and then we can call our DAO method to find Authors by their last names. Again, we can take advantage of a convenient Spring base class for our test cases.

package spring.hibernate.oracle.stored.procedures.dao;

import org.junit.Test;
import org.springframework.test.AbstractTransactionalDataSourceSpringContextTests;

public class AuthorDAOTest extends AbstractTransactionalDataSourceSpringContextTests {

  private AuthorDAO authorDAO;

  @Override
  protected void onSetUp() throws Exception {
    super.onSetUp();
    createAuthor(1, "Jules", "Verne");
    createAuthor(2, "Charles", "Dickens");
    createAuthor(3, "Emily", "Dickinson");
    createAuthor(4, "Henry", "James");
    createAuthor(5, "William", "James");
    createAuthor(6, "Henry", "Thoreau");
  }

  @Test
  public void testFindByLastNameUsingHQL() throws Exception {
    assertEquals(2, getAuthorDAO().findByLastNameUsingHQL("James").size());
    assertEquals(1, getAuthorDAO().findByLastNameUsingHQL("Verne").size());
    assertEquals(1, getAuthorDAO().findByLastNameUsingHQL("Dickinson").size());
    assertEquals(1, getAuthorDAO().findByLastNameUsingHQL("Dickens").size());
    assertEquals(0, getAuthorDAO().findByLastNameUsingHQL("Whitman").size());
  }

  @Override
  protected String[] getConfigLocations() {
    return new String[] { "applicationContext.xml" };
  }

  public AuthorDAO getAuthorDAO() {
    return authorDAO;
  }

  public void setAuthorDAO(final AuthorDAO authorDAO) {
    this.authorDAO = authorDAO;
  }

  private void createAuthor(final int id, final String firstName, final String lastName) {
    jdbcTemplate.execute(String.format("insert into author (id, first_name, last_name) values (%d, '%s', '%s')", id,
      firstName, lastName));
  }
}

Write a Stored Procedure

Because we have specified <prop key="hibernate.hbm2ddl.auto">create</prop> in our Spring configuration for Hibernate, the AUTHOR table now exists in the database. We can write a simple stored procedure to query this table.

CREATE OR REPLACE PROCEDURE findByLastName
(  res OUT SYS_REFCURSOR, 
   vLastName IN author.last_name%type  ) AS
BEGIN
  OPEN res FOR
    SELECT * FROM author WHERE last_name = vLastName;
END findByLastName;

Call The Stored Procedure From Hibernate

Now that we have a PL/SQL Stored Procedure, we will need a way to reference it from Hibernate. We can annotate the domain Object with such a named query.

....
@Entity
@org.hibernate.annotations.NamedNativeQuery(name = "findByLastName", query = "call findByLastName(?, :vLastName)", callable = true, resultClass = Author.class)
@Table(name = "AUTHOR", schema = "MY_ORCL")
public class Author implements java.io.Serializable {
....

Now we can add a method to our AuthorDAO for calling this Stored Procedure.

....
@SuppressWarnings("unchecked")
public List<Author> findByLastNameUsingStoredProcedure(final String lastName) {
  return (List<Author>) getHibernateTemplate().execute(new HibernateCallback() {
    public Object doInHibernate(final Session session) throws HibernateException, SQLException {
      return session.getNamedQuery("findByLastName") //
                    .setParameter("vLastName", lastName) //
                    .list();
    }
  });
}
....

Finally, we will add a test case for calling the new DAO method.

....
@Test
public void testFindByLastNameUsingStoredProcedure() throws Exception {
  assertEquals(2, getAuthorDAO().findByLastNameUsingStoredProcedure("James").size());
  assertEquals(1, getAuthorDAO().findByLastNameUsingStoredProcedure("Verne").size());
  assertEquals(1, getAuthorDAO().findByLastNameUsingStoredProcedure("Dickinson").size());
  assertEquals(1, getAuthorDAO().findByLastNameUsingStoredProcedure("Dickens").size());
  assertEquals(0, getAuthorDAO().findByLastNameUsingStoredProcedure("Whitman").size());
}
....

Write a PL/SQL Function

We can similarly call an Oracle Function. Here, we will use a function that locates Authors by their first names.

CREATE OR REPLACE FUNCTION findByFirstName
(  vFirstName IN author.first_name%type  ) 
RETURN SYS_REFCURSOR AS
  res SYS_REFCURSOR;
BEGIN
  OPEN res FOR
    SELECT * FROM author WHERE first_name = vFirstName;
  RETURN res;
END findByFirstName;

Call The Function From Hibernate

We can reference this function using an org.hibernate.annotations.NamedNativeQuery, but we can also make the scenario a little more interesting by instead using the javax.persistence.NamedNativeQuery annotation in conjunction with the javax.persistence.QueryHint annotation. By using this annotation, note how we have two named queries declared on a single domain Object. Also note the braces that are necessary for the query syntax of the function but are not necessary for the stored procedure call.

....
@Entity
@org.hibernate.annotations.NamedNativeQuery(name = "findByLastName", query = "call findByLastName(?, :vLastName)", callable = true, resultClass = Author.class)
@javax.persistence.NamedNativeQuery(name = "findByFirstName", query = "{ ? = call findByFirstName(:vFirstName) }", resultClass = Author.class, hints = { @javax.persistence.QueryHint(name = "org.hibernate.callable", value = "true") })
@Table(name = "AUTHOR", schema = "MY_ORCL")
public class Author implements java.io.Serializable {
....

Again, we will access this PL/SQL function through our DAO.

....
@SuppressWarnings("unchecked")
public List<Author> findByFirstNameUsingFunction(final String firstName) {
  return (List<Author>) getHibernateTemplate().execute(new HibernateCallback() {
    public Object doInHibernate(final Session session) throws HibernateException, SQLException {
      return session.getNamedQuery("findByFirstName") //
                    .setParameter("vFirstName", firstName) //
                    .list();
    }
  });
}
....

And finally, we can add another simple test for this function call.

....
@Test
public void testFindByFirstNameUsingFunction() throws Exception {
  assertEquals(0, getAuthorDAO().findByFirstNameUsingFunction("James").size());
  assertEquals(2, getAuthorDAO().findByFirstNameUsingFunction("Henry").size());
}
....

Hopefully, this step-by-step process gives a good starting point for creating more complex stored procedure and function calls using Spring, Hibernate and Oracle.

Next: Hibernate updates and stored procedures ->