Tuesday 18 August 2015

Spring Cloud for Amazon Web Services - Listen to SQS (JAVA Config)

While using spring-cloud-aws project to listen to SQS, I read this 
The Spring Cloud AWS configuration is currently done using custom elements provided by Spring Cloud AWS namespaces. JavaConfig will be supported soon.  
Soon!! huh?!! Well, this is a problem since I did not want to use XML config in my project.
However, the documentation adds 
It is recommended to use the XML messaging namespace to create QueueMessagingTemplate as it will set a more sophisticated MessageConverter that converts objects into JSON when Jackson is on the classpath.
I needed to use custom JSON convertor to convert my message and I was not going to use xml config. So I decided to give it a go and create the java config I need. I went on to read the spring-cloud-aws project code and some of the examples online. Then, borrowed some code from here and there that helped me accomplish my task. Here is the code, hopefully, it will make someone's life a little bit easier.
package com.coffeebeans.config;

import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
import com.amazonaws.regions.Region;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.sqs.AmazonSQS;
import com.amazonaws.services.sqs.AmazonSQSAsync;
import com.amazonaws.services.sqs.AmazonSQSAsyncClient;
import com.amazonaws.services.sqs.buffered.AmazonSQSBufferedAsyncClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.aws.context.annotation.ConditionalOnMissingAmazonClient;
import org.springframework.cloud.aws.messaging.config.QueueMessageHandlerFactory;
import org.springframework.cloud.aws.messaging.config.SimpleMessageListenerContainerFactory;
import org.springframework.cloud.aws.messaging.listener.QueueMessageHandler;
import org.springframework.cloud.aws.messaging.listener.SimpleMessageListenerContainer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Lazy;
import org.springframework.messaging.converter.MessageConverter;
import org.springframework.messaging.handler.annotation.support.PayloadArgumentResolver;
import org.springframework.messaging.handler.invocation.HandlerMethodArgumentResolver;

import java.util.ArrayList;
import java.util.List;

/**
 * Created by muhamadto on 8/18/15.
 */

@Configuration
@ComponentScan("com.coffeebeans")
public class SqsConfig {

    @Value("${queue.endpoint}")
    private String queueEndPoint;

    @Value("${aws.region}")
    private String awsRegion;

    @Autowired
    MessageConverter messageConverter;

    @Bean
    public SimpleMessageListenerContainer simpleMessageListenerContainer() {
        SimpleMessageListenerContainer messageListenerContainer = simpleMessageListenerContainerFactory().createSimpleMessageListenerContainer();
        messageListenerContainer.setMessageHandler(queueMessageHandler());
        return messageListenerContainer;
    }

    @Bean
    public SimpleMessageListenerContainerFactory simpleMessageListenerContainerFactory(){
        SimpleMessageListenerContainerFactory messageListenerContainerFactory = new SimpleMessageListenerContainerFactory();
        messageListenerContainerFactory.setAmazonSqs(amazonSQS());
        messageListenerContainerFactory.setDeleteMessageOnException(false);
        return messageListenerContainerFactory;
    }

    @Bean
    public QueueMessageHandler queueMessageHandler() {
        QueueMessageHandlerFactory queueMessageHandlerFactory = new QueueMessageHandlerFactory();
        queueMessageHandlerFactory.setAmazonSqs(amazonSQS());
        QueueMessageHandler messageHandler = queueMessageHandlerFactory.createQueueMessageHandler();

        List<HandlerMethodArgumentResolver> list = new ArrayList<>();
        HandlerMethodArgumentResolver resolver = new PayloadArgumentResolver(this.messageConverter);
        list.add(resolver);
        messageHandler.setArgumentResolvers(list);
        return messageHandler;
    }


    @Lazy
    @Bean(destroyMethod = "shutdown")
    @ConditionalOnMissingAmazonClient(AmazonSQS.class)
    public AmazonSQSAsync amazonSQS() {
        AmazonSQSAsyncClient amazonSQSAsyncClient  = new AmazonSQSAsyncClient(new DefaultAWSCredentialsProviderChain());
        amazonSQSAsyncClient.setEndpoint(this.queueEndPoint);
        amazonSQSAsyncClient.setRegion(Region.getRegion(Regions.fromName(this.awsRegion)));
        return new AmazonSQSBufferedAsyncClient(amazonSQSAsyncClient);
    }
}
Now annotate a method that belongs to any class in com.coffeebeans package with @MessageMapping("queue_name") where MessageMapping is org.springframework.messaging.handler.annotation.MessageMapping
For example

package com.coffeebeans.listener;

import com.coffeebeans.message.Message;
import org.springframework.messaging.handler.annotation.MessageMapping;

/**
 * Created by muhamadto on 8/18/15.
 */
public class QueueListener {
    @MessageMapping("queue_name")
    public void onMessage(Message message) throws Exception{
        System.out.println(message);
    }
}

As mentioned in the documentation and quoted above you will need Jackson in your class path.

Sunday 9 August 2015

PART 4: Spring MVC web-services (Spring Caching Abstraction)

This post explores how Spring framework supports caching. Like many features in Spring, caching is just abstraction. This allows applications to choose between the different caching implementation available, e.g. EHcache, Redis, Guava cache, ... etc. In Spring 4.1, the cache abstraction added support of JSR-107 annotations.


Dependancy

Add the following snippet to services/pom.xml
    

    org.springframework.data
    spring-data-redis
    1.4.3.RELEASE


    redis.clients
    jedis
    2.4.2
    jar
    compile

For the caching abstraction to work with an application developers need to do two things:
  • Configure cache implementation. In this project we will use Redis implementation.
  • Declare caching, that is which methods to be cached.


Configurations

Caching configuration in this project is being done on two steps, configuration file per technology (Redis, etc.) and a general configuration file.


Configure the Redis caching Manager

Add the following configuration class, com.coffeebeans.services.config.RedisCachingConfig
package com.coffeebeans.services.config;

import com.coffeebeans.utilities.generic.Constants;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.cache.CacheManager;
import org.springframework.context.annotation.*;
import org.springframework.core.env.Environment;
import org.springframework.data.redis.cache.RedisCacheManager;
import org.springframework.data.redis.connection.jedis.JedisConnectionFactory;
import org.springframework.data.redis.core.RedisTemplate;

/**
 * Created by muhamadto on 26/07/2015.
 */
@Configuration
public class RedisCachingConfig {
    @Autowired
    Environment env;

    @Bean
    JedisConnectionFactory jedisConnectionFactory() {
        JedisConnectionFactory factory = new JedisConnectionFactory();
        factory.setHostName(System.getProperty(Constants.REDIS_HOST_NAME, Constants.LOCALHOST));
        factory.setPort(Integer.parseInt(System.getProperty(Constants.REDIS_PORT)));
        factory.setUsePool(true);
        return factory;
    }

