Petri Kainulainen

Spring Data JPA Tutorial Three: Custom Queries with Query Methods

Petri — Sun, 05 Feb 2012 17:55:56 +0000

The second part of my Spring Data JPA tutorial described how you can create a simple CRUD application with Spring Data JPA. This blog entry will describe how you can use query methods for creating custom queries with Spring Data JPA. In order to have a reasonable example, I have created three new requirements for my example application:

It must be possible to search persons by using their last name as a search criteria.
The search function must return only such persons which last name is an exact match with the given search criteria.
The search must be case insensitive.

Spring Data JPA provides three different approaches for creating custom queries with query methods. Each of these approaches is described in following.

Query Creation from Method Name

Spring Data JPA has a built in query creation mechanism which can be used for parsing queries straight from the method name of a query method. This mechanism first removes common prefixes from the method name and parses the constraints of the query from the rest of the method name. The query builder mechanism is described with more details in Defining Query Methods Subsection of Spring Data JPA reference documentation.

Using this approach is quite simple. All you have to do is to ensure that the method names of your repository interface are created by combining the property names of an entity object and the supported keywords. The Query Creation Subsection of the Spring Data JPA reference documentation has nice examples concerning the usage of supported keywords.

The source code of the repository method which is using this approach is given in following:

/**
* Specifies methods used to obtain and modify person related information
* which is stored in the database.
* @author Petri Kainulainen
*/
public interface PersonRepository extends JpaRepository<Person, Long> {

/**
* Finds persons by using the last name as a search criteria.
* @param lastName
* @return A list of persons which last name is an exact match with the given last name.
* If no persons is found, this method returns an empty list.
*/
public List<Person> findByLastName(String lastName);
}

The strength of this approach is that it is rather fast to implement simple queries. On the other hand, if your query has many parameters, your method name will be rather long and ugly. Also, if the keyword you need is not supported by Spring Data JPA, you are out of luck.

A good example of this is the fact that at the moment you cannot use the lower keyword in your method names. This means that this approach cannot be used to fulfill the requirements which I specified in the beginning.

JPA Named Queries

Spring Data JPA provides also support for the JPA Named Queries. You have got following alternatives for declaring the named queries:

You can use either named-query XML element or @NamedQuery annotation to create named queries with the JPA query language.
You can use either named-native-query XML element or @NamedNative query annotation to create queries with SQL if you are ready to tie your application with a specific database platform.

The only thing you have to do to use the created named queries is to name the query method of your repository interface to match with the name of your named query. I have chosen to specify the named query by using @NamedQuery annotation in my entity class.

The source code of the Person class is given in following:

/**
* An entity class which contains the information of a single person.
* @author Petri Kainulainen
*/
@Entity
@NamedQuery(name = "Person.findByName", query = "SELECT p FROM Person p WHERE LOWER(p.lastName) = LOWER(?1)")
@Table(name = "persons")
public class Person {

@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private Long id;

@Column(name = "creation_time", nullable = false)
private Date creationTime;

@Column(name = "first_name", nullable = false)
private String firstName;

@Column(name = "last_name", nullable = false)
private String lastName;

@Column(name = "modification_time", nullable = false)
private Date modificationTime;

@Version
private long version = 0;

public Long getId() {
return id;
}

/**
* Gets a builder which is used to create Person objects.
* @param firstName The first name of the created user.
* @param lastName The last name of the created user.
* @return A new Builder instance.
*/
public static Builder getBuilder(String firstName, String lastName) {
return new Builder(firstName, lastName);
}

public Date getCreationTime() {
return creationTime;
}

public String getFirstName() {
return firstName;
}

public String getLastName() {
return lastName;
}

/**
* Gets the full name of the person.
* @return The full name of the person.
*/
@Transient
public String getName() {
StringBuilder name = new StringBuilder();

name.append(firstName);
name.append(" ");
name.append(lastName);

return name.toString();
}

public Date getModificationTime() {
return modificationTime;
}

public long getVersion() {
return version;
}

public void update(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}

@PreUpdate
public void preUpdate() {
modificationTime = new Date();
}

@PrePersist
public void prePersist() {
Date now = new Date();
creationTime = now;
modificationTime = now;
}

@Override
public String toString() {
return ToStringBuilder.reflectionToString(this);
}

/**
* A Builder class used to create new Person objects.
*/
public static class Builder {
Person built;

/**
* Creates a new Builder instance.
* @param firstName The first name of the created Person object.
* @param lastName The last name of the created Person object.
*/
Builder(String firstName, String lastName) {
built = new Person();
built.firstName = firstName;
built.lastName = lastName;
}

/**
* Builds the new Person object.
* @return The created Person object.
*/
public Person build() {
return built;
}
}

/**
* This setter method should only be used by unit tests.
* @param id
*/
protected void setId(Long id) {
this.id = id;
}
}

The relevant part of my PersonRepository interface looks following:

/**
* Specifies methods used to obtain and modify person related information
* which is stored in the database.
* @author Petri Kainulainen
*/
public interface PersonRepository extends JpaRepository<Person, Long> {

/**
* Finds person by using the last name as a search criteria.
* @param lastName
* @return A list of persons whose last name is an exact match with the given last name.
* If no persons is found, this method returns null.
*/
public List<Person> findByName(String lastName);
}

Using named queries is valid option if your application is small or if you have to use native queries. If your application has a lot of custom queries, this approach will litter the code of your entity class with query declarations (You can of course use the XML configuration to avoid this but in my opinion this approach is even more horrible).

@Query Annotation

The @Query annotation can be used to create queries by using the JPA query language and to bind these queries directly to the methods of your repository interface. When the query method is called, Spring Data JPA will execute the query specified by the @Query annotation (If there is a collision between the @Query annotation and the named queries, the query specified by using @Query annotation will be executed).

The source code of the repository method which is implemented by using this approach is given in following:

/**
* Specifies methods used to obtain and modify person related information
* which is stored in the database.
* @author Petri Kainulainen
*/
public interface PersonRepository extends JpaRepository<Person, Long> {

/**
* Finds a person by using the last name as a search criteria.
* @param lastName
* @return A list of persons whose last name is an exact match with the given last name.
* If no persons is found, this method returns an empty list.
*/
@Query("SELECT p FROM Person p WHERE LOWER(p.lastName) = LOWER(:lastName)")
public List<Person> find(@Param("lastName") String lastName);
}

This approach gives you access to the JPA query language and keeps your queries in the repository layer where they belong. On the other hand, you cannot use the @Query annotation (I will describe more advanced strategies in the next parts of this tutorial) if the JPA query language cannot be used to create the query you need.

Using Created Query Methods

I have now described you three ways to create query methods with Spring Data JPA. The next step is to take a look of the service class which uses the created query methods.

The SearchType enumeration identifies the used query method. Its source code is given in following:

/**
* Describes the search type of the search. Legal values are:
*

METHOD_NAME which means that the query is obtained from the method name of the query method.

NAMED_QUERY which means that a named query is used.

QUERY_ANNOTATION which means that the query method annotated with @Query annotation is used.

* @author Petri Kainulainen
*/
public enum SearchType {
METHOD_NAME,
NAMED_QUERY,
QUERY_ANNOTATION;
}

The SearchDTO is a simple DTO object which contains the search term given by the user and identifies the used query method. Its source code is given in following:

/**
* A DTO class which is used as a form object in the search form.
* @author Petri Kainulainen
*/
public class SearchDTO {

private String searchTerm;

private SearchType searchType;

public SearchDTO() {

}

public String getSearchTerm() {
return searchTerm;
}

public void setSearchTerm(String searchTerm) {
this.searchTerm = searchTerm;
}

public SearchType getSearchType() {
return searchType;
}

public void setSearchType(SearchType searchType) {
this.searchType = searchType;
}

@Override
public String toString() {
return ToStringBuilder.reflectionToString(this);
}
}

The PersonService interface has got one new method . The relevant part of the PersonService interface is described in following:

/**
* Declares methods used to obtain and modify person information.
* @author Petri Kainulainen
*/
public interface PersonService {

/**
* Searches persons by using the search criteria given as a parameter.
* @param searchCriteria
* @return A list of persons matching with the search criteria. If no persons is found, this method
* returns an empty list.
* @throws IllegalArgumentException if search type is not given.
*/
public List<Person> search(SearchDTO searchCriteria);
}

The actual implementation of the search() method is responsible of selecting the correct query method and passing the given search term to it. The source of my search() method implementation is given in following:

