Using Spring JPA

Introduction

Spring JPA is a quick method for providing CRUD functionality around an RDBMS.

Using Spring JPA, I can define an @Entity and then create a @Repository interface that takes the persisted entity as a generic type.  

In the repository interface, I define method names, like this:

 List<Gngram> findByCollectionNameAndFocalTermAndFocalPos(Pageable pageable, String collectionName, String focalTerm, String focalPos);   

The implementation is handled automagically by Spring.

I don't have to write a single line of SQL, JQL, or any query language.  This allows us to get basic CRUD functionality around any relational table or view in a matter of minutes.


In this example, we'll be using this table:

This table holds a Google n-Gram.  The format of each record is explained here.  As each record is read from a file, the database is updated.

Outline

• How to configure a project
• This tutorial assumes the use of Maven: Installing Maven and Creating a Java Project in Maven are important skills to have.
• A background in Dependency Injection with Spring is essential.
• Java Package Layout
• Defining the Entity
• Defining the Repository
• Writing a test class
• Custom Methods
• When Spring JPA is not sufficient

Environment

1. JDK 7
2. Maven 3.2.3
3. Spring
1. Context, Core, JDBC 4.1.3
2. Data-Commons and Data-JPA 4.1.4
4. MySQL 5.1.27

JAR dependencies are specified in Maven and the exact version numbers given here:

The POM

My POM file looks like this:

 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">  
      <modelVersion>4.0.0</modelVersion>  
   
      <groupId>com.mycompany.app</groupId>  
      <artifactId>mycompany-app</artifactId>  
      <version>4.1.4</version>  
      <packaging>pom</packaging>  
   
      <properties>  
           <spring-context.version>4.1.3.RELEASE</spring-context.version>  
           <spring-core.version>4.1.3.RELEASE</spring-core.version>  
           <spring-jdbc.version>4.1.3.RELEASE</spring-jdbc.version>  
           <spring-data-commons-core.version>1.4.1.RELEASE</spring-data-commons-core.version>  
           <spring-data-jpa.version>1.7.1.RELEASE</spring-data-jpa.version>  
           <hibernate-entitymanager.version>4.3.7.Final</hibernate-entitymanager.version>  
      </properties>  
   
      <dependencies>  
   
           <!-- Spring -->  
           <dependency>  
                <groupId>org.springframework</groupId>  
                <artifactId>spring-context</artifactId>  
                <version>${spring-context.version}</version>  
           </dependency>  
           <dependency>  
                <groupId>org.springframework</groupId>  
                <artifactId>spring-core</artifactId>  
                <version>${spring-core.version}</version>  
           </dependency>  
           <dependency>  
                <groupId>org.springframework</groupId>  
                <artifactId>spring-jdbc</artifactId>  
                <version>${spring-jdbc.version}</version>  
           </dependency>  
           <dependency>  
                <groupId>org.springframework.data</groupId>  
                <artifactId>spring-data-commons</artifactId>  
                <!--version>1.6.3.RELEASE</version-->  
                <version>1.9.1.RELEASE</version>  
   
           </dependency>  
           <dependency>  
                <groupId>org.springframework.data</groupId>  
                <artifactId>spring-data-jpa</artifactId>  
                <version>1.7.1.RELEASE</version>  
           </dependency>  
           <dependency>  
                <groupId>org.hibernate</groupId>  
                <artifactId>hibernate-entitymanager</artifactId>  
                <version>4.3.1.Final</version>  
           </dependency>  
   
           <!-- MySQL -->  
           <dependency>  
                <groupId>mysql</groupId>  
                <artifactId>mysql-connector-java</artifactId>  
                <version>5.1.27</version>  
           </dependency>  
             
           <!-- Commons JDBC -->  
           <dependency>  
                <groupId>commons-pool</groupId>  
                <artifactId>commons-pool</artifactId>  
                <version>20030825.183949</version>  
           </dependency>  
           <dependency>  
                <groupId>commons-dbcp</groupId>  
                <artifactId>commons-dbcp</artifactId>  
                <version>20030825.184428</version>  
           </dependency>  
           <dependency>  
                <groupId>commons-collections</groupId>  
                <artifactId>commons-collections</artifactId>  
                <version>20040616</version>  
           </dependency>  
   
      </dependencies>  
   
 </project>  

The groupId and artifactId in red text above should be changed.

The Application Context

The primary configuration is in the application-context.xml file for the project. This configuration file provides the context for the Spring IoC container.