    @Bean
    RedisTemplate<Object, Object> redisTemplate() {
        RedisTemplate<Object, Object> redisTemplate = new RedisTemplate<>();
        redisTemplate.setConnectionFactory(jedisConnectionFactory());
        return redisTemplate;
    }

    @Bean
    CacheManager redisCacheManager() {
        RedisCacheManager redisCacheManager = new RedisCacheManager(redisTemplate());
        redisCacheManager.setUsePrefix(true);
        redisCacheManager.setDefaultExpiration(Constants.REDIS_DEFAULT_EXPIRY_TIME);
        return redisCacheManager;
    }
}

Notice: You will need to add JVM variables REDIS_HOST and REDIS_PORT which referred to by Constants.REDIS_HOST_NAME and Constants.REDIS_PORT of the new com.coffeebeans.utilities.generic.Constants class of Utilities module.
package com.coffeebeans.utilities.generic;

/**
 * Created by muhamadto on 2/08/2015.
 */
public class Constants {
    public static final String REDIS_HOST_NAME="REDIS_HOST";
    public static final String REDIS_PORT ="REDIS_PORT";
    public static final long REDIS_DEFAULT_EXPIRY_TIME=300;

    public static final String COFFEEBEANS_REPOSITORY_PACKAGE="repository.package";
    public static final String COFFEEBEANS_MODEL_PACKAGE="model.package";

    public static final String JDBC_DRIVER_CLASS="jdbc.driverClass";
    public static final String DB_URL="DB_URL";
    public static final String DB_USERNAME="DB_USERNAME";
    public static final String DB_PASSWORD="DB_PASSWORD";

    public static final String BONECP_IDLE_CONNECTION_TEST_PERIOD_IN_MINUTES="bonecp.idleConnectionTestPeriodInMinutes";
    public static final String BONECP_IDLE_MAX_AGE_IN_MINUTES="bonecp.idleMaxAgeInMinutes";
    public static final String BONECP_MAX_CONNECTIONS_PER_PARTITION="bonecp.maxConnectionsPerPartition";
    public static final String BONECP_MIN_CONNECTIONS_PER_PARTITION="bonecp.minConnectionsPerPartition";
    public static final String BONECP_PARTITION_COUNT="bonecp.partitionCount";
    public static final String BONECP_ACQUIRE_INCREMENT="bonecp.acquireIncrement";
    public static final String BONECP_STATEMENTS_CACHE_SIZE="bonecp.statementsCacheSize";

    public static final String HIBERNATE_CACHE_USE_SECOND_LEVEL_CACHE="hibernate.cache.use_second_level_cache";
    public static final String HIBERNATE_CACHE_REGION_FACTORY_CLASS="hibernate.cache.region.factory_class";
    public static final String HIBERNATE_CACHE_USE_QUERY_CACHE="hibernate.cache.use_query_cache";
    public static final String HIBERNATE_GENERATE_STATISTICS="hibernate.generate_statistics";
    public static final String HIBERNATE_DIALECT="hibernate.dialect";

    public static final String LOCALHOST="localhost";
}


Abstract caching manager

Add the following class, com.coffeebeans.services.config.CachingConfig
package com.coffeebeans.services.config;

import com.coffeebeans.utilities.env.Environment;
import com.coffeebeans.utilities.env.EnvironmentEnum;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.cache.CacheManager;
import org.springframework.cache.annotation.CachingConfigurer;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.cache.interceptor.CacheErrorHandler;
import org.springframework.cache.interceptor.CacheResolver;
import org.springframework.cache.interceptor.KeyGenerator;
import org.springframework.cache.interceptor.SimpleKeyGenerator;
import org.springframework.cache.support.CompositeCacheManager;
import org.springframework.cache.support.NoOpCacheManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;

import java.util.ArrayList;
import java.util.List;

/**
 * Created by muhamadto on 2/08/2015.
 */
@Configuration
@EnableCaching
@Import({RedisCachingConfig.class})
@ComponentScan(basePackages = {"com.coffeebeans.services.service"})
public class CachingConfig implements CachingConfigurer {

    @Qualifier("redisCacheManager")
    @Autowired
    private CacheManager redisCacheManager;


    @Bean
    @Override
    public CacheManager cacheManager() {
        List<Cachemanager> cacheManagers = new ArrayList<>();

        if(EnvironmentEnum.LOCAL == Environment.resoveEnv()){
            cacheManagers.add(new NoOpCacheManager());
        } else {
            cacheManagers.add(this.redisCacheManager);
        }

        CompositeCacheManager cacheManager = new CompositeCacheManager();
        cacheManager.setCacheManagers(cacheManagers);
        cacheManager.setFallbackToNoOpCache(true);
        return cacheManager;
    }

    @Bean
    @Override
    public KeyGenerator keyGenerator() {
        return new SimpleKeyGenerator();
    }

    @Override
    public CacheResolver cacheResolver() {
        return null;
    }

    @Override
    public CacheErrorHandler errorHandler() {
        return null;
    }
}
This last class provide us to disable caching for local machines using org.springframework.cache.support.NoOpCacheManager.

Now Import the Caching Config to AppConfig
package com.coffeebeans.services.config;

import com.coffeebeans.persistence.config.PersistenceConfig;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;

/**
 * Created by muhamadto on 26/07/2015.
 */

@Configuration
@Import({PersistenceConfig.class, ServicesConfig.class, CachingConfig.class})
public class AppConfig {
}

You might realised the usage of Environment.resoveEnv in CachingConfig. This method lives in class  com.coffeebeans.utilities.env.Environment in the newly created Utilities module.
package com.coffeebeans.utilities.env;

/**
 * Created by muhamadto on 2/08/2015.
 */
public class Environment {

    public static EnvironmentEnum resoveEnv() throws IllegalArgumentException, NullPointerException{
        return EnvironmentEnum.valueOf(System.getProperty("env").toUpperCase());

    }
}
And it uses the following enum which represents the three environments possible for this project. 
package com.coffeebeans.utilities.env;

/**
 * Created by muhamadto on 2/08/2015.
 */
public enum EnvironmentEnum {
    LOCAL("LOCAL"),
    STAGING("STAGING"),
    PROD("STAGING");

    private String env;

    EnvironmentEnum(String env){
        this.env = env;
    }

    public String toString() {
        return env;
    }
}
Now the configuration is done, let's declare a method as cachable and inspect the resulting behaviour.
  

Declare cachable Methods