What is Next?

I have now described to you how you can use query methods for creating custom queries with Spring Data JPA. If you are interested of seeing my example application in action, you can get it from Github. The next part of my Spring Data JPA tutorial will describe how you can create JPA criteria queries with Spring Data JPA.

Spring Data JPA Tutorial Part Two: CRUD

Petri — Tue, 24 Jan 2012 19:48:06 +0000

The first part of my Spring Data JPA tutorial described, how you configure Spring Data JPA. This blog entry goes a bit deeper and describes how you can use Spring Data JPA for creating a simple CRUD application. The requirements of the application are following:

The person must have a first name and last name. Both of these properties are mandatory.
It must be possible to list persons.
It must be possible to add new persons.
It must be possible to edit the information of existing persons.
It must be possible to delete persons.

I have now described the requirements of the created application. Now it is time to get to work and start implementing it.

Required Steps

The implementation of CRUD application can be divided to following steps:

Implementing the Person model object
Creating a repository for the Person object
Using the created repository

Each of these steps is explained with more details in following.

Implementing the Model Object

The implementation of the Person class is pretty simple. However, there are few issues which I would like to point out:

A builder is used to to create new instances of Person class. This might seem like over engineering but I like this approach for two reasons: First, it makes code easier to read than using the telescopic constructor pattern. Second, it ensures that you cannot create an object which in an inconsistent state during its construction (This is something that the common JavaBeans pattern cannot guarantee).
The only way to change the information stored in a Person object is to call the update() method. I am fan of putting as much logic to the model objects as possible. This approach does not clutter the service layer with domain logic and and ensures that you do not end up with an anemic domain model.

The source code of my Person class is given in following:

/**
* An entity class which contains the information of a single person.
* @author Petri Kainulainen
*/
@Entity
@Table(name = "persons")
public class Person {

@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private Long id;

@Column(name = "creation_time", nullable = false)
private Date creationTime;

@Column(name = "first_name", nullable = false)
private String firstName;

@Column(name = "last_name", nullable = false)
private String lastName;

@Column(name = "modification_time", nullable = false)
private Date modificationTime;

@Version
private long version = 0;

public Long getId() {
return id;
}

/**
* Gets a builder which is used to create Person objects.
* @param firstName The first name of the created user.
* @param lastName The last name of the created user.
* @return A new Builder instance.
*/
public static Builder getBuilder(String firstName, String lastName) {
return new Builder(firstName, lastName);
}

public Date getCreationTime() {
return creationTime;
}

public String getFirstName() {
return firstName;
}

public String getLastName() {
return lastName;
}

/**
* Gets the full name of the person.
* @return The full name of the person.
*/
@Transient
public String getName() {
StringBuilder name = new StringBuilder();

name.append(firstName);
name.append(" ");
name.append(lastName);

return name.toString();
}

public Date getModificationTime() {
return modificationTime;
}

public long getVersion() {
return version;
}

public void update(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}

@PreUpdate
public void preUpdate() {
modificationTime = new Date();
}

@PrePersist
public void prePersist() {
Date now = new Date();
creationTime = now;
modificationTime = now;
}

@Override
public String toString() {
return ToStringBuilder.reflectionToString(this);
}

/**
* A Builder class used to create new Person objects.
*/
public static class Builder {
Person built;

/**
* Creates a new Builder instance.
* @param firstName The first name of the created Person object.
* @param lastName The last name of the created Person object.
*/
Builder(String firstName, String lastName) {
built = new Person();
built.firstName = firstName;
built.lastName = lastName;
}

/**
* Builds the new Person object.
* @return The created Person object.
*/
public Person build() {
return built;
}
}

/**
* This setter method should only be used by unit tests.
* @param id
*/
protected void setId(Long id) {
this.id = id;
}
}

Creating the Repository

Implementing a repository which provides CRUD operations for the Person model object is pretty straightforward. All you have to do is to create an interface which extends the JpaRepository interface. The JpaRepository interface is a JPA specific extension to the Repository interface and it gives you the access to following methods which are used to implement the CRUD application:

delete(T entity) which deletes the entity given as a parameter.
findAll() which returns a list of entities.
findOne(ID id) which returns the entity using the id given a parameter as a search criteria.
save(T entity) which saves the entity given as a parameter.

The source code of my PersonRepository interface is given in following:

Using the Created Repository

You have now created both the model object and the repository which is needed to communicate with the database. The next step is to implement a service class which acts as an intermediary between the controllers and the implemented repository. The structure of the service layer is described next.

The PersonDTO is a simple DTO object which is used as a form object in my example application. Its source code is given in following:

/**
* A DTO object which is used as a form object
* in create person and edit person forms.
* @author Petri Kainulainen
*/
public class PersonDTO {

private Long id;

@NotEmpty
private String firstName;

@NotEmpty
private String lastName;

public PersonDTO() {

}

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 String toString() {
return ToStringBuilder.reflectionToString(this);
}
}

The PersonService interface specifies the methods which are provided by the actual implementation. Its source code is given in following:

/**
* Declares methods used to obtain and modify person information.
* @author Petri Kainulainen
*/
public interface PersonService {

/**
* Creates a new person.
* @param created The information of the created person.
* @return The created person.
*/
public Person create(PersonDTO created);

/**
* Deletes a person.
* @param personId The id of the deleted person.
* @return The deleted person.
* @throws PersonNotFoundException if no person is found with the given id.
*/
public Person delete(Long personId) throws PersonNotFoundException;

/**
* Finds all persons.
* @return A list of persons.
*/
public List<Person> findAll();

/**
* Finds person by id.
* @param id The id of the wanted person.
* @return The found person. If no person is found, this method returns null.
*/
public Person findById(Long id);

/**
* Updates the information of a person.
* @param updated The information of the updated person.
* @return The updated person.
* @throws PersonNotFoundException if no person is found with given id.
*/
public Person update(PersonDTO updated) throws PersonNotFoundException;
}

The source code of the RepositoryPersonService class which implements the PersonService interface is given in following:

/**
* This implementation of the PersonService interface communicates with
* the database by using a Spring Data JPA repository.
* @author Petri Kainulainen
*/
@Service
public class RepositoryPersonService implements PersonService {

private static final Logger LOGGER = LoggerFactory.getLogger(RepositoryPersonService.class);

@Resource
private PersonRepository personRepository;

@Transactional
@Override
public Person create(PersonDTO created) {
LOGGER.debug("Creating a new person with information: " + created);

Person person = Person.getBuilder(created.getFirstName(), created.getLastName()).build();

return personRepository.save(person);
}

@Transactional(rollbackFor = PersonNotFoundException.class)
@Override
public Person delete(Long personId) throws PersonNotFoundException {
LOGGER.debug("Deleting person with id: " + personId);

Person deleted = personRepository.findOne(personId);

if (deleted == null) {
LOGGER.debug("No person found with id: " + personId);
throw new PersonNotFoundException();
}

personRepository.delete(deleted);
return deleted;
}

@Transactional(readOnly = true)
@Override
public List<Person> findAll() {
LOGGER.debug("Finding all persons");
return personRepository.findAll();
}

@Transactional(readOnly = true)
@Override
public Person findById(Long id) {
LOGGER.debug("Finding person by id: " + id);
return personRepository.findOne(id);
}

@Transactional(rollbackFor = PersonNotFoundException.class)
@Override
public Person update(PersonDTO updated) throws PersonNotFoundException {
LOGGER.debug("Updating person with information: " + updated);

Person person = personRepository.findOne(updated.getId());

if (person == null) {
LOGGER.debug("No person found with id: " + updated.getId());
throw new PersonNotFoundException();
}

person.update(updated.getFirstName(), updated.getLastName());

return person;
}

/**
* This setter method should be used only by unit tests.
* @param personRepository
*/
protected void setPersonRepository(PersonRepository personRepository) {
this.personRepository = personRepository;
}
}

What is Next?

I have now demonstrated to you how you can implement a simple CRUD application with Spring Data JPA. If you are interested of seeing my fully functional example in action, you can get it from Github. The third part of my Spring Data JPA tutorial describes how you can create custom queries with query methods.

Spring Data JPA Tutorial Part One: Configuration

Petri — Sat, 21 Jan 2012 10:19:05 +0000

Spring Data JPA is a project which aims both to simplify the creation of JPA based repositories and to reduce the amount of code needed to communicate with a database. I have been using it for a while at my work and in my personal hobby projects and it has indeed make things a lot more simpler and cleaner. Now it is time to share my knowledge with you.

