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.

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.