In com.coffeebeans.services.service.user.UserServiceImpl, add @Cacheable(value = "users") before getUserByUsername(). So, it looks like the following:
@Override
@Cacheable(value = "users")
public UserResponse getUserByUsername(String username) {
    UserResponse userResponse;
    User user = this.userRepository.findByUsername(username);
    if(user != null){
        userResponse = UserResponse.convert(user);
    } else{
        LOGGER.error("Could not find a user for search criteria [{}]", username);
        throw new NotFoundException(String.format("Could not find a user for search criteria [username = %s]", username));
    }
    LOGGER.debug("User has been found [{}].", user);
    return userResponse;
} 


TESTING

Testing Locally

Use curl command to retrieve a use 
  • Request
  • curl  http://localhost:8080/services/1/user/mh
  • Response
  • {
       {  
       "location":"http://localhost:8080/services/1/user/mh",
       "enabled":false,
       "verified":false,
       "username":"mh",
       "email":"mh@example.com"
    }
However, every time you make the request the method will be executed, you can verify that from the log, as the following message will be printed once per request.
[SRV] 19:23:53.613 DEBUG com.coffeebeans.services.service.user.UserServiceImpl - User has been found [User(username=mh, email=mh@example.com)].

Testing On Staging

Making the same request in staging environment - given Redis server is working - will result in single execution for that method. All subsequent requests will retrieve the data from the cache. You can verify that by making sure that no message is being print in the log as a result of the request.


WHAT IS NEXT

Since in this post we started to make use for environments different form local machine. Next step in this project will be setting up a foundation for supporting multiple environment.

Saturday 18 July 2015

PART 3: Spring MVC web-services (Validating Requests Using JSR 303)

Image: Stuart Miles

In the last post, this series identified the required steps to support persistence using Spring Data JPA in API powered by Spring MVC. It taught us that users can make a request using JSON representation of some java bean in our application. Then they expect that their requests trigger some actions (e.g. singing up a user) and that the API will return adequate responses. 
However, how can the API make sure that the request is valid in the first place?


Example of Invalid Request

A client of the signup webservice we wrote in the last post might make this request
curl -H "Content-Type: application/json; charset=utf-8" --data '{"email":"post", "password":"ww"}' http://localhost:8080/services/1/user
So what is exactly wrong with that request. Well, all three fields are invalid:
  • email format is not correct.
  • username  is null
  • password is too short
Hence, we need a code somewhere in our application to add constrains on data been provided by users.

JSR 303: BEAN VALIDATION

Throughout the application from presentation layer to persistence layer developers need to validate date. JSR-303 provided a framework to validate beans using metadata model (annotations). This save us from writing the validation logic ourselves. It, also, provide us with a chance to avoid duplicating this validation code in every layer of our application. It separates the concerns leaving the pojo classes free of cluttered validation code. This project will use Hibernate validator as implantation of JSR-303


Dependancy

In CoffeeBeansRest/pom.xml add the following dependancy 

    org.hibernate
    hibernate-validator
    5.1.3.Final


Validator Bean

In Service/com.coffeebeans.config.ServicesConfig add the following bean
@Bean
public Validator validator() {
    return new LocalValidatorFactoryBean();
}


Annotation entity classes

Now, change com.coffeebeans.domain.request.user.UserSignupRequest to be as following
package com.coffeebeans.domain.request.user;

import lombok.Data;
import org.hibernate.validator.constraints.Email;
import org.hibernate.validator.constraints.Length;

import javax.validation.constraints.NotNull;

/**
 * Created by muhamadto on 12/07/2015.
 */

@Data
public class UserSignupRequest {

    @NotNull @Email
    private String email;

    @NotNull
    private String username;

    @NotNull @Length(min=8, max=16)
    private String password;
}
This class showed us 3 validation annotation
  1. javax.validation.constraints.NotNull, which means that the  client must provide a value for this field.
  2. org.hibernate.validator.constraints.Length, using this annotation we can specify min and max length of a field (e.g. password).
  3. org.hibernate.validator.constraints.Email, makes sure that the supplied value for the field annotate with it is a valid email format.
NOTE: It would make sense to add length check on the username and email among other checks. However, covering the annotations in JSR303 is not the goal of this post. The scope of this lesson is rather, to explain how data validation can be enabled in Spring RESTful API.

Create validation Exception

This exception is going to be returned to the services' clients if the requests were invalid.
package com.coffeebeans.exception.validation;

import com.coffeebeans.api.error.ValidationError;

import javax.validation.ConstraintViolation;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import java.util.Set;

/**
 * Created by muhamadto on 12/07/2015.
 */
public class ValidationException extends RuntimeException{
    private List<validationerror> validationErrors = new ArrayList<validationerror>();
    public ValidationException (){
        super();
    }

    public ValidationException (String message){
        super(message);
    }

    public ValidationException(String message, Throwable cause) {
        super(message, cause);
    }
    public ValidationException(Throwable cause) {
        super(cause);
    }

    protected ValidationException(String message, Throwable cause,
                                  boolean enableSuppression,
                                  boolean writableStackTrace) {
        super(message, cause, enableSuppression, writableStackTrace);
    }

    public ValidationException(Set> constraintViolations) {
        Iterator> iterator = constraintViolations.iterator();

        while(iterator.hasNext()){
            ConstraintViolation invalidConstraint = iterator.next();
            ValidationError validationError = new ValidationError();
            validationError.setMessage(invalidConstraint.getMessage());
            validationError.setPropertyName(String.valueOf(invalidConstraint.getPropertyPath()));
            validationError.setPropertyValue(String.valueOf(invalidConstraint.getInvalidValue()));
            validationErrors.add(validationError);
        }
    }

    public List<validationerror> getValidationErrors() {
        return validationErrors;
    }
}
This Exception class uses another class that comprises of:
  • Name of the field with invalid value;
  • The value that violated the constrains 
  • custom message
package com.coffeebeans.api.error;

import lombok.Data;

/**
 * Created by muhamadto on 12/07/2015.
 */
public @Data
class ValidationError {
    private String propertyName;
    private String propertyValue;
    private String message;
}


Use Validator Bean

com.coffeebeans.service.base.BaseService is a good place to write a generic method to validate if data is violating the constrains dictate through the metadata.
@Autowired
Validator validator;

protected void validate(Object request) throws ValidationException{
    Set<? extends ConstraintViolation<?>> constraintViolations = validator.validate(request);
    if (!CollectionUtils.isEmpty(constraintViolations)) {
        throw new ValidationException(constraintViolations);
    }
}
The app autowired the validator bean and used it to check the data.


Perform the validation on requests

As an example, let's validate the UserSignupRequest from last post. Make a call to com.coffeebeans.service.base.BaseService#validate() in the first line of com.coffeebeans.service.user.UserServiceImpl#createUser(). The logic should be like this.
@Override
@Transactional
public UserResponse createUser(UserSignupRequest userSignupRequest, Role role) {
    validate(userSignupRequest);

    UserResponse newUser;

    final String email = userSignupRequest.getEmail().toLowerCase();
    if(this.userRepository.findByEmail(email) == null){
        LOGGER.info("User does not  exist - creating a new user [{}].", userSignupRequest.getUsername());

        User user = new User(userSignupRequest);
        user.setRole(role);
        Date now = new Date();

        user.setInsertDate(now);
        user.setLastModified(now);

        user = this.userRepository.save(user);

        newUser = UserResponse.convert(user);

        LOGGER.debug("Created new user [{}].", user);
    } else{
        LOGGER.error("Duplicate user located [{}], exception raised with appropriate HTTP response code.", email);
        throw new DuplicateEntryException("User already exists.");
    }
    return newUser;
}


Exception Handling

In com.coffeebeans.controller.base.BaseController add the following snippet.
@ResponseBody
@ExceptionHandler(ValidationException.class)
@ResponseStatus(value = HttpStatus.BAD_REQUEST)
ErrorResponse handleException(ValidationException e){
    return new ErrorResponse(HttpStatus.BAD_REQUEST.toString(), e.getMessage(), "Bad Request", e.getValidationErrors());
}
The com.coffeebeans.api.error.ErrorResponse now has a new constructor which takes additional list of the validation errors.
package com.coffeebeans.api.error;

import lombok.Data;

import java.util.ArrayList;
import java.util.List;

/**
 * Created by muhamadto on 12/07/2015.
 */
@Data
public class ErrorResponse {

    private String errorCode;
    private String consumerMessage;
    private String applicationMessage;
    private List<validationerror> validationErrors = new ArrayList<>();

    public ErrorResponse(){}

    public ErrorResponse(String errorCode, String consumerMessage,  String applicationMessage){
        this(errorCode, consumerMessage, applicationMessage, null);
    }

    public ErrorResponse(String errorCode, String consumerMessage,  String applicationMessage, List<validationerror> validationErrors){
        this.errorCode = errorCode;
        this.consumerMessage = consumerMessage;
        this.applicationMessage = applicationMessage;
        this.validationErrors = validationErrors;
    }
}


Using the invalid request again

Try to send this request at the begging of this post again

  • Request
  • curl -H "Content-Type: application/json; charset=utf-8" --data '{"email":"post", "password":"ww"}' http://localhost:8080/services/1/user
  • Response
  • {
        "errorCode": "400"
        "consumerMessage"": null
        "applicationMessage": "Bad Request"
        "validationErrors":[
            {
                "propertyName": "email"
                "propertyValue": "post"
                "message": "not a well-formed email address"
            },{
                "propertyName": "password"
                "propertyValue": "ww"
                "message": "length must be between 8 and 16"
            },{
                "propertyName": "username"
                "propertyValue: "null"
                "message": "may not be null"
            }
        ]
    }


What is next

In this post we learned how to validate data which was provided by client. In the next post, this series will navigate how to cache API output.

Monday 13 July 2015

PART 2: Spring MVC web-service (Supporting Spring Data JPA)

The last post outlined how to use Spring MVC to kick-start a RESTful web-services application. This post will build upon what we learned from last lesson by building persistence mechanism using Spring Data JPA. Download the code of this project from Github.


WHAT TECHNOLOGIES WILL BE USED?

  • MySQL
  • Spring Data JPA
  • BoneCP (JDBC Connection Pool)
  • Hibernate (as JPA Vendor)
  • Ehcache

DEPendancies

In Persistence/pom.xml we will need to add the dependancies required for Spring Data JPA.
    
        4.3.5.Final
    

    
        
            org.springframework.boot
            spring-boot-starter-data-jpa
            1.8.1.RELEASE
        

        
            org.hibernate
            hibernate-entitymanager
            ${hibernate}
        

        
            org.hibernate
            hibernate-ehcache
            ${hibernate}
            
                
                    net.sf.ehcache
                    ehcache-core
                
            
        

        
            net.sf.ehcache
            ehcache
            2.7.0
        

        
            mysql
            mysql-connector-java
            5.1.22
            runtime
        

        
            com.jolbox
            bonecp
            0.7.1.RELEASE
        
    
Now, what did all that mean? These dependancies instruct the application to use:
  1. Spring Data JPA module.
  2. Hibernate as JPA vendor. The usage of HibernateJpaVendorAdapter ensure that our application will not require persistence.xml among many other benefits like support for supports the detection of annotated packages
  3. Hibernate Ehcache module but excludes the core module as hibernate uses version and no Ehcache has newer versions 
  4. BoneCP as connection pool, I personally find it fast. However, it seems that the project is discontinued. So, it may be time to think about an alternative Maybe Tomcat JDBC.
  5. mysql database (You may delete this dependancy and place the connector in <%CATALINA_HOME%>/lib)


Configuration

To configure Spring in persistence we will need to define a new java config file, and register this config class to root context in com.coffeebeans.initializer.WebAppInitializer  

Config Class

package com.coffeebeans.config;

import com.coffeebeans.utils.Constants;
import com.jolbox.bonecp.BoneCPDataSource;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.PropertySource;
import org.springframework.core.env.Environment;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import org.springframework.orm.jpa.JpaTransactionManager;
import org.springframework.orm.jpa.JpaVendorAdapter;
import org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean;
import org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter;
import org.springframework.transaction.PlatformTransactionManager;
import org.springframework.transaction.annotation.EnableTransactionManagement;

import javax.persistence.EntityManagerFactory;
import javax.sql.DataSource;
import java.util.Properties;

/**
 * Created by muhamadto on 12/07/2015.
 */

@Configuration
@EnableTransactionManagement
@EnableJpaRepositories(basePackages = "com.coffeebeans.repository")
@PropertySource("classpath:default.properties")
public class PersistenceConfig {
    @Autowired
    Environment env;

    @Bean(destroyMethod = "close")
    public DataSource dataSource() {
        BoneCPDataSource dataSource = new BoneCPDataSource();
        dataSource.setJdbcUrl(System.getProperty(Constants.DB_URL, Constants.LOCALHOST));
        dataSource.setUsername(System.getProperty(Constants.DB_USERNAME));
        dataSource.setPassword(System.getProperty(Constants.DB_PASSWORD));
        dataSource.setIdleConnectionTestPeriodInMinutes(Integer.parseInt(env.getProperty(Constants.BONECP_IDLE_CONNECTION_TEST_PERIOD_IN_MINUTES)));
        dataSource.setIdleMaxAgeInMinutes(Integer.parseInt(env.getProperty(Constants.BONECP_IDLE_MAX_AGE_IN_MINUTES)));
        dataSource.setMaxConnectionsPerPartition(Integer.parseInt(env.getProperty(Constants.BONECP_MAX_CONNECTIONS_PER_PARTITION)));
        dataSource.setMinConnectionsPerPartition(Integer.parseInt(env.getProperty(Constants.BONECP_MIN_CONNECTIONS_PER_PARTITION)));
        dataSource.setPartitionCount(Integer.parseInt(env.getProperty(Constants.BONECP_PARTITION_COUNT)));
        dataSource.setAcquireIncrement(Integer.parseInt(env.getProperty(Constants.BONECP_ACQUIRE_INCREMENT))) ;
        dataSource.setStatementsCacheSize( Integer.parseInt(env.getProperty(Constants.BONECP_STATEMENTS_CACHE_SIZE)));
        return dataSource;
    }

    @Bean
    public LocalContainerEntityManagerFactoryBean entityManagerFactory() {
        LocalContainerEntityManagerFactoryBean em = new LocalContainerEntityManagerFactoryBean();
        em.setDataSource(dataSource());
        em.setPackagesToScan(env.getProperty(Constants.COFFEEBEANS_MODEL_PACKAGE));
        JpaVendorAdapter vendorAdapter = new HibernateJpaVendorAdapter();
        em.setJpaVendorAdapter(vendorAdapter);
        em.setJpaProperties(additionalProperties());
        return em;
    }

    @Bean
    public PlatformTransactionManager transactionManager(EntityManagerFactory emf){
        JpaTransactionManager transactionManager = new JpaTransactionManager();
        transactionManager.setEntityManagerFactory(emf);

        return transactionManager;
    }

    private Properties additionalProperties() {
        Properties prop = new Properties();
        prop.setProperty(Constants.HIBERNATE_CACHE_USE_SECOND_LEVEL_CACHE, env.getProperty(Constants.HIBERNATE_CACHE_USE_SECOND_LEVEL_CACHE));
        prop.setProperty(Constants.HIBERNATE_CACHE_REGION_FACTORY_CLASS, env.getProperty(Constants.HIBERNATE_CACHE_REGION_FACTORY_CLASS));
        prop.setProperty(Constants.HIBERNATE_CACHE_USE_QUERY_CACHE, env.getProperty(Constants.HIBERNATE_CACHE_USE_QUERY_CACHE));
        prop.setProperty(Constants.HIBERNATE_GENERATE_STATISTICS, env.getProperty(Constants.HIBERNATE_DIALECT));
        prop.setProperty(Constants.HIBERNATE_DIALECT, env.getProperty(Constants.HIBERNATE_DIALECT));

        return prop;
    }
}
Notice that DB_URL, DB_USERNAME, and DB_PASSWORD are jvm variables

Register The Config Class With The Root Context

In com.coffeebeans.initializer.WebAppInitializer change onStartUp
@Override
public void onStartup(ServletContext servletContext) throws ServletException {
    AnnotationConfigWebApplicationContext rootContext = new AnnotationConfigWebApplicationContext();
    rootContext.register(ServicesConfig.class,PersistenceConfig.class);
    servletContext.addListener(new ContextLoaderListener(rootContext));

    AnnotationConfigWebApplicationContext dispatcherServlet = new AnnotationConfigWebApplicationContext();
    dispatcherServlet.register(MvcConfig.class);

    ServletRegistration.Dynamic dispatcher = servletContext.addServlet("mvc-dispatcher", new DispatcherServlet(dispatcherServlet));
    dispatcher.setLoadOnStartup(1);
    dispatcher.addMapping("/1/*");

    FilterRegistration charEncodingFilterReg = servletContext.addFilter("CharacterEncodingFilter", CharacterEncodingFilter.class);
    charEncodingFilterReg.setInitParameter("encoding", "UTF-8");
    charEncodingFilterReg.setInitParameter("forceEncoding", "true");
    charEncodingFilterReg.addMappingForUrlPatterns(EnumSet.allOf(DispatcherType.class), false, "/*");
}

PersistenceConfig is annotated with:
  1. org.springframework.context.annotation.Configuration, which signals that this class is a Spring config class
  2. org.springframework.transaction.annotation.EnableTransactionManagement, to enable Spring's annotation-driven transaction management capability, similar to the support found in Spring's <tx:*> XML namespace
  3. org.springframework.data.jpa.repository.config.EnableJpaRepositories, to enable and activate Spring Data JPA repositories as the name suggests  and to provide information on which base package will contain the repositories, in our example basePackages = "com.coffeebeans.repository".If no base package is configured it will use the one the configuration class resides in. In other work, Spring will scan for JPA repositories in the provided package to sire them later in a client that might depend on them.
  4. org.springframework.context.annotation.PropertySource, declarative way for adding properties to Spring environment. In our case these properties define in default.properties file.
It defines the following beans:
  1. DataSource bean of type BoneCPDataSource. It uses a connection pool to the data base. In this example we use DB url, username and password. In a production environment it would be better to create a data source in the container (e.g. tomcat -> contaxt.xml) and look it up using JNDI. However, this will need web.xml to be define because Servlet 3 Java API does not have replacement for <resource-ref/>.
  2. EntityManagerFactory bean of type  LocalContainerEntityManagerFactoryBean. It creates JPA EntityManagerFactory and provide ability to pass it to JPA-based DAOs using dependancy injectionThis FactoryBean is more flexible in that you can override the location of the persistence.xml file. However, in Spring 4 we can instruct the code to use Spring-based scanning for entity classes in the classpath instead of JPA's approach which uses persistence.xml. This can be done by calling setPackagesToScan() on the LocalContainerEntityManagerFactoryBean.
  3. TransactionManager bean of type PlatformTransactionManager, for controlling transactions. 
Remember default.properties?!  Here's it. In Persistence module add default.properties in src/main/resources
################### DataSource Configuration ##########################

jdbc.driverClass=com.mysql.jdbc.Driver
jdbc.dataSource=java:comp/env/jdbc/Rest

init-db=false

################### Hibernate Configuration ##########################

hibernate.show_sql=false
hibernate.hbm2ddl.auto=update
hibernate.generateDdl=false
hibernate.cache.use_second_level_cache=true
hibernate.cache.region.factory_class=org.hibernate.cache.ehcache.EhCacheRegionFactory
hibernate.cache.use_query_cache=true
hibernate.generate_statistics=true
hibernate.dialect=org.hibernate.dialect.MySQL5Dialect

############################### BoneCP ##############################

bonecp.driverClass=com.mysql.jdbc.Driver
bonecp.dataSource=java:comp/env/jdbc/Rest
bonecp.idleMaxAgeInMinutes=240
bonecp.idleConnectionTestPeriodInMinutes=60
bonecp.maxConnectionsPerPartition=10
bonecp.minConnectionsPerPartition=1
bonecp.partitionCount=2
bonecp.acquireIncrement=5
bonecp.statementsCacheSize=100

############################ Persistence ###########################

repository.package=com.coffeebeans.repository
model.package=com.coffeebeans.domain.model

and add com.coffeebeans.utils.Constants, to define the identifiers of the properties as java constants.
package com.coffeebeans.utils;

/**
 * Created by muhamadto on 12/07/2015.
 */
public class Constants {
    public static final String COFFEEBEANS_REPOSITORY_PACKAGE = "repository.package";
    public static final String COFFEEBEANS_MODEL_PACKAGE = "model.package";
    public static final String LOCALHOST = "localhost";

    public static final String JDBC_DRIVER_CLASS = "jdbc.driverClass";
    public static final String DB_URL = "DB_URL";
    public static final String DB_USERNAME = "DB_USERNAME";
    public static final String DB_PASSWORD = "DB_PASSWORD";

    public static final String BONECP_IDLE_CONNECTION_TEST_PERIOD_IN_MINUTES = "bonecp.idleConnectionTestPeriodInMinutes";
    public static final String BONECP_IDLE_MAX_AGE_IN_MINUTES = "bonecp.idleMaxAgeInMinutes";
    public static final String BONECP_MAX_CONNECTIONS_PER_PARTITION = "bonecp.maxConnectionsPerPartition";
    public static final String BONECP_MIN_CONNECTIONS_PER_PARTITION = "bonecp.minConnectionsPerPartition";
    public static final String BONECP_PARTITION_COUNT = "bonecp.partitionCount";
    public static final String BONECP_ACQUIRE_INCREMENT = "bonecp.acquireIncrement";
    public static final String BONECP_STATEMENTS_CACHE_SIZE = "bonecp.statementsCacheSize";

    public static final String HIBERNATE_CACHE_USE_SECOND_LEVEL_CACHE = "hibernate.cache.use_second_level_cache";
    public static final String HIBERNATE_CACHE_REGION_FACTORY_CLASS = "hibernate.cache.region.factory_class";
    public static final String HIBERNATE_CACHE_USE_QUERY_CACHE = "hibernate.cache.use_query_cache";
    public static final String HIBERNATE_GENERATE_STATISTICS = "hibernate.generate_statistics";
    public static final String HIBERNATE_DIALECT = "hibernate.dialect";
}

By registering PersistenceConfig with rootContext in com.coffeebeans.initializer.WebAppInitializer#onStartup(), Spring Data JPA is component is fully configured. Now, lets add entities and repositories.


Entity Classes

Entity class are in com.coffeebeans.domain.model package as we previously specified using LocalContainerEntityManagerFactoryBean#setPackagesToScan() in com.coffeebeans.config.PersistenceConfig.

Define a super class for entity classes

import lombok.Data;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.annotation.LastModifiedDate;
import org.springframework.data.jpa.domain.AbstractPersistable;
import org.springframework.util.Assert;

import javax.persistence.*;
import java.util.Date;
import java.util.UUID;

/**
 * Created by muhamadto on 12/07/2015.
 */

@MappedSuperclass
@Data
public class DomainObject extends AbstractPersistable <long > {

    @Version
    protected int version;

    @Column(length = 36, unique = true, nullable = false)
    protected String uuid;

    @CreatedDate
    protected Date insertDate;

    @LastModifiedDate
    protected Date lastModified;

    public DomainObject() {
        this(UUID.randomUUID());
    }

    public DomainObject(UUID uuid) {
        Assert.notNull(uuid, "UUID is required");
        this.uuid = uuid.toString();
        this.insertDate = new Date();
    }
}
Let's inspect this class closely:
  • DomainObject class inherts from  org.springframework.data.jpa.domain.AbstractPersistable which ultimitly inherets Serializable and add mapping for id property. 
  • DomainObject class is annotate with javax.persistence.MappedSuperclass, which means that the mappings for its fields apply only to its subclasses.
  • Another annotation also is lombok.Data, This saves us from writing boilerplate code for setters, getters, default constructor, ... etc.
  • It contains the general fields that all entity classes must have, like inserDate, id (which it inherits from AbstractPersistable) and version.

Define User entity class

package com.coffeebeans.domain.model.user;

import com.coffeebeans.domain.model.base.DomainObject;
import com.coffeebeans.domain.request.user.UserSignupRequest;
import lombok.Data;
import org.hibernate.annotations.CacheConcurrencyStrategy;
import org.hibernate.annotations.Type;
import org.hibernate.annotations.Cache;

import javax.persistence.*;
import java.util.UUID;

/**
 * Created by mohamedhamtou on 28/12/14.
 */
@Entity
@Table(name="USER")
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE, region = "user")
@Data
public class User extends DomainObject {
    @Column(length = 36, unique = true, nullable = false)
    protected String username;