This is the first part of my Spring Data JPA tutorial and it will describe to you, how you can configure Spring Data JPA when you are using Hibernate as your JPA provider. Before we will get started, I want to make one thing straight: This tutorial is not an introductory level tutorial to Hibernate, JPA or Spring. You must have some experience about these technologies if you want to understand the concepts described in my Spring Data JPA tutorial.

The dependencies of this tutorial are following:

BoneCP 0.7.1.RELEASE (You can use other data source implementations as well)
Hibernate 4.0.1.Final
Spring Framework 3.1.0.RELEASE
Spring Data JPA 1.0.2
Servlet API 3.0

Also, since I am using Maven as a build tool, you must install it if you want to run my example application.

Getting Started

It is time to get started. You can configure the Spring Data JPA by following these steps:

You have to obtain the needed dependencies.
You must configure the needed beans in your Spring application context configuration. The beans needed by the Spring Data JPA are: data source, transaction manager and entity manager factory.
You have to configure the Spring Data JPA.

These steps are explained with more details in following:

Obtaining the Needed Depedencies

First, you need to obtain the needed dependencies. You can do this by configuring the needed dependencies in your pom.xml file. The pom.xml of my example looks following:

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/maven-v4_0_0.xsd">
>4.0.0>
>net.petrikainulainen.spring>
>data-jpa-tutorial-part-one>
>war>
>0.1>
>Spring Data JPA Tutorial Part One>
>Spring Data JPA Tutorial Part One>
>
>
>Apache License 2.0>
>http://www.apache.org/licenses/LICENSE-2.0>
>
>
>http://www.petrikainulainen.net>
>
>
>repository.jboss.org-public>
>JBoss repository>
>https://repository.jboss.org/nexus/content/groups/public>
>
>
>
>4.0.1.Final>
>5.1.18>
>1.6.1>
>3.1.0.RELEASE>
>UTF-8>
>
>

>
>org.springframework>
>spring-beans>
>${spring.version}>
>
>
>org.springframework>
>spring-core>
>${spring.version}>
>
>
>org.springframework>
>spring-context-support>
>${spring.version}>
>
>
>org.springframework>
>spring-context>
>${spring.version}>
>
>
>org.springframework>
>spring-jdbc>
>${spring.version}>
>
>
>org.springframework>
>spring-orm>
>${spring.version}>
>
>
>org.springframework>
>spring-tx>
>${spring.version}>
>

>
>org.springframework>
>spring-web>
>${spring.version}>
>
>
>org.springframework>
>spring-webmvc>
>${spring.version}>
>
>
>cglib>
>cglib>
>2.2.2>
>

>
>org.springframework.data>
>spring-data-jpa>
>1.0.2.RELEASE>
>

>
>org.hibernate>
>hibernate-core>
>${hibernate.version}>
>
>
>org.hibernate>
>hibernate-entitymanager>
>${hibernate.version}>
>

>
>com.h2database>
>h2>
>1.3.160>
>

>
>com.jolbox>
>bonecp>
>0.7.1.RELEASE>
>

>
>javax.servlet>
>javax.servlet-api>
>3.0.1>
>provided>
>
>
>javax.servlet>
>jstl>
>1.2>
>

>
>org.slf4j>
>slf4j-api>
>${slf4j.version}>
>
>
>org.slf4j>
>slf4j-log4j12>
>${slf4j.version}>
>
>
>log4j>
>log4j>
>1.2.16>
>

>
>junit>
>junit>
>4.9>
>test>
>
>
>
>data-jpa-tutorial-part-one>
>
>
>org.apache.maven.plugins>
>maven-compiler-plugin>
>2.3.2>
>
>1.6>
>1.6>
>
>
>
>org.apache.maven.plugins>
>maven-war-plugin>
>2.1.1>
>
>false>
>
>
>
>org.mortbay.jetty>
>jetty-maven-plugin>
>8.1.0.RC2>
>
>0>
>
>src/main/resources/webdefault.xml>
>
>
>
>
>org.apache.maven.plugins>
>maven-site-plugin>
>3.0>
>
>

>
>org.codehaus.mojo>
>cobertura-maven-plugin>
>2.5.1>
>
>
>
>
>
>
>

Configuring the Spring Application Context

Second, you must configure the Spring application context. As you might remember, you need to configure the data source, transaction manager and entity manager factory beans. If you are using Spring 3.1 and Servlet 3.0, you can do this by implementing a Java configuration class and loading that configuration class in your web application initializer. The content of my application context configuration class is given in following:

/**
* An application context Java configuration class. The usage of Java configuration
* requires Spring Framework 3.0 or higher with following exceptions:
*

@EnableWebMvc annotation requires Spring Framework 3.1

* @author Petri Kainulainen
*/
@Configuration
@ComponentScan(basePackages = {"net.petrikainulainen.spring.datajpa.controller"})
@EnableWebMvc
@ImportResource("classpath:applicationContext.xml")
@PropertySource("classpath:application.properties")
public class ApplicationContext {

private static final String VIEW_RESOLVER_PREFIX = "/WEB-INF/jsp/";
private static final String VIEW_RESOLVER_SUFFIX = ".jsp";

private static final String PROPERTY_NAME_DATABASE_DRIVER = "db.driver";
private static final String PROPERTY_NAME_DATABASE_PASSWORD = "db.password";
private static final String PROPERTY_NAME_DATABASE_URL = "db.url";
private static final String PROPERTY_NAME_DATABASE_USERNAME = "db.username";

private static final String PROPERTY_NAME_HIBERNATE_DIALECT = "hibernate.dialect";
private static final String PROPERTY_NAME_HIBERNATE_FORMAT_SQL = "hibernate.format_sql";
private static final String PROPERTY_NAME_HIBERNATE_NAMING_STRATEGY = "hibernate.ejb.naming_strategy";
private static final String PROPERTY_NAME_HIBERNATE_SHOW_SQL = "hibernate.show_sql";
private static final String PROPERTY_NAME_ENTITYMANAGER_PACKAGES_TO_SCAN = "entitymanager.packages.to.scan";

private static final String PROPERTY_NAME_MESSAGESOURCE_BASENAME = "message.source.basename";
private static final String PROPERTY_NAME_MESSAGESOURCE_USE_CODE_AS_DEFAULT_MESSAGE = "message.source.use.code.as.default.message";

@Resource
private Environment environment;

@Bean
public DataSource dataSource() {
BoneCPDataSource dataSource = new BoneCPDataSource();

dataSource.setDriverClass(environment.getRequiredProperty(PROPERTY_NAME_DATABASE_DRIVER));
dataSource.setJdbcUrl(environment.getRequiredProperty(PROPERTY_NAME_DATABASE_URL));
dataSource.setUsername(environment.getRequiredProperty(PROPERTY_NAME_DATABASE_USERNAME));
dataSource.setPassword(environment.getRequiredProperty(PROPERTY_NAME_DATABASE_PASSWORD));

return dataSource;
}

@Bean
public JpaTransactionManager transactionManager() throws ClassNotFoundException {
JpaTransactionManager transactionManager = new JpaTransactionManager();

transactionManager.setEntityManagerFactory(entityManagerFactoryBean().getObject());

return transactionManager;
}

@Bean
public LocalContainerEntityManagerFactoryBean entityManagerFactoryBean() throws ClassNotFoundException {
LocalContainerEntityManagerFactoryBean entityManagerFactoryBean = new LocalContainerEntityManagerFactoryBean();

entityManagerFactoryBean.setDataSource(dataSource());
entityManagerFactoryBean.setPackagesToScan(environment.getRequiredProperty(PROPERTY_NAME_ENTITYMANAGER_PACKAGES_TO_SCAN));
entityManagerFactoryBean.setPersistenceProviderClass(HibernatePersistence.class);

Properties jpaProterties = new Properties();
jpaProterties.put(PROPERTY_NAME_HIBERNATE_DIALECT, environment.getRequiredProperty(PROPERTY_NAME_HIBERNATE_DIALECT));
jpaProterties.put(PROPERTY_NAME_HIBERNATE_FORMAT_SQL, environment.getRequiredProperty(PROPERTY_NAME_HIBERNATE_FORMAT_SQL));
jpaProterties.put(PROPERTY_NAME_HIBERNATE_NAMING_STRATEGY, environment.getRequiredProperty(PROPERTY_NAME_HIBERNATE_NAMING_STRATEGY));
jpaProterties.put(PROPERTY_NAME_HIBERNATE_SHOW_SQL, environment.getRequiredProperty(PROPERTY_NAME_HIBERNATE_SHOW_SQL));

entityManagerFactoryBean.setJpaProperties(jpaProterties);

return entityManagerFactoryBean;
}

@Bean
public MessageSource messageSource() {
ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();

messageSource.setBasename(environment.getRequiredProperty(PROPERTY_NAME_MESSAGESOURCE_BASENAME));
messageSource.setUseCodeAsDefaultMessage(Boolean.parseBoolean(environment.getRequiredProperty(PROPERTY_NAME_MESSAGESOURCE_USE_CODE_AS_DEFAULT_MESSAGE)));

return messageSource;
}

@Bean
public ViewResolver viewResolver() {
InternalResourceViewResolver viewResolver = new InternalResourceViewResolver();

viewResolver.setViewClass(JstlView.class);
viewResolver.setPrefix(VIEW_RESOLVER_PREFIX);
viewResolver.setSuffix(VIEW_RESOLVER_SUFFIX);

return viewResolver;
}
}