My context file looks like this:

 <?xml version="1.0" encoding="UTF-8"?>  
 <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:context="http://www.springframework.org/schema/context" xmlns:jpa="http://www.springframework.org/schema/data/jpa" xmlns:repository="http://www.springframework.org/schema/data/repository" xmlns:tx="http://www.springframework.org/schema/tx"  
      xsi:schemaLocation="http://www.springframework.org/schema/data/repository http://www.springframework.org/schema/data/repository/spring-repository-1.6.xsd  
           http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd  
           http://www.springframework.org/schema/data/jpa http://www.springframework.org/schema/data/jpa/spring-jpa-1.3.xsd  
           http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-3.1.xsd  
           http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-4.0.xsd">  
   
      <context:annotation-config />  
      <jpa:repositories base-package="org.swtk.ngrams.google.db.data.repositories" />  
      <context:component-scan base-package="org.swtk.ngrams.google.db.data" />  
   
      <bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">  
           <property name="dataSource" ref="datasource" />  
           <property name="persistenceUnitName" value="swtk-gngrams" />  
           <property name="packagesToScan" value="org.swtk.ngrams.google.db" />  
           <property name="jpaVendorAdapter">  
                <bean class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter">  
                     <property name="showSql" value="false" />  
                     <property name="database" value="MYSQL" />  
                </bean>  
           </property>  
      </bean>  
   
      <bean id="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager">  
           <property name="entityManagerFactory" ref="entityManagerFactory" />  
      </bean>  
   
      <bean id="datasource" class="org.apache.commons.dbcp.BasicDataSource">  
           <property name="url" value="jdbc:mysql://127.0.0.1:3306/gngrams" />  
           <property name="username" value="userid" />  
           <property name="password" value="password" />  
           <property name="driverClassName" value="com.mysql.jdbc.Driver" />  
      </bean>  
   
 </beans>  

The text highlighted in red should be changed.

Package Layout

I use the following package layout:

• com.mycompany.app.data
• entities
• repositories
• service

The entities package contains the persistent POJOs that map to tables in the database.  The repositories package contains granular methods for accessing data in the database.  The service package contains coarser-grained methods for accessing data; perhaps using multiple methods from multiple repositories and returning a combined result to a consumer.

Entities

My entity class reflects the table in the image at the start of this article.

To any developer already familiar with ORM solutions, the annotations on this POJO should be straightforward:

 package org.swtk.ngrams.google.db.data.entities;  
   
 import javax.persistence.Column;  
 import javax.persistence.Entity;  
 import javax.persistence.GeneratedValue;  
 import javax.persistence.GenerationType;  
 import javax.persistence.Id;  
 import javax.persistence.Table;  
   
 import org.swtk.common.core.util.StringUtils;  
   
 @Entity  
 @Table(name = "gngram")  
 public class Gngram {  
   
      /**  
       *     Purpose:  
       *     The name of the collection file  
       *  
       *     eg. this is typically the underlying source file that contains the google n-grams  
       */  
      @Column(name = "COLLECTION_NAME")  
      private String     collectionName;  
   
      /**  
       *     Purpose:  
       *     The term with an attached part-of-speech  
       *  
       *     eg. given this n-Gram:  
       *          "had well_ADV organized"  
       *     the focal pos is  
       *          "ADV"  
       */  
      @Column(name = "FOCAL_POS")  
      private String     focalPos;  
   
      /**  
       *     Purpose:  
       *     The term with an attached part-of-speech  
       *  
       *     eg. given this n-Gram:  
       *          "had well_ADV organized"  
       *     the focal term is  
       *          "well"  
       */  
      @Column(name = "FOCAL_TERM")  
      private String     focalTerm;  
   
      /**  
       *     Purpose:  
       *     The primary key   
       */  
      @Id  
      @Column(name = "ID")  
      @GeneratedValue(strategy = GenerationType.IDENTITY)  
      private Integer     id;  
   
      /**  
       *     Purpose:  
       *     The number of times the n-Gram was found (across the entire collection)  
       */  
      @Column(name = "MATCH_COUNT")  
      private Double     matchCount;  
   
      /**  
       *     Purpose:  
       *     The number of volumes the n-Gram was found in  
       */  
      @Column(name = "VOLUME_COUNT")  
      private Double     volumeCount;  
   
      public String getCollectionName() {  
           return collectionName;  
      }  
   
      public String getFocalPos() {  
           return focalPos;  
      }  
   
      public String getFocalTerm() {  
           return focalTerm;  
      }  
   
      public Integer getId() {  
           return id;  
      }  
   
      public Double getMatchCount() {  
           return matchCount;  
      }  
   
      public Double getVolumeCount() {  
           return volumeCount;  
      }  
   
      public boolean hasFocalPos() {  
           return StringUtils.hasValue(getFocalPos());  
      }  
   
      public boolean hasFocalTerm() {  
           return StringUtils.hasValue(getFocalTerm());  
      }  
   
      public void setCollectionName(String collectionName) {  
           this.collectionName = collectionName;  
      }  
   
      public void setFocalPos(String focalPos) {  
           this.focalPos = focalPos;  
      }  
   
      public void setFocalTerm(String focalTerm) {  
           this.focalTerm = focalTerm;  
      }  
   
      public void setId(Integer id) {  
           this.id = id;  
      }  
   
      public void setMatchCount(Double matchCount) {  
           this.matchCount = matchCount;  
      }  
   
      public void setVolumeCount(Double volumeCount) {  
           this.volumeCount = volumeCount;  
      }  
 }  
   

Repositories

The Repository interface extends the JpaRepository interface, and takes the persistent entity as a generic type:

 package org.swtk.ngrams.google.db.data.repositories;  

 import java.util.List;  
 import org.springframework.data.domain.Pageable;  
 import org.springframework.data.jpa.repository.JpaRepository;  
 import org.springframework.stereotype.Repository;  
 import org.swtk.ngrams.google.db.data.entities.Gngram;  

 @Repository  
 public interface GngramRepository extends JpaRepository<Gngram, Integer> {  

      List<Gngram> findByCollectionName(Pageable pageable, String collectionName);  

      List<Gngram> findByCollectionNameAndFocalPos(Pageable pageable, String collectionName, String focalPos);  

      List<Gngram> findByCollectionNameAndFocalTerm(Pageable pageable, String collectionName, String focalTerm);  

      List<Gngram> findByCollectionNameAndFocalTermAndFocalPos(Pageable pageable, String collectionName, String focalTerm, String focalPos);  
 }  

The pageable parameter allows the specification of the page and number of results per page.  The remaining parameters are inserted into the query generated by Spring for each of these method implementations.

Test Case

The test case looks like this:

 package org.swtk.ngrams.google.db.data.repositories;  
   
 import static org.junit.Assert.assertEquals;  
 import static org.junit.Assert.assertNotNull;  
   
 import java.util.ArrayList;  
 import java.util.List;  
   
 import org.junit.Test;  
 import org.swtk.common.core.env.LogManager;  
 import org.swtk.ngrams.google.db.data.entities.Gngram;  
 import org.swtk.ngrams.google.db.util.adapter.GngramAdapter;  
 import org.swtk.ngrams.ioc.NgramsIocContainer;  
   
 public class GngramRepositoryTest {  
   
      public static LogManager     logger               = new LogManager(GngramRepositoryTest.class);  
   
      private static final String     COLLECTION_NAME     = "test-run-grt";  
   
      private void createAndSave(GngramRepository gngramRepository) throws Throwable {  
           List<Gngram> list = new ArrayList<Gngram>();  
   
           list.add(GngramAdapter.transform(COLLECTION_NAME, "had well_ADV organized     1904     11     11"));  
           list.add(GngramAdapter.transform(COLLECTION_NAME, "had well_NOUN organized     1934     22     22"));  
   
           gngramRepository.save(list);  
      }  
   
      @Test  
      public void run() throws Throwable {  
   
           GngramRepository gngramRepository = NgramsIocContainer.getGngramsContext().getBean(GngramRepository.class);  
           assertNotNull(gngramRepository);  
   
           /* clear database: test prep */  
           gngramRepository.delete(gngramRepository.findByCollectionName(null, COLLECTION_NAME));  
   
           /* create and save the entity */  
           createAndSave(gngramRepository);  
   
           /* test basic retrieval methods */  
           assertEquals(2, gngramRepository.findByCollectionNameAndFocalTerm(null, COLLECTION_NAME, "well").size());  
           assertEquals(1, gngramRepository.findByCollectionNameAndFocalPos(null, COLLECTION_NAME, "ADV").size());  
   
           /* clear database: test cleanup */  
           gngramRepository.delete(gngramRepository.findByCollectionName(null, COLLECTION_NAME));  
      }  
 }  

I don't have a services class defined for this example.

References

1. Official Spring JPA Documentation
1. At some point, every Spring JPA developer should read through this documentation completely.
2. Supported Keywords Inside Method Names
1. The complete list of keywords and samples.  
2. Essentially an EBNF-like table for writing methods in your interface.
2. Using Custom Queries with Query Methods
1. Generic queries can only take you so far.
2. [Stackoverflow] Custom Methods belong in separate interfaces
1. Putting a @Query annotation over a method in an interface that extends JpaRepository doesn't seem to work as well as some articles suggest.