    @Column(length = 36, unique = true, nullable = false)
    protected String email;

    @Column(length = 16, nullable = false)
    protected String password;

    @Type(type = "numeric_boolean")
    protected boolean enabled;
    
    @Type(type = "numeric_boolean")
    protected boolean verified = false;

    @Enumerated(EnumType.STRING)
    protected Role role;
    
    public User() {
        this(UUID.randomUUID());
    }

    public User(UUID uuid) {
        super(uuid);
    }

    public User(String username, String email, String encryptedPassword) {
        super(UUID.randomUUID());
        this.username = username.toLowerCase();
        this.email = email.toLowerCase();
        this.password = encryptedPassword;
    }

    public User(UserSignupRequest userSignupRequest) {
        super(UUID.randomUUID());
        this.username = userSignupRequest.getUsername().toLowerCase();
        this.email = userSignupRequest.getEmail().toLowerCase();
        this.password = userSignupRequest.getPassword();
    }
}
Important things to notice:
  • It's annotated with javax.persistence.Entity
  • Its corresponding table called USER, we know that through the annotation javax.persistence.Table
  • org.hibernate.annotations.Cache, to add caching strategy, region attribute refers to cache in ehcache.xml
The user role is define in com.coffeebeans.domain.model.user.Role
package com.coffeebeans.domain.model.user;

/**
 * Created by muhamadto on 5/07/2015.
 */
public enum Role {

    ROLE_ANONYMOUS("ROLE_ANONYMOUS"),
    ROLE_USER("ROLE_USER"),
    ROLE_ADMIN("ROLE_ADMIN");

    private String userAuthorityType;
    private Role(String userAuthorityType){
        this.userAuthorityType= userAuthorityType;
    }

    public String toString() {
        return userAuthorityType;
    }
}

DataBase

CREATE DATABASE `Rest`;

USE `Rest`;

CREATE TABLE `USER` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `insertDate` datetime NOT NULL,
  `lastModified` datetime NOT NULL,
  `uuid` varchar(36) NOT NULL,
  `version` int(11) NOT NULL,
  `email` varchar(36) NOT NULL,
  `enabled` bit(1) NOT NULL,
  `verified` bit(1) NOT NULL,
  `password` varchar(16) NOT NULL,
  `role` varchar(25) NOT NULL,
  `username` varchar(36) NOT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uuid` (`uuid`),
  UNIQUE KEY `username_UNIQUE` (`username`),
  UNIQUE KEY `email_UNIQUE` (`email`),
  UNIQUE KEY `id_UNIQUE` (`id`)
);

CACHING

For now we will focus on 2nd level caching of hibernate. This can be done by:
  • Add src/main/resources/ehcache.xml in Persistence module.


    

    
        
    

    
        
    
  • Annotating entity classes (e.g. User) with org.hibernate.annotations.Cache
  • Adding the following properties to the EntityManagerFactory (please revisit PersistenceConfig#additionalProperties())
    • hibernate.cache.use_second_level_cache=true
    • hibernate.cache.region.factory_class=org.hibernate.cache.ehcache.EhCacheRegionFactory
    • hibernate.cache.use_query_cache=true


Defining Repositories

  • Repositories live in com.coffeebeans.repository package as we previously specified using @EnableJpaRepositories(basePackages = "com.coffeebeans.repository") in com.coffeebeans.config.PersistenceConfig.
  • In Spring Data JPA, Repository interface is the central interface. It takes the the domain class (e.g. User) to manage as well as the id type of the domain class as type arguments (e.g. Long as we passed Long to AbstractPersistable while defining DomainObject super class). This Repository interface acts as a marker interface to capture the types to work with. 
  • The CrudRepository that inserts Repository adds sophisticated CRUD functionality for the entity class that is being managed
  • PagingAndSortingRepository adds methods to facilitate paginated access to entities.
  • Then persistence technology specific sub-interfaces to include additional technology specific methods like JpaRepository in our example.

Define User repository interface

package com.coffeebeans.repository.user;

import com.coffeebeans.domain.model.user.User;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

/**
 * Created by muhamadto on 12/07/2015.
 */

@Repository("userRepository")
public interface UserRepository extends JpaRepository<User, Long> {
    User findByUsername(String username);
    User findByEmail(String email);
    User findByUuid(String uuid);
    User findById(Long id);
}

Before we go and build a service to use our repository we will add two additional types of classes.
  • Request class: which a client of a service will provide in the request
  • Response class: which will be returned to the service caller.

Request Class

package com.coffeebeans.domain.request.user;

import lombok.Data;

/**
 * Created by muhamadto on 12/07/2015.
 */

@Data
public class UserSignupRequest {

    private String email;

    private String username;

    private String password;
}

Response Class

package com.coffeebeans.domain.response;
import lombok.Data;

import java.net.URI;

/**
 * Created by mohamedhamtou on 20/02/15.
 */
@Data 
public class BaseResponse {
    protected URI location;
}

package com.coffeebeans.domain.response;

import com.coffeebeans.domain.model.user.User;
import com.coffeebeans.domain.response.base.BaseResponse;
import lombok.Data;

/**
 * Created by mohamedhamtou on 20/02/15.
 */
@Data
public class UserResponse extends BaseResponse{
    protected boolean enabled;
    protected boolean verified;

    protected String username;
    protected String email;

    public static UserResponse convert(User user){
        UserResponse userResponse = new UserResponse();
        
        userResponse.setUsername(user.getUsername());
        userResponse.setEmail(user.getEmail());
        userResponse.setVerified(user.isVerified());
        userResponse.setEnabled(user.isEnabled());

        return userResponse;
    }
}
Now persistence module is ready to be used. So, let's build a service to use it.

BUILDING THE CLIENT

In Services module

Define A User Controller

import com.coffeebeans.controller.base.BaseController;
import com.coffeebeans.domain.model.user.Role;
import com.coffeebeans.domain.request.user.UserSignupRequest;
import com.coffeebeans.domain.response.UserResponse;
import com.coffeebeans.service.user.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;

import java.net.URI;

/**
 * Created by muhamadto on 12/07/2015.
 */

@RestController
@RequestMapping(value = "user", produces = MediaType.APPLICATION_JSON_VALUE)
public class UserController extends BaseController {
    @Autowired
    private UserService userService;

    @ResponseBody
    @RequestMapping(method = RequestMethod.POST)
    public UserResponse signupUser(@RequestBody final UserSignupRequest userSignupRequest){
        UserResponse userResponse = this.userService.createUser(userSignupRequest, Role.ROLE_ANONYMOUS);
        URI location = this.buildLocationFromCurrentRequestUri(userResponse.getUsername());
        userResponse.setLocation(location);
        return userResponse;
    }

    @ResponseBody
    @RequestMapping(method = RequestMethod.GET, value = "/{username}")
    public UserResponse getMyUserDetails(@PathVariable String username) {
        UserResponse userResponse = this.userService.getUserByUsername(username);
        URI location = this.buildLocationFromCurrentServletMapping("user", userResponse.getUsername());
        userResponse.setLocation(location);
        return userResponse;
    }
}
This controllers defines to RESTful calls. 
  1. One to create a user
  2. Another to get that user by name
Both methods in this controller return UserResponse to their clients. signupUser()requires that the client of  to JSON representation of UserSignupRequest class (Curtesy of RequestBody annotation).

Define A User Service

import com.coffeebeans.domain.model.user.Role;
import com.coffeebeans.domain.request.user.UserSignupRequest;
import com.coffeebeans.domain.response.UserResponse;

/**
 * Created by muhamadto on 12/07/2015.
 */
public interface UserService {
    UserResponse createUser(final UserSignupRequest userSignupRequest, Role role);
    UserResponse getUserByUsername(String username);
}

and a class to implement this interface
package com.coffeebeans.service.user;

import com.coffeebeans.exception.general.NotFoundException;
import com.coffeebeans.repository.user.UserRepository;
import com.coffeebeans.domain.model.user.Role;
import com.coffeebeans.domain.model.user.User;
import com.coffeebeans.domain.request.user.UserSignupRequest;
import com.coffeebeans.domain.response.UserResponse;
import com.coffeebeans.exception.general.DuplicateEntryException;
import com.coffeebeans.service.base.BaseService;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.util.Date;

/**
 * Created by muhamadto on 12/07/2015.
 */

@Service("userService")
public class UserServiceImpl extends BaseService implements UserService{
    public static Logger LOGGER = LoggerFactory.getLogger(UserServiceImpl.class);

    @Autowired
    private UserRepository userRepository;

    @Override
    @Transactional
    public UserResponse createUser(UserSignupRequest userSignupRequest, Role role) {
        UserResponse newUser;

        final String email = userSignupRequest.getEmail().toLowerCase();
        if(this.userRepository.findByEmail(email) == null){
            LOGGER.info("User does not  exist - creating a new user [{}].", userSignupRequest.getUsername());

            User user = new User(userSignupRequest);
            user.setRole(role);
            Date now = new Date();

            user.setInsertDate(now);
            user.setLastModified(now);

            user = this.userRepository.save(user);

            newUser = UserResponse.convert(user);

            LOGGER.debug("Created new user [{}].", user);
        } else{
            LOGGER.error("Duplicate user located [{}], exception raised with appropriate HTTP response code.", email);
            throw new DuplicateEntryException("User already exists.");
        }
        return newUser;

    }

    @Override
    public UserResponse getUserByUsername(String username) {
        UserResponse userResponse;
        User user = this.userRepository.findByUsername(username);
        if(user != null){
            LOGGER.debug("User has been found [{}].", user);
            userResponse = UserResponse.convert(user);
        } else{
            LOGGER.error("Could not find a user for search criteria [{}]", username);
            throw new NotFoundException(String.format("Could not find a user for search criteria [username = %s]", username));
        }
        return userResponse;
    }
}
  • UserServiceImpl uses gets instance of UserRepository using dependancy injection. It uses this instance to save, update, and query UserUserRepository can be autowired no because of EnableJpaRepositories in PersistenceConfig class.

Exception Handling

As we saw in the UserServiceImpl, their are two exception:
  • createUser()  throws  com.coffeebeans.exception.general.DuplicateEntryException if the added user already exist 
  • getUserByUsername()  throws  com.coffeebeans.exception.general.NotFoundException if the username search did not find that user.
  • Both exceptions are subclasses from RuntimeException
package com.coffeebeans.exception.general;

/**
 * Created by mohamedhamtou on 26/01/15.
 */

public class NotFoundException extends RuntimeException {
    public NotFoundException(){
        super();
    }

    public NotFoundException(String message){
        super(message);
    }

    public NotFoundException(String message, Throwable cause) {
        super(message, cause);
    }
    public NotFoundException(Throwable cause) {
        super(cause);
    }

    protected NotFoundException(String message, Throwable cause,
                                boolean enableSuppression,
                                boolean writableStackTrace) {
        super(message, cause, enableSuppression, writableStackTrace);
    }
}

package com.coffeebeans.exception.general;

/**
 * Created by muhamadto on 12/07/2015.
 */
public class DuplicateEntryException extends RuntimeException {
    public DuplicateEntryException() {
        super();
    }

    public DuplicateEntryException(String message) {
        super(message);
    }

    public DuplicateEntryException(String message, Throwable cause) {
        super(message, cause);
    }

    public DuplicateEntryException(Throwable cause) {
        super(cause);
    }

    protected DuplicateEntryException(String message, Throwable cause,
                                      boolean enableSuppression,
                                      boolean writableStackTrace) {
        super(message, cause, enableSuppression, writableStackTrace);
    }
}
So how can we handle these, add the following methods to com.coffeebeans.controller.base.BaseController
  @ResponseBody
    @ExceptionHandler(DuplicateEntryException.class)
    @ResponseStatus(value = HttpStatus.CONFLICT)
    ErrorResponse handleException(DuplicateEntryException e){
        return new ErrorResponse(HttpStatus.CONFLICT.toString(), e.getMessage(), "Duplicated User");
    }

    @ResponseBody
    @ExceptionHandler(NotFoundException.class)
    @ResponseStatus(value = HttpStatus.NOT_FOUND)
    ErrorResponse handleException(NotFoundException e){
        return new ErrorResponse(HttpStatus.NOT_FOUND.toString(), e.getMessage(), "NOT FOUND (aka Huh?)");
    }
  • com.coffeebeans.api.error.ErrorResponse is a custom error class. The usefulness of this class will be clear once we start the JSR 303: Bean Validation lesson.
    • specific message such as throw new NotFoundException(String.format("Could not find a user for search criteria [username = %s]", username));
    • General message such as NOT FOUND (aka Huh?)
import lombok.Data;

import java.util.ArrayList;
import java.util.List;

/**
 * Created by muhamadto on 12/07/2015.
 */
@Data
public class ErrorResponse {

    private String errorCode;
    private String consumerMessage;
    private String applicationMessage;

    public ErrorResponse(){}

    public ErrorResponse(String errorCode, String consumerMessage,  String applicationMessage){
        this.errorCode = errorCode;
        this.consumerMessage = consumerMessage;
        this.applicationMessage = applicationMessage;
    }
}
Now run mvn clean install on the persistence module, then mvn clean package on Services module then depoly the war file in tomcat.


Using CURL To TEST

  • Signup user
    • Request:
      curl -H "Content-Type: application/json; charset=utf-8" --data '{"email":"post@domain.com","username":"example", "password":"password"}' http://localhost:8080/services/1/user
    • Response:
      {
          "location": "http://localhost:8080/services/1/user/example1"
          "enabled": false
          "verified": false
          "username": "example1"
          "email": "example1@domain.com"
      }
      
  • Retrieve User by Name
    • Request:
      curl http://localhost:8080/services/1/user/example1
    • Response:
      {
          "location": "http://localhost:8080/services/1/user/example1"
          "enabled": false
          "verified": false
          "username": "example1"
          "email": "example1@domain.com"
      }
The location property in the response is coming from the com.coffeebeans.domain.response.BaseResponse location property and been built through one of two methods in com.coffeebeans.controller.base.BaseController. These methods are:
    protected URI buildLocationFromCurrentRequestUri(String username){
        URI location = ServletUriComponentsBuilder.fromCurrentRequestUri().path("/").path(username).build().toUri();
        return location;
    }

    protected URI buildLocationFromCurrentServletMapping(String mapping, String username){
        URI location = ServletUriComponentsBuilder.fromCurrentServletMapping().path("/").path(mapping).path("/").path(username).build().toUri();
        return location;
    }
Now, we have a working RESTful web-services application that run Spring MVC and supports persistence using Spring Data JPA.

What is Next

Next post we will talk about bean validation.