My web application initializer looks like this:

/**
* Web application Java configuration class. The usage of web application
* initializer requires Spring Framework 3.1 and Servlet 3.0.
* @author Petri Kainulainen
*/
public class DataJPAExampleInitializer implements WebApplicationInitializer {

private static final String DISPATCHER_SERVLET_NAME = "dispatcher";
private static final String DISPATCHER_SERVLET_MAPPING = "/";

@Override
public void onStartup(ServletContext servletContext) throws ServletException {
AnnotationConfigWebApplicationContext rootContext = new AnnotationConfigWebApplicationContext();
rootContext.register(ApplicationContext.class);

ServletRegistration.Dynamic dispatcher = servletContext.addServlet(DISPATCHER_SERVLET_NAME, new DispatcherServlet(rootContext));
dispatcher.setLoadOnStartup(1);
dispatcher.addMapping(DISPATCHER_SERVLET_MAPPING);

servletContext.addListener(new ContextLoaderListener(rootContext));
}
}

You might have noticed that I used the @PropertySource annotation to specify the location of a properties file which contains the values of used configuration parameters. The content of my application.properties file is following:

# The default database is H2 memory database but I have also
# added configuration needed to use either MySQL and PostgreSQL.

#Database Configuration
db.driver=org.h2.Driver
#db.driver=com.mysql.jdbc.Driver
#db.driver=org.postgresql.Driver
db.url=jdbc:h2:mem:datajpa
#db.url=jdbc:mysql://localhost:3306/datajpa
#db.url=jdbc:postgresql://localhost/datajpa
db.username=sa
db.password=

#Hibernate Configuration
hibernate.dialect=org.hibernate.dialect.H2Dialect
#hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
#hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
hibernate.format_sql=true
hibernate.ejb.naming_strategy=org.hibernate.cfg.ImprovedNamingStrategy
hibernate.show_sql=true

#MessageSource
message.source.basename=i18n/messages
message.source.use.code.as.default.message=true

#EntityManager
#Declares the base package of the entity classes
entitymanager.packages.to.scan=net.petrikainulainen.spring.datajpa.model

Configuring Spring Data JPA

Third, you must configure the Spring Data JPA. If you were paying attention, you might have noticed that I used the @ImportResource annotation in my application context configuration class to import additional configuration from a XML configuration file. At the moment Spring Data JPA does not support Java configuration. Thus, the only way to configure it is to use a XML configuration file. My applicationContext.xml file looks following:

version="1.0" encoding="UTF-8"?>
xmlns="http://www.springframework.org/schema/beans"
xmlns:jpa="http://www.springframework.org/schema/data/jpa"
xmlns:mvc="http://www.springframework.org/schema/mvc"
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-3.1.xsd
http://www.springframework.org/schema/data/jpa
http://www.springframework.org/schema/data/jpa/spring-jpa-1.0.xsd
http://www.springframework.org/schema/mvc
http://www.springframework.org/schema/mvc/spring-mvc-3.1.xsd">

mapping="/static/**" location="/static/"/>

base-package="net.petrikainulainen.spring.datajpa.repository"/>
>

You Are Done

That is it. I have now demonstrated to you how you can configure the Spring Data JPA. I also have created an example application to demonstrate that this configuration is actually working. You can test the configuration yourself by getting my example application from Github and running the example web application by using the Maven Jetty plugin (Note: Remember to create the model and repository packages first. Since it is not possible to add empty directories to the Git staging area, the Github repository does not have them either).

The second part of my Spring Data JPA tutorial describes how you can create a simple CRUD web application by using Spring Data JPA. Stay tuned.

There Are No Small Projects

Petri — Sun, 15 Jan 2012 18:52:52 +0000

How often have your heard one of the following phrases:

This is a small project so we will just have to put something together and FAST.

Big projects need to be designed in a totally different manner than small ones.

This is just a campaign product / prototype which is used only once. We can write tests later if the scope of the project is increased.

These phrases and many others like them suggest that big software projects require different approach than small ones. Even though this is partially true, each one of those phrases contains a hidden agenda:

First, they propose that small projects should be put together as fast as possible. Second, they propose that good software development practices such as unit testing, integration testing and code reviews are not as important in a small project than they are in a big one.

I have noticed that this attitude is surprisingly common but that does not make it right. I personally believe that this approach is flawed for the following reasons:

Not all projects start as big ones. In these cases the scope of the project is extended during the project. If you have separate practices for small and big projects, you will end up noticing that you have been following the wrong practices. This can be a critical mistake since you might have to go back to the code you have written earlier and adapt it to match the demands of the big projects This costs both time and money and your customer is often not willing to pay for it. And guess what? The customer is absolutely right. You made the mistake. You will have to pay the prize.

Small projects are important to your customer. It does not really matter whether the project is described to you as a temporary or as a permanent solution. The fact is that you cannot know if something you delivered is going to be a part of something bigger in the future. The only ethical thing to do is to ensure that you finish all projects by following good software development practices. This way it should be easier to extend the software you delivered if needed.

Remember that even if the project does not sound big and important project to you, it might be a huge investment to your customer and it should be treated as such. If you can ship the finished product with your name and contact details, you have most likely given the customer the respect he deserves.

Changing peoples attitude is hard. If your developers have learned that it is acceptable to cut corners in small projects, you are going to have a hard time to change their attitude when you finally get that big project you have been dying to get. The reason why this is hard is that you will have force your developers out of their comfort zones and people tend to resist changes like this. That is why the best thing you can do for your business is to follow good software development practices in every project. It will save both your nerves and your money.

Keeping your expectations high has also got a one additional benefit: It will make the recruitment process much easier for you. As long as you mention your high expectations during job interviews, it will be fairly easy to see who is not a good addition to your team.

I have now given you three reasons why you should treat each project in the same way. Remember that it is perfectly fine to decline projects which seem too small for you. However, if you decide take a project (either big or small), you should always follow the same principles and aim for delivering software which you can be proud of. If you are a real professional, anything less than this is simply unacceptable.

Creating RESTful Urls with Spring MVC 3.1 Part Three: UrlRewriteFilter

Petri — Mon, 09 Jan 2012 19:45:39 +0000

This blog entry describes how you can create RESTful url addresses to your web application with Spring MVC 3.1 and UrlRewriteFilter. In other words, the url addresses of your application must fulfill following requirements:

An url address must have a suffix in it (in other words, an url address most not contain a suffix like ‘.action’).
The context path of the web application which is visible to the users of the application must not start with a prefix like ‘app’.

Next I am going to describe the steps which are needed to fulfill these requirements with Spring MVC 3.1 and UrlRewriteFilter.

The first step is to configure the dispatcher servlet and UrlRewriteFilter. This step consist of two phases:

Map the dispatcher servlet to url pattern ‘/app/*’ and the UrlRewriteFilter to url pattern ‘/*’.
Configure the UrlRewriteFilter to hide the url pattern of dispatcher servlet.

First, you have to configure you web application. If you are using Spring 3.1 and Servlet 3.0, you can do this by implementing the WebApplicationInitializer interface. Otherwise you will have to create a web.xml configuration file which contains the same configuration (This is left as an exercise for the reader). The source code of my web application configuration class is given in following:

public class RestfulInitializer implements WebApplicationInitializer {

private static final String DISPATCHER_SERVLET_NAME = "dispatcher";
private static final String DISPATCHER_SERVLET_MAPPING = "/app/*";

private static final String URL_REWRITE_FILTER_NAME = "urlRewrite";
private static final String URL_REWRITE_FILTER_MAPPING = "/*";
private static final String URL_REWRITE_FILTER_PARAM_LOGLEVEL = "logLevel";
private static final String URL_REWRITE_FILTER_LOGLEVEL_SLF4J = "slf4j";

@Override
public void onStartup(ServletContext servletContext) throws ServletException {
AnnotationConfigWebApplicationContext rootContext = new AnnotationConfigWebApplicationContext();
rootContext.register(ApplicationContext.class);

ServletRegistration.Dynamic dispatcher = servletContext.addServlet(DISPATCHER_SERVLET_NAME, new DispatcherServlet(rootContext));
dispatcher.setLoadOnStartup(1);
dispatcher.addMapping(DISPATCHER_SERVLET_MAPPING);

servletContext.addListener(new ContextLoaderListener(rootContext));

FilterRegistration.Dynamic urlReWrite = servletContext.addFilter(URL_REWRITE_FILTER_NAME, new UrlRewriteFilter());
urlReWrite.setInitParameter(URL_REWRITE_FILTER_PARAM_LOGLEVEL, URL_REWRITE_FILTER_LOGLEVEL_SLF4J);
EnumSet<DispatcherType> urlReWriteDispatcherTypes = EnumSet.of(DispatcherType.REQUEST, DispatcherType.FORWARD);
urlReWrite.addMappingForUrlPatterns(urlReWriteDispatcherTypes, true, URL_REWRITE_FILTER_MAPPING);
}
}

Second, you must configure the UrlRewriteFilter properly. The web application root of my example application has following directory structure:

Static resources such as css files are located under static folder.
JSP files are located under WEB-INF/jsp folder.

The UrlRewriteFilter can be configured by creating a configuration file called urlrewrite.xml to WEB-INF folder. The contents of this file is given in following:

default-match-type="wildcard">

>
>/>
last="true">/app/home>
>

match-type="regexp">

type="request-uri" operator="notequal">^/(static|app|WEB-INF)/.*>
>^/(.*)>
last="true">/app/$1>
>

>/app/**>
>/$1>
>
>

The second step is to implement your web application. You must follow these two principles during the implementation phase:

Add the correct request mappings to controller classes. Remember that you must not add the ‘/app/’ prefix to the value attribute of your @RequestMapping annotation.
Use the url tag of JSTL or Spring tab library in the JSP pages (or simply leave the ‘/app/’ prefix out from the href attribute of the html link tag).

I will use the source code of my example application to provide an example which should clarify the principles given above. The class called HomeController is responsible of processing the requests made to the home page of my example application. The source code of this class is given in following:

@Controller
public class HomeController {

protected static final String HOME_VIEW = "home";

@RequestMapping(value = "/home", method = RequestMethod.GET)
public String showPage() {
return HOME_VIEW;
}
}

The home view is called home.jsp and its source code is given in following:

<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jstl/core" %>
<html>
<head>
<title>Spring MVC Restful Url Example Application - Home</title>
<link rel="stylesheet" type="text/css" href="/static/css/styles.css"/>
</head>
<body>
<h1>Home</h1>
<p>

value="/app/page" var="pageUrl"/>
<a href="${pageUrl}">Move to an another page</a>.
</p>
</body>
</html>

I have now described to you how can create RESTful urls with Spring MVC 3.1 And UrlRewriteFilter. This approach feels a bit hacky but I am using it in one of my projects because I have not been able to solve the problem with the default servlet name and Jetty 8.1.0.RC0. Also, if you want to implement RESTful urls by using older Spring MVC versions, this is your best option (It should be fairly easy to create the needed configuration files based on this example).

PS. You can get the soure code of my example application from Github.

Creating RESTful Urls with Spring MVC 3.1 Part Two: Dispatcher Servlet Url Mappings

Petri — Sat, 17 Dec 2011 22:06:50 +0000

The first part of this series described how you can create RESTful urls with Spring MVC 3.1 and default-servlet-handler element of the MVC namespace. This blog entry will describe how you can use the dispatcher servlet url mappings for the same purpose. As you might remember from my previous blog entry, a RESTful url must fulfill these requirements:

An url address must no have suffix in it (in other words, an url address most not contain a suffix like ‘.action’).
The context path of the web application must not start with a prefix like ‘app’.

As I mentioned to you before, you can use the dispatcher servlet url mappings for configuring your web application to use RESTful url addresses. This means that you must create section specific context path prefixes and map the dispatcher servlet to these url patterns. This idea might seem a bit confusing at first so I will provide an example which will hopefully explain this idea.

Lets assume that your web page has two sections: products and services. This would mean that you would map your dispatcher servlet to following url patterns: ‘/products/*’ and ‘/services/*’. This approach works rather well if the next part of the context path does not contain a path variable. Lets take a closer look of this in following:

Following context paths would not work: ‘/products/1′ and ‘/services/5′.
Following context paths would work: ‘/products/phones/1′ and ‘/services/training/1′.

The reason for this behavior is that the dispatcher servlet removes the url pattern from the beginning of the request’s context path and tries to look for a handler to the request by using the resulting string. (E.g. If you have mapped your dispatcher servlet to url pattern ‘/products/*’ and the context path of the incoming request is ‘/products/phones/1′, the dispatcher servlet is looking for a handler which request mapping matches with the string ‘/phones/1′). This naturally means that context paths like ‘/products/1′ and ‘/services/1′ will not work because the resulting request mapping is not “unique”.

Enough with the theory. The steps needed to create RESTful url addresses by using this technique are described next.

First, you must configure your application context. I have a created a simple Java configuration class which is used to enable Spring MVC, set the component scan base package and configure the view resolver bean. The source code of the configuration class is given in following:

/**
* An application context Java configuration class. The usage of Java configuration
* requires Spring Framework 3.0 or higher.
* @author Petri Kainulainen
*/
@Configuration
@ComponentScan(basePackages = {"net.petrikainulainen.spring.restful.controller"})
@EnableWebMvc
public class ApplicationContext {

private static final String VIEW_RESOLVER_PREFIX = "/WEB-INF/jsp/";
private static final String VIEW_RESOLVER_SUFFIX = ".jsp";

@Bean
public ViewResolver viewResolver() {
InternalResourceViewResolver viewResolver = new InternalResourceViewResolver();

viewResolver.setViewClass(JstlView.class);
viewResolver.setPrefix(VIEW_RESOLVER_PREFIX);
viewResolver.setSuffix(VIEW_RESOLVER_SUFFIX);

return viewResolver;
}
}

Second, you must configure your web application. In this case the web application configuration consists of two phases:

Configure the url mapping of the dispatcher servlet.
Configure the welcome file of your application.

I decided to configure my web application by implementing the WebApplicationInitializer interface. My example adds dispatcher servlet url mappings for the home page, products section and services section of the web application. The source code of my implementation is given in following:

/**
* Web application Java configuration class. The usage of web application
* initializer requires Spring Framework 3.1 and Servlet 3.0.
* @author Petri Kainulainen
*/
public class RestfulInitializer implements WebApplicationInitializer {

private static final String DISPATCHER_SERVLET_NAME = "dispatcher";
private static final String DISPATCHER_SERVLET_MAPPING_HOME = "/home";
private static final String DISPATCHER_SERVLET_MAPPING_PRODUCTS = "/products/*";
private static final String DISPATCHER_SERVLET_MAPPING_SERVICES = "/services/*";

@Override
public void onStartup(ServletContext servletContext) throws ServletException {
AnnotationConfigWebApplicationContext rootContext = new AnnotationConfigWebApplicationContext();
rootContext.register(ApplicationContext.class);

ServletRegistration.Dynamic dispatcher = servletContext.addServlet(DISPATCHER_SERVLET_NAME, new DispatcherServlet(rootContext));
dispatcher.setLoadOnStartup(1);
dispatcher.addMapping(DISPATCHER_SERVLET_MAPPING_HOME);
dispatcher.addMapping(DISPATCHER_SERVLET_MAPPING_PRODUCTS);
dispatcher.addMapping(DISPATCHER_SERVLET_MAPPING_SERVICES);

servletContext.addListener(new ContextLoaderListener(rootContext));
}
}

Since it is not yet possible to configure the welcome page of a web application by using Java configuration, I had to create a web.xml configuration file and configure the welcome file of my application in it. My web.xml file looks as follows:

xmlns="http://java.sun.com/xml/ns/javaee"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">

index.html>
>
>

Third, you must create a index page which redirects user to your home page. In my example, the url mapping of the home page is ‘/home’. I used the Meta Refresh Tag for this purpose. The source code of my welcome file is given in following:

"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta HTTP-EQUIV="REFRESH" content="0; url=/home">
<title></title>
</head>
<body>
</body>
</html>

I have now described to you how you can use the dispatcher servlet url mappings for creating RESTful url addresses with Spring MVC. I am having some doubts about this approach for three reasons:

If new sections are added to your web application, you must always remember to add the correct mapping for the dispatcher servlet. This feels a bit cumbersome.
The actual url address of your home page is not invisible for the users of your application. I prefer url addresses like http://www.example.com over http://www.example.com/home. This might sound ridiculous but in some situations this is not acceptable.
The context path of your application must have more than one “level” because otherwise Spring cannot find the correct handler for the requests. This might not a problem in most cases but if it is, you cannot use the approach described in this blog entry.

If you are interested of playing around with my example application, you can get the source code from GitHub. The third and last part of this series will describe how you can create RESTful urls with Spring MVC and UrlrewriteFiter. Stay tuned.

Creating RESTful Urls with Spring MVC 3.1 Part One: default-servlet-handler

Petri — Fri, 16 Dec 2011 20:27:31 +0000

This blog entry describes how you can create a web application which has restful url addresses by using Spring MVC 3.1 and the default-servlet-handler element of MVC XML namespace. The requirements for RESTful urls are given in following:

An url address must no have suffix in it (in other words, an url address most not contain a suffix like ‘.action’).
The context path of the web application must not start with a prefix like ‘app’.

I have figured out three alternative solutions to this problem and first of them is described in following:

First, you have to configure the application context of your application. This step consists of three smaller steps:

Configure the location of static resources such as css files.
Ensure that static resources are served by the container’s default servlet
Create an application context configuration class.

The first two steps can be implemented by creating an application context configuration file which content is given in following (NOTE: As Rossen pointed out, you can use Java configuration as well. See his comment for more details):

version="1.0" encoding="UTF-8"?>
xmlns="http://www.springframework.org/schema/beans"
xmlns:mvc="http://www.springframework.org/schema/mvc"
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-3.1.xsd
http://www.springframework.org/schema/mvc
http://www.springframework.org/schema/mvc/spring-mvc-3.1.xsd">

mapping="/static/**" location="/static/"/>

The third step of the application context configuration can be implemented by using a simple Java configuration class which enables the Spring MVC support, imports the application context configuration file, sets the component scan base package and configures a view resolver bean. The source code of this configuration class is given in following:

/**
* An application context Java configuration class. The usage of Java configuration
* requires Spring Framework 3.0 or higher with following exceptions:
*

@EnableWebMvc annotation requires Spring Framework 3.1

* @author Petri Kainulainen
*/
@Configuration
@ComponentScan(basePackages = {"net.petrikainulainen.spring.restful.controller"})
@EnableWebMvc
@ImportResource("classpath:applicationContext.xml")
public class ApplicationContext {

private static final String VIEW_RESOLVER_PREFIX = "/WEB-INF/jsp/";
private static final String VIEW_RESOLVER_SUFFIX = ".jsp";

@Bean
public ViewResolver viewResolver() {
InternalResourceViewResolver viewResolver = new InternalResourceViewResolver();

viewResolver.setViewClass(JstlView.class);
viewResolver.setPrefix(VIEW_RESOLVER_PREFIX);
viewResolver.setSuffix(VIEW_RESOLVER_SUFFIX);

return viewResolver;
}
}

Second, you must configure your web application and map the dispatcher servlet to url pattern ‘/’. This example configures the web application by using Java configuration which was introduced by the Servlet 3.0 API. However, it should be fairly easy to create a web.xml configuration file based on this example if you cannot use Spring Framework 3.1 and Servlet 3.0. Configuring a web application by using Java is easy. All you have to do is to implement the WebApplicationInitializer interface. My implementation of that interface is described in following:

/**
* Web application Java configuration class. The usage of web application
* initializer requires Spring Framework 3.1 and Servlet 3.0.
* @author Petri Kainulainen
*/
public class RestfulInitializer implements WebApplicationInitializer {

private static final String DISPATCHER_SERVLET_NAME = "dispatcher";
private static final String DISPATCHER_SERVLET_MAPPING = "/";

@Override
public void onStartup(ServletContext servletContext) throws ServletException {
AnnotationConfigWebApplicationContext rootContext = new AnnotationConfigWebApplicationContext();
rootContext.register(ApplicationContext.class);

ServletRegistration.Dynamic dispatcher = servletContext.addServlet(DISPATCHER_SERVLET_NAME, new DispatcherServlet(rootContext));
dispatcher.setLoadOnStartup(1);
dispatcher.addMapping(DISPATCHER_SERVLET_MAPPING);

servletContext.addListener(new ContextLoaderListener(rootContext));
}
}

I have now described to you how you can configure your web application to use RESTful url addresses. This solution seems pretty clean but for some reason I was unable to get it to work with Jetty 8.1.0.RC0. This seems pretty weird to me because the mvc:default-servlet-handler Subsection of Spring Framework 3.1 reference documentation states that:

The caveat to overriding the “/” Servlet mapping is that the RequestDispatcher for the default Servlet must be retrieved by name rather than by path. The DefaultServletHttpRequestHandler will attempt to auto-detect the default Servlet for the container at startup time, using a list of known names for most of the major Servlet containers (including Tomcat, Jetty, Glassfish, JBoss, Resin, WebLogic, and WebSphere).

Since I was able to run my example application without any problems with Tomcat 7.0.23, I am wondering if the problem is somehow related to my configuration. At the moment I am suspecting that the problem is related to the default servlet name of Jetty 8.1.0.RC0 because the Spring Framework’s reference documentation also states that:

If the default Servlet has been custom configured with a different name, or if a different Servlet container is being used where the default Servlet name is unknown, then the default Servlet’s name must be explicitly provided

I decided to publish blog entry anyway because I feel that this might be valuable to someone. I had also a selfish motive since I love to use Jetty during development phase and I am hoping that someone can help to find a solution to my problem. I am going to offer you one in the next part of this series but I am not totally satisfied with it. It just does not feel right.

P.S. I have also created an example application which you can use to test the advice given in this blog entry. The source of this application is available at GitHub. If you have any advice concerning the problem I am having with Jetty 8.1.0.RC0, I be would interested to hear it out.

Implementing a Custom Naming Strategy With Hibernate

Petri — Fri, 02 Dec 2011 20:34:41 +0000

As all of you who are familiar with Hibernate know, not all entity annotations are mandatory. These non mandatory annotations include @Table and @Column annotations. However, even though these annotations are not required, leaving them out has never been an option for me. I simply don’t like the table and column names which are generated by Hibernate unless they are explicitly set.

The naming convention of database objects and schema elements is controlled by the used implementation of the org.hibernate.cfg.NamingStrategy interface. Hibernate 3.6 has four implementations of this interface:

However, none of these implementations fulfill my requirements which are:

All characters must be lowercase.
Table names must be in plural form.
Words must be separated by using an underscore.

Since the ImprovedNamingStrategy class is almost what I am looking for (its only fault is that it returns the table name in a singular form), I decided to create a custom naming strategy by extending it and overriding its classToTableName() method. The source code of my implementation is given in following:

package net.petrikainulainen.hibernate.util;
import org.hibernate.cfg.ImprovedNamingStrategy;

/**
* A custom naming strategy implementation which uses following naming conventions:
*

Table names are lower case and in plural form. Words are separated with '_' character.

Column names are lower case and words are separated with '_' character.

* @author Petri Kainulainen
*/
public class CustomNamingStrategy extends ImprovedNamingStrategy {

private static final String PLURAL_SUFFIX = "s";

/**
* Transforms class names to table names by using the described naming conventions.
* @param className
* @return The constructed table name.
*/
@Override
public String classToTableName(String className) {
String tableNameInSingularForm = super.classToTableName(className);
return transformToPluralForm(tableNameInSingularForm);
}

private String transformToPluralForm(String tableNameInSingularForm) {
StringBuilder pluralForm = new StringBuilder();

pluralForm.append(tableNameInSingularForm);
pluralForm.append(PLURAL_SUFFIX);

return pluralForm.toString();
}
}

The next step is to configure the Hibernate to use my custom naming strategy. If you are using Hibernate, you can either

You can set a reference to the custom naming strategy by calling the setNamingStrategy() method of the Configuration class as described in the Implementing a Naming Strategy Section of the Hibernate Reference Documentation.
You can set the value of hibernate.ejb.naming_strategy property to net.petrikainulainen.hibernate.util.CustomNamingStrategy in the Hibernate XML configuration file as described in the XML Configuration Section of the Hibernate Reference Manual.

If you are using JPA, you can set the used naming strategy by setting the value of hibernate.ejb.naming_strategy property to net.petrikainulainen.hibernate.util.CustomNamingStrategy in the persistence.xml as described the Packaging Section of the Hibernate EntityManager reference manual.

After you have configured Hibernate to use the implemented custom naming strategy, you can remove the @Table and @Column annotations from entity classes (This is not entirely true but I will describe the shortcomings of my solution later). For example, if you have an entity class Person, its source code could look something like this:

@Entity
@Table("persons")
public class Person {

@Column(name="first_name")
private String firstName;

@Column(name="last_name")
private String lastName;

public Person() {

}
}

After Hibernate is using the new naming strategy, the source code of the Person entity would look like this (but Hibernate would still use the same table and column names which were explicitly specified in the previous example):

@Entity
public class Person {

private String firstName;

private String lastName;

public Person() {

}
}

I have now described to you how you can implement and configure a custom naming strategy with Hibernate. However, the solution described in this blog entry is far from perfect. It has following shortcomings:

It does not always produce grammatically correct table names. For example: The plural form is a word entity is not entitys. It is entities. This problem is pretty hard to tackle automatically but remember that you can always use the @Table annotation to solve these cases.
If you want to add restrictions to the column in the entity class, you still have to add the @Column annotation. This is not a problem to me because I always generate the database creation scripts manually and add constraints to the database. However, if you want to generate your database by using Hibernate, you would have to specify the constraints by using the @Column annotation or add the needed constraints manually to the created database.
You still have to configure the relationships between entities by using annotations. Creating an automatic solution for this problem would mean that I would have to invent some kind of naming convention for the names of join tables and columns. This is something which I am not willing to do. However, If you have an another solution in mind, let me know!

Why You Should Keep Your Build Green

Petri — Thu, 29 Sep 2011 18:43:09 +0000

Continuous integration has established its place among the good software development practices. However, setting up a continuous integration server and configuring it to run your tests automatically does not mean that you are really doing continuous integration. It only means that you have installed a continuous integration server and it run your tests automatically. Martin Fowler defines continuous integration as follows:

Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily – leading to multiple integrations per day. Each integration is verified by an automated build (including test) to detect integration errors as quickly as possible.

The goal of continuous integration is to minimize the impact of problems found when integrating different software components together. A regular integration cycle ensures that the components are integrated together in small pieces. The advantage of this approach is that you don’t have to deal with large problems which might be troublesome to solve. Instead, you will face only smaller problems which in general should be easier and faster to solve. A failing test is an indicator of a such problem.

The true test which reveals if you are really doing continuous integration is this: What do you do when your build fails? If you are doing continuous integration, you will start fixing the problem as soon as you are aware that it exists. This is the condition which must be fulfilled before you can claim that you are doing continuous integration without lying. Keeping your build green should be your first priority because:

A green build signals that the code is working. At first this might seem like an answer given by a smartass but knowing that a build works has two advantages:

First, it helps developers to isolate the cause of problems they might face when they are adding more code to the code base. If they can trust that the code was working before they made changes to it, they know that their changes are the cause of their problems. Any developer who has worked with legacy code knows how valuable this is and how much time it saves.

Second, a green build is a good way to find out which parts of the developed software are done. In my opinion, the only way to verify that a code is working, is to write comprehensive tests to it. When those tests passes, you know that the code is working and you can start working on the next task on your to-do list. If you do not write comprehensive tests to your code or you decide not to write tests at all, you cannot know whether it works or not. And to make matters worse, you cannot know whether your code is working one month from now.

It prevents the situation from escalating into something much worse. You might have heard about the broken windows theory which states that taking a good care of urban environments may prevent vandalism and reduce the possibility that the situation would escalate into more serious crime. In my experience this theory can be applied to software development, and especially to continuous integration. If you don’t take failing tests seriously and fix them as soon as they appear, the developers get used to the situation. They start to think that a failing build is not such a big deal.

When this happens and you do not react, you will eventually end up in a situation where a lot of tests are failing and you are forced to figure out why (or ignore them forever). If the situation gets this bad, fixing it will last a lot longer than fixing a single failing test (Remember that fixing the failing tests is not enough anymore. You will also have to fix the attitude of your developers). In my experience, it is not wise (or pain free) to figure out how much longer it takes. Instead, I recommend that you choose to keep your build green. It is not just the easiest way. It is the only way.

I have now described to you why keeping your build green should be your first priority. A word of warning though, a green build does not guarantee that your software is bug free or that it is working. It only guarantees that the code compiles and that each test case passes. If you want to enjoy the benefits described in this blog entry, you must ensure that your test suite is in a great shape. And if you don’t have a proper test suite, start building one right now. The benefits of having a great test suite and keeping your build green are far greater than the so called benefits of any excuse you can make of.

Testing that All Service Methods Are Annotated with @Transactional Annotation

Petri — Fri, 16 Sep 2011 20:06:12 +0000

A common method of setting transaction boundaries in Spring Framework is to use its annotation driven transaction management and annotate service methods with @Transactional annotation. Seems pretty simple, right? Yes and no. Even though the annotation driven transaction management of Spring Framework is easy to setup and use, there are a few things which you must remember to do:

You must remember to annotate each service method with @Transactional annotation. This might seems a like an easy task but since you are probably a human being, you are also capable of making mistakes. A mistake like this might leave the database of your application in an inconsistent state if something goes wrong while your application is writing information to the database.
If you want to rollback the transaction when a service method throws a checked exception, you must specify the thrown checked exception class as a value of the rollbackFor property of the @Transactional annotation. This is needed because by default the Spring Framework will not rollback the transaction when a checked exception is thrown. If the rollbackFor attribute is of the @Transactional annotation is not set and a checked exception is thrown when your application is writing information to the database, the database of your application might end up in an inconsistent state.

Luckily is is quite easy to implement a test which ensures that

Each method of a service class except getters and setters are annotated with @Transactional annotation.
Each checked exception which is thrown by a service method is set as a value of the rollbackFor property of the @Transactional annotation.
As a bonus, this test will also check that each service class is annotated with @Service annotation.

I will describe next how you can write a unit test which verifies that both of the conditions given above are true by using JUnit and PathMatchingResourcePatternResolver class provided by Spring Framework. The source code of that unit test is given in following (The package declaration and the import statements are left out for the sake of readability):

public class ServiceAnnotationTest {

private static final String PACKAGE_PATH_SEPARATOR = ".";

/*
* A string which is used to identify getter methods. All methods whose name contains the given string
* are considered as getter methods.
*/
private static final String GETTER_METHOD_NAME_ID = "get";
private static final String FILE_PATH_SEPARATOR = System.getProperty("file.separator");

/*
* The file path to the root folder of service package. If the absolute path to the service package
* is /users/foo/classes/com/bar/service and the classpath base directory is /users/foo/classes,
* the value of this constant must be /com/bar/service.
*/
private static final String SERVICE_BASE_PACKAGE_PATH = "/com/bar/service";

/*
* A string which is used to identify setter methods. All methods whose name contains the given string
* are considered as setter methods.
*/
private static final String SETTER_METHOD_NAME_ID = "set";

/*
* A string which is used to identify the test classes. All classes whose name contains the given string
* are considered as test classes.
*/
private static final String TEST_CLASS_FILENAME_ID = "Test";

private List<Class> serviceClasses;

/**
* Iterates through all the classes found under the service base package path (and its sub directories)
* and inserts all service classes to the serviceClasses array.
*
* @throws IOException
* @throws ClassNotFoundException
*/
@Before
public void findServiceClasses() throws IOException, ClassNotFoundException {
serviceClasses = new ArrayList<Class>();
PathMatchingResourcePatternResolver resolver = new PathMatchingResourcePatternResolver();
Resource[] resources = resolver.getResources("classpath*:" + SERVICE_BASE_PACKAGE_PATH + "/**/*.class");
for (Resource resource : resources) {
if (isNotTestClass(resource)) {
String serviceClassCandidateNameWithPackage = parseClassNameWithPackage(resource);
ClassLoader classLoader = resolver.getClassLoader();
Class serviceClassCandidate = classLoader.loadClass(serviceClassCandidateNameWithPackage);
if (isNotInterface(serviceClassCandidate)) {
if (isNotException(serviceClassCandidate)) {
if (isNotEnum(serviceClassCandidate)) {
if (isNotAnonymousClass(serviceClassCandidate)) {
serviceClasses.add(serviceClassCandidate);
}
}
}
}
}
}
}

/**
* Checks if the resource given a as parameter is a test class. This method returns
* true if the resource is not a test class and false otherwise.
*
* @param resource
* @return
*/
private boolean isNotTestClass(Resource resource) {
return !resource.getFilename().contains(TEST_CLASS_FILENAME_ID);
}

/**
* Checks if the resource given as a parameter is an exception class. This method returns true
* if the class is not an exception class and false otherwise.
*
* @param exceptionCanditate
* @return
*/
private boolean isNotException(Class exceptionCanditate) {
return !Exception.class.isAssignableFrom(exceptionCanditate) &&
!RuntimeException.class.isAssignableFrom(exceptionCanditate) &&
!Throwable.class.isAssignableFrom(exceptionCanditate);
}

/**
* Parses a class name from the absolute path of the resource given as a parameter
* and returns the parsed class name. E.g. if the absolute path of the resource is
* /user/foo/classes/com/foo/Bar.class, this method returns com.foo.Bar.
*
* @param resource
* @return
* @throws IOException
*/
private String parseClassNameWithPackage(Resource resource) throws IOException {
String pathFromClasspathRoot = parsePathFromClassPathRoot(resource.getFile().getAbsolutePath());
String pathWithoutFilenameSuffix = parsePathWithoutFilenameSuffix(pathFromClasspathRoot);
return buildClassNameFromPath(pathWithoutFilenameSuffix);
}

/**
* Parses the path which starts from the classpath root directory by using the
* absolute path given as a parameter. Returns the parsed path.
* E.g. If the absolute path is /user/foo/classes/com/foo/Bar.class and the classpath
* root directory is /user/foo/classes/, com/foo/Bar.class is returned.
*
* @param absolutePath
* @return
*/
private String parsePathFromClassPathRoot(String absolutePath) {
int classpathRootIndex = absolutePath.indexOf(SERVICE_BASE_PACKAGE_PATH);
return absolutePath.substring(classpathRootIndex + 1);
}

/**
* Removes the file suffix from the path given as a parameter and returns new path
* without the suffix. E.g. If path is com/foo/Bar.class, com/foo/Bar is returned.
*
* @param path
* @return
*/
private String parsePathWithoutFilenameSuffix(String path) {
int prefixIndex = path.indexOf(PACKAGE_PATH_SEPARATOR);
return path.substring(0, prefixIndex);
}

/**
* Builds a class name with package information from a path given as a parameter and
* returns the class name with package information. e.g. If a path com/foo/Bar is given
* as a parameter, com.foo.Bar is returned.
*
* @param path
* @return
*/
private String buildClassNameFromPath(String path) {
return path.replace(FILE_PATH_SEPARATOR, PACKAGE_PATH_SEPARATOR);
}

/**
* Checks if the class given as an argument is an interface or not.
* Returns false if the class is not an interface and true otherwise.
*
* @param interfaceCanditate
* @return
*/
private boolean isNotInterface(Class interfaceCanditate) {
return !interfaceCanditate.isInterface();
}

/**
* Checks if the class given as an argument is an Enum or not.
* Returns false if the class is not Enum and true otherwise.
*
* @param enumCanditate
* @return
*/
private boolean isNotEnum(Class enumCanditate) {
return !enumCanditate.isEnum();
}

/**
* Checks if the class given as a parameter is an anonymous class.
* Returns true if the class is not an anonymous class and false otherwise.
*
* @param anonymousClassCanditate
* @return
*/
private boolean isNotAnonymousClass(Class anonymousClassCanditate) {
return !anonymousClassCanditate.isAnonymousClass();
}

/**
* Verifies that each method which is declared in a service class and which is not a
* getter or setter method is annotated with Transactional annotation. This test
* also ensures that the rollbackFor property of Transactional annotation specifies
* all checked exceptions which are thrown by the service method.
*/
@Test
public void eachServiceMethodHasTransactionalAnnotation() {
for (Class serviceClass : serviceClasses) {
Method[] serviceMethods = serviceClass.getMethods();
for (Method serviceMethod : serviceMethods) {
if (isMethodDeclaredInServiceClass(serviceMethod, serviceClass)) {
if (isNotGetterOrSetterMethod(serviceMethod)) {
boolean transactionalAnnotationFound = serviceMethod.isAnnotationPresent(Transactional.class);
assertTrue("Method " + serviceMethod.getName() + " of " + serviceClass.getName() + " class must be annotated with @Transactional annotation.", transactionalAnnotationFound);
if (transactionalAnnotationFound) {
if (methodThrowsCheckedExceptions(serviceMethod)) {
boolean rollbackPropertySetCorrectly = rollbackForPropertySetCorrectlyForTransactionalAnnotation(serviceMethod.getAnnotation(Transactional.class), serviceMethod.getExceptionTypes());
assertTrue("Method " + serviceMethod.getName() + "() of " + serviceClass.getName() + " class must set rollbackFor property of Transactional annotation correctly", rollbackPropertySetCorrectly);
}
}
}
}
}
}
}

/**
* Checks that the method given as a parameter is declared in a service class given as
* a parameter. Returns true if the method is declated in service class and false
* otherwise.
*
* @param method
* @param serviceClass
* @return
*/
private boolean isMethodDeclaredInServiceClass(Method method, Class serviceClass) {
return method.getDeclaringClass().equals(serviceClass);
}

/**
* Checks if the method given as parameter is a getter or setter method. Returns true
* if the method is a getter or setter method an false otherwise.
*
* @param method
* @return
*/
private boolean isNotGetterOrSetterMethod(Method method) {
return !method.getName().contains(SETTER_METHOD_NAME_ID) && !method.getName().contains(GETTER_METHOD_NAME_ID);
}

/**
* Checks if the method given as a parameter throws checked exceptions. Returns true
* if the method throws checked exceptions and false otherwise.
*
* @param method
* @return
*/
private boolean methodThrowsCheckedExceptions(Method method) {
return method.getExceptionTypes().length > 0;
}

/**
* Checks if the transactional annotation given as a parameter specifies all checked exceptions
* given as a parameter as a value of rollbackFor property. Returns true if all exceptions
* are specified and false otherwise.
*
* @param annotation
* @param thrownExceptions
* @return
*/
private boolean rollbackForPropertySetCorrectlyForTransactionalAnnotation(Annotation annotation, Class[] thrownExceptions) {
boolean rollbackForSet = true;

if (annotation instanceof Transactional) {
Transactional transactional = (Transactional) annotation;
List<Class extends Throwable>> rollbackForClasses = Arrays.asList(transactional.rollbackFor());
for (Class thrownException : thrownExceptions) {
if (!rollbackForClasses.contains(thrownException)) {
rollbackForSet = false;
break;
}
}
}

return rollbackForSet;
}

/**
* Verifies that each service class is annotated with @Service annotation.
*/
@Test
public void eachServiceClassIsAnnotatedWithServiceAnnotation() {
for (Class serviceClass : serviceClasses) {
assertTrue(serviceClass.getSimpleName() + " must be annotated with @Service annotation", serviceClass.isAnnotationPresent(Service.class));
}
}
}

I have now described to you how you can write a unit test which ensures that requirements given before the code example are met. However, the solution which I introduced to you is not yet “perfect”. My example has following limitations:

It checks all classes which are found from the service package or from its sub packages. It is possible that you might want to exclude some classes found from the service packages or exclude some methods of the included classes.
It expects that the transaction will be rolled back if a checked exception is thrown by a service method annotated with @Transactional annotation. In reality, you might not want to roll back the transaction for each thrown checked exception. If this is the case, the test should ensure that each thrown checked exception class is given either as a value of rollbackFor or as a value of noRollbackFor property of @Transactional annotation (Check the Spring reference manual for more details).

However, these improvements are left as an exercise for the reader.