Spring-data-jpa Tutorial

Spring-data-jpa is one of my favorite Spring projects. This is probably because writing and editing SQL is way down my list of 'fun things to do'. The Spring-data project allows you to just write an interface for the repository and leave the actual implementation to the library. If you are familiar with Ruby it's similar to how ActiveRecord works.

All of the source code for this tutorial can be found on here.

BuildScript

I'll start off with the build script. Pretty simple and straightforward. We are using Hibernate as our JPA provider, but any should work fine. For this tutorial I'm also using the in-memory database HSQLDB. Even in real projects I like to include HSQLDB for testing. It allows us to have unit tests that hit an actual database but are still fast and work if you aren't connected to a work VPN.

	apply plugin: "java"
	apply plugin: "eclipse"
	apply plugin: "idea"
	sourceCompatibility = 1.7
	repositories {
	mavenCentral()
	}
	ext {
	hibernateVersion="4.3.1.Final"
	springVersion="4.0.1.RELEASE"
	}
	dependencies {
	compile "org.springframework:spring-context:$springVersion"
	compile "org.springframework:spring-core:$springVersion"
	compile "org.springframework:spring-jdbc:$springVersion"
	compile "org.springframework:spring-orm:$springVersion"
	compile "org.springframework:spring-tx:$springVersion"
	compile 'org.springframework.data:spring-data-jpa:1.4.3.RELEASE'
	compile "org.hibernate:hibernate-core:$hibernateVersion"
	compile "org.hibernate:hibernate-entitymanager:$hibernateVersion"
	compile 'org.hsqldb:hsqldb:2.3.0'
	testCompile 'junit:junit:4.11'
	testCompile "org.springframework:spring-test:$springVersion"
	}

view raw build.gradle hosted with ❤ by GitHub

Java Configuration

To enable the spring-data-jpa repositories add the annotation @EnableJpaRepositories and provide it with the package(s) that contain repositories. A couple of things to notice about this configuration file is that we tell Spring how to close the database when it is shutdown (@Bean(destroyMethod = "shutdown")). Failure to do this can lead to all kinds of weirdness. The second thing I wanted to point out are the properties at the bottom. Among some other things this will load the schema from the annotations in the Java files and create a file called schema.sql which you can use to create your database. This is super useful for testing using an in-memory database or as a base for creating your production database.

	package com.example;
	import java.util.Properties;
	import javax.persistence.EntityManagerFactory;
	import javax.sql.DataSource;
	import org.hibernate.cfg.Environment;
	import org.springframework.context.annotation.Bean;
	import org.springframework.context.annotation.ComponentScan;
	import org.springframework.context.annotation.Configuration;
	import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
	import org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseBuilder;
	import org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseType;
	import org.springframework.orm.hibernate4.HibernateExceptionTranslator;
	import org.springframework.orm.jpa.JpaTransactionManager;
	import org.springframework.orm.jpa.JpaVendorAdapter;
	import org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean;
	import org.springframework.orm.jpa.vendor.Database;
	import org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter;
	import org.springframework.transaction.PlatformTransactionManager;
	import org.springframework.transaction.annotation.EnableTransactionManagement;
	@Configuration
	@ComponentScan(basePackages = { "com.example.domain" })
	@EnableJpaRepositories(basePackages = { "com.example.repositories" })
	@EnableTransactionManagement
	public class AppConfig {
	public static final String DB_NAME = "testdb";
	@Bean(destroyMethod = "shutdown")
	public DataSource dataSource() {
	return new EmbeddedDatabaseBuilder().setType(EmbeddedDatabaseType.HSQL)
	.setName(DB_NAME).build();
	}
	@Bean(destroyMethod = "close")
	public EntityManagerFactory entityManagerFactory() {
	LocalContainerEntityManagerFactoryBean factory = new LocalContainerEntityManagerFactoryBean();
	factory.setDataSource(dataSource());
	factory.setPersistenceUnitName(DB_NAME);
	factory.setPackagesToScan("com.example.domain");
	factory.setJpaVendorAdapter(jpaAdapter());
	factory.setJpaProperties(jpaProperties());
	factory.afterPropertiesSet();
	return factory.getObject();
	}
	@Bean
	public JpaVendorAdapter jpaAdapter() {
	HibernateJpaVendorAdapter adapter = new HibernateJpaVendorAdapter();
	adapter.setDatabase(Database.HSQL);
	return adapter;
	}
	@Bean
	public PlatformTransactionManager transactionManager() {
	return new JpaTransactionManager(entityManagerFactory());
	}
	@Bean
	public HibernateExceptionTranslator exceptionTranslator() {
	return new HibernateExceptionTranslator();
	}
	public Properties jpaProperties() {
	Properties properties = new Properties();
	properties.put(Environment.HBM2DDL_AUTO, "create");
	properties.put(Environment.HBM2DDL_IMPORT_FILES, "data.sql");
	properties.put(
	"javax.persistence.schema-generation.create-database-schemas", "true");
	properties.put("javax.persistence.schema-generation.scripts.action",
	"create");
	properties.put("javax.persistence.schema-generation.scripts.create-target",
	"src/main/resources/schema.sql");
	properties.put("javax.persistence.database-product-name", "HSQL");
	return properties;
	}
	}

view raw AppConfig.java hosted with ❤ by GitHub

The Domain and Repository

The domain is annotated like you've been doing using JPA or Hibernate. The real magic is the repository. It's just an interface. All the implementation details are hidden away in the spring-data-jpa project. For the majority of your CRUD methods you can use the methods provided or create your own using just the method signature. If you need more control you can use the @Query annotation and provide your own SQL.

	package com.example.domain;
	import java.io.Serializable;
	import javax.persistence.Entity;
	import javax.persistence.GeneratedValue;
	import javax.persistence.Id;
	import javax.persistence.Table;
	@Entity
	@Table
	public class Person implements Serializable {
	private static final long serialVersionUID = 1L;
	@Id
	@GeneratedValue
	private Long id;
	private String firstName;
	private String lastName;
	public Person() {
	}
	public Person(String firstName, String lastName) {
	this.firstName = firstName;
	this.lastName = lastName;
	}
	public Long getId() {
	return id;
	}
	public void setId(Long id) {
	this.id = id;
	}
	public String getFirstName() {
	return firstName;
	}
	public void setFirstName(String firstName) {
	this.firstName = firstName;
	}
	public String getLastName() {
	return lastName;
	}
	public void setLastName(String lastName) {
	this.lastName = lastName;
	}
	@Override
	public int hashCode() {
	final int prime = 31;
	int result = 1;
	result = prime * result + ((firstName == null) ? 0 : firstName.hashCode());
	result = prime * result + ((lastName == null) ? 0 : lastName.hashCode());
	return result;
	}
	@Override
	public boolean equals(Object obj) {
	if (this == obj)
	return true;
	if (obj == null)
	return false;
	if (getClass() != obj.getClass())
	return false;
	Person other = (Person) obj;
	if (firstName == null) {
	if (other.firstName != null)
	return false;
	}
	else if (!firstName.equals(other.firstName))
	return false;
	if (lastName == null) {
	if (other.lastName != null)
	return false;
	}
	else if (!lastName.equals(other.lastName))
	return false;
	return true;
	}
	}

view raw Person.java hosted with ❤ by GitHub

	package com.example.repositories;
	import java.util.List;
	import org.springframework.data.repository.CrudRepository;
	import com.example.domain.Person;
	public interface PersonRepository extends CrudRepository<Person, Long> {
	List<Person> findByFirstName(String firstName);
	List<Person> findByLastName(String lastName);
	List<Person> findByLastNameContaining(String partialLastName);
	}

view raw PersonRepository.java hosted with ❤ by GitHub

A test

A test to make sure everything works

	insert into Person (firstName, lastName) values ('John', 'Doe');
	insert into Person (firstName, lastName) values ('John', 'Smith');
	insert into Person (firstName, lastName) values ('Jane', 'Doe');

view raw data.sql hosted with ❤ by GitHub

	package com.example.repositories;
	import static org.junit.Assert.assertEquals;
	import static org.junit.Assert.assertNotNull;
	import static org.junit.Assert.assertNull;
	import static org.junit.Assert.assertTrue;
	import java.util.List;
	import javax.annotation.Resource;
	import org.junit.Test;
	import org.junit.runner.RunWith;
	import org.springframework.test.context.ContextConfiguration;
	import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
	import com.example.AppConfig;
	import com.example.domain.Person;
	@RunWith(SpringJUnit4ClassRunner.class)
	@ContextConfiguration(classes = { AppConfig.class })
	public class PersonRepositoryTest {
	@Resource
	private PersonRepository personRepository;
	@Test
	public void crud() {
	Person me = new Person("Josh", "Brackett");
	Person saved = personRepository.save(me);
	assertNotNull(saved);
	assertNotNull(saved.getId());
	Long id = saved.getId();
	Person got = personRepository.findOne(id);
	assertNotNull(got);
	assertEquals(saved, got);
	got.setFirstName("Joshua");
	Person updated = personRepository.save(got);
	assertNotNull(updated);
	assertEquals("Joshua", updated.getFirstName());
	personRepository.delete(id);
	Person deleted = personRepository.findOne(id);
	assertNull(deleted);
	}
	@Test
	public void getJohns() {
	List<Person> persons = personRepository.findByFirstName("John");
	assertNotNull(persons);
	assertEquals(2, persons.size());
	for (Person person : persons) {
	assertEquals("John", person.getFirstName());
	}
	}
	@Test
	public void getDoes() {
	List<Person> persons = personRepository.findByLastName("Doe");
	assertNotNull(persons);
	assertEquals(2, persons.size());
	for (Person person : persons) {
	assertEquals("Doe", person.getLastName());
	}
	}
	@Test
	public void getPartialMatch() {
	String partial = "mit";
	List<Person> persons = personRepository.findByLastNameContaining(partial);
	assertNotNull(persons);
	assertEquals(1, persons.size());
	for (Person person : persons) {
	assertTrue(person.getLastName().contains(partial));
	}
	}
	}

view raw PersonRepositoryTest.java hosted with ❤ by GitHub

If this has piqued your interest I highly recommend reading through the spring-data-jpa documentation. It's relatively short and very well written in my opinion.

Generating Schema with JPA/Hibernate

When creating new projects I tend to create the application code first and generate the database schema from that code. One of the nicer things added in JPA 2.1, which has been supported in Hibernate for several years, is the ability to generate a schema based on Java annotated classes. In practice I've found that in order to accomplish generating the schema and using it to test with an in memory database requires both Hibernate and JPA properties.

These properties will generate a script called schema.sql that will create the schema for an HSQL database. It will also load that schema with data from a file called data.sql. Note that data.sql needs to be on the classpath.

    jpaProperties.put(Environment.HBM2DDL_AUTO, "create");
    jpaProperties.put(Environment.HBM2DDL_IMPORT_FILES, "data.sql");
    jpaProperties.put("javax.persistence.schema-generation.create-database-schemas", "true");
    jpaProperties.put("javax.persistence.schema-generation.scripts.action", "create");
    jpaProperties.put("javax.persistence.schema-generation.scripts.create-target",
        "src/test/resources/schema.sql");
    jpaProperties.put("javax.persistence.database-product-name", "HSQL");

 See the complete Java configuration on github here. It uses Spring framework, Spring-data-jpa, and Hibernate.

Modern Spring 4 MVC Hello World Tutorial

I was browsing reddit as I am wont to do at pretty much any hour of any day and came across a Spring 4 MVC tutorial. At work I use Spring 4 and was curious what a beginner tutorial would look like. Even though it was a small tutorial I expected to see things like @RestController and JavaConfig. I even hoped to see Gradle, but alas it was all XML configuration and a maven build with even more XML. No wonder people get such a bad impression of Spring and Java. Below I've quickly put together a tutorial using techniques I use working with Spring 4. I'm glossing over some things so if something doesn't make sense just leave a comment. It's super simple and some things are overkill but it's just so you can get a flavor of what working with Java and Spring 4 can really be like.

All the code can be found on it's github repository.

The build file

The most important parts are the repositories section and the dependencies section. The repositories section defines where to find the dependencies of your project designated in the dependencies section. In this case we can get everything from Maven central. The ext section defines some variables used for the specific versions of your dependencies. The buildscript section allows us to add functionality into gradle. In this case we are adding a tomcat plugin so we can launch a tomcat instance directly from the gradle build.

	apply plugin: "eclipse"
	apply plugin: "idea"
	apply plugin: "war"
	apply plugin: "tomcat"
	war { baseName='hello-world' }
	sourceCompatibility = 1.7
	buildscript {
	repositories {
	jcenter()
	}
	dependencies { classpath 'org.gradle.api.plugins:gradle-tomcat-plugin:1.0' }
	}
	repositories {
	mavenCentral()
	}
	ext {
	jacksonVersion="2.2.3"
	springVersion="4.0.1.RELEASE"
	tomcatVersion="7.0.50"
	}
	dependencies {
	providedCompile "javax.servlet:javax.servlet-api:3.1.0", "javax.servlet.jsp:jsp-api:2.1"
	runtime ("javax.servlet:jstl:1.2") {
	exclude group: "javax.servlet", module: "javax.servlet-api"
	exclude group: "javax.servlet", module: "jsp-api"
	}
	compile "org.springframework:spring-context:$springVersion"
	compile "org.springframework:spring-core:$springVersion"
	compile "org.springframework:spring-web:$springVersion"
	compile "org.springframework:spring-webmvc:$springVersion"
	compile "com.fasterxml.jackson.core:jackson-core:$jacksonVersion"
	compile "com.fasterxml.jackson.core:jackson-databind:$jacksonVersion"
	compile "com.fasterxml.jackson.core:jackson-annotations:$jacksonVersion"
	testCompile "junit:junit:4.11"
	testCompile "org.springframework:spring-test:$springVersion"
	tomcat "org.apache.tomcat.embed:tomcat-embed-core:$tomcatVersion",
	"org.apache.tomcat.embed:tomcat-embed-logging-juli:$tomcatVersion"
	tomcat("org.apache.tomcat.embed:tomcat-embed-jasper:$tomcatVersion") {
	exclude group: 'org.eclipse.jdt.core.compiler', module: 'ecj'
	}
	}

view raw build.gradle hosted with ❤ by GitHub

The Configuration

We will be using a completely XML-less configuration. This requires a server that supports servlet 3.0 and above. This means >= Tomcat 7 or >= Jetty 8. Major takeaway is that we will put our controller in the com.hello.controller package so we need to scan that package.

	package com.hello;
	import org.springframework.context.annotation.ComponentScan;
	import org.springframework.context.annotation.Configuration;
	@Configuration
	@ComponentScan(basePackages = { "com.hello.controller", "com.hello.config" })
	public class AppConfig {
	}

view raw AppConfig.java hosted with ❤ by GitHub

	package com.hello.config;
	import javax.servlet.Filter;
	import javax.servlet.ServletRegistration.Dynamic;
	import org.springframework.web.filter.CharacterEncodingFilter;
	import org.springframework.web.filter.HiddenHttpMethodFilter;
	import org.springframework.web.filter.HttpPutFormContentFilter;
	import org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer;
	import com.hello.AppConfig;
	import com.hello.WebConfig;
	public class ServletInitializer extends
	AbstractAnnotationConfigDispatcherServletInitializer {
	@Override
	protected Class<?>[] getRootConfigClasses() {
	return new Class[] { AppConfig.class };
	}
	@Override
	protected Class<?>[] getServletConfigClasses() {
	return new Class[] { WebConfig.class };
	}
	@Override
	protected String[] getServletMappings() {
	return new String[] { "/" };
	}
	@Override
	protected void customizeRegistration(Dynamic registration) {
	registration.setInitParameter("dispatchOptionsRequest", "true");
	}
	@Override
	protected Filter[] getServletFilters() {
	CharacterEncodingFilter charFilter = new CharacterEncodingFilter();
	charFilter.setEncoding("UTF-8");
	charFilter.setForceEncoding(true);
	return new Filter[] { new HiddenHttpMethodFilter(), charFilter,
	new HttpPutFormContentFilter() };
	}
	}

view raw ServletInitializer.java hosted with ❤ by GitHub

	package com.hello;
	import org.springframework.context.annotation.ComponentScan;
	import org.springframework.context.annotation.Configuration;
	import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
	import org.springframework.web.servlet.config.annotation.EnableWebMvc;
	import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
	@EnableWebMvc
	@Configuration
	@ComponentScan(basePackages = "com.hello.controller")
	public class WebConfig extends WebMvcConfigurerAdapter {
	@Override
	public void configureDefaultServletHandling(
	DefaultServletHandlerConfigurer configurer) {
	configurer.enable();
	}
	}

view raw WebConfig.java hosted with ❤ by GitHub

The Controller

Spring 4 introduced a new controller annotation @RestController. This is just a convenience annotation that means the class is an @Controller class and all the methods are @ResponseBody methods. This is a nice addition when building out REST webservices using Spring MVC.

	package com.hello.controller;
	import org.springframework.web.bind.annotation.PathVariable;
	import org.springframework.web.bind.annotation.RequestMapping;
	import org.springframework.web.bind.annotation.RequestMethod;
	import org.springframework.web.bind.annotation.RestController;
	@RestController
	@RequestMapping("/hello")
	public class HelloController {
	@RequestMapping(method = RequestMethod.GET, value = "/{name}")
	public String sayHello(@PathVariable("name") String name) {
	return name + " from the server";
	}
	}

view raw HelloController.java hosted with ❤ by GitHub

The view

We are using AngularJS to interact with our controller. The way most of the webapps I've been writing lately work is having a Java backend provide a REST webservice to a javascript frontend. There are pros and cons to this approach which can be debated but I've been having fun and been productive using this method.

	/*jshint unused: false */
	/*global angular:true */
	// Declare app level module
	var App = angular.module('App', []);
	(function() {
	'use strict';
	App.controller("HelloCtrl", ['$scope', '$http',
	function($scope, $http) {
	$scope.name = "User";
	$scope.message = "";
	$scope.getName = function() {
	$http.get('hello/' + $scope.name).then(function(response) {
	$scope.message = "Hello " + response.data;
	});
	};
	}
	]);
	})();

view raw app.js hosted with ❤ by GitHub

	<!DOCTYPE html>
	<html ng-app="App">
	<head>
	<meta http-equiv="content-type" content="text/html; charset=utf-8" />
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Hello</title>
	</head>
	<body ng-controller="HelloCtrl">
	<input type="text" ng-model="name"></input><button ng-click="getName()">Submit</button>
	<div>{{message}}</div>
	<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.2.11/angular.js"></script>
	<script src="js/app.js"></script>
	</body>
	</html>

view raw index.html hosted with ❤ by GitHub

The Controller Test

Spring has really nice support for testing your controllers as well.

	package com.hello.controller;
	import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
	import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
	import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
	import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
	import org.junit.Before;
	import org.junit.Test;
	import org.junit.runner.RunWith;
	import org.springframework.beans.factory.annotation.Autowired;
	import org.springframework.http.MediaType;
	import org.springframework.test.context.ContextConfiguration;
	import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
	import org.springframework.test.context.web.WebAppConfiguration;
	import org.springframework.test.web.servlet.MockMvc;
	import org.springframework.test.web.servlet.setup.MockMvcBuilders;
	import org.springframework.web.context.WebApplicationContext;
	import com.hello.AppConfig;
	import com.hello.WebConfig;
	@RunWith(SpringJUnit4ClassRunner.class)
	@WebAppConfiguration
	@ContextConfiguration(classes = { AppConfig.class, WebConfig.class })
	public class HelloControllerTest {
	@Autowired
	private WebApplicationContext wac;
	private MockMvc mockMvc;
	@Before
	public void setup() throws Exception {
	mockMvc = MockMvcBuilders.webAppContextSetup(wac).build();
	}
	@Test
	public void helloTest() throws Exception {
	String name = "Test";
	mockMvc
	.perform(get("/hello/{name}", name).accept(MediaType.APPLICATION_JSON))
	.andDo(print())
	.andExpect(status().isOk())
	.andExpect(
	content().contentTypeCompatibleWith(MediaType.APPLICATION_JSON))
	.andExpect(content().string(name + " from the server"));
	}
	}

view raw HelloControllerTest.java hosted with ❤ by GitHub

Result

Make sure you have JDK 7 installed and then run it yourself by grabbing the code and from the command line run ./gradlew tomcatRun for OSX/Linux or gradlew.bat tomcatRun if you are on Windows. Gradle should take care of everything else for you.

Package Filters in Eclipse

Package filtering is a way to help weed out all those useless packages that pop up when importing a class into some code you are writing.

In the video below I show you how to set it up.

Open resources in eclipse

The open resources dialog is a quick and easy way to navigate through your code base. In my opinion it becomes essential once the code base reaches a non-trivial size.

Opened using Ctrl-R in Windows/Linux and Cmd-R in OSX.