REST Java Architecture

9:14 PM Dani 1 Comments

Having reached this point, we should be able to import the modules created previously into Eclipse (Version: Kepler Service Release 1) which will be the IDE used in this tutorial. First we need to create a workspace for the project. After the latter, we need to import the already created maven projects doing the following:

File -> Import -> Maven -> Existing Maven Projects


Upon project successful import, the explorer should look like the following screenshot:


Congratulations, if you have made it this far you should be able to actually begin with the development of the application!

4.- Adding RESTEasy to the application

And the project explorer should look like the following after having created the public service class:



Lastly, we need to test the service starting up the application in an application server (e,g: Apache Tomcat) and calling the service created previously as follows:

http://localhost:8080/creacodetive-api/api/public/Welcome%20to%20the%20REST%20World!

See below a brief description of what the URL is composed of:

- Server URL: http://localhost:8080
- Context of the Application to run: /creacodetive-api
- RESTEasy servlet mapping prefix: /api
- Resource Path: /public/{path_param}
    - {path_param} Content passed to the resource: Welcome%20to%20the%20REST%20World!

At this point we can now say that we've got RESTEasy integrated in our app.

Download the api module containing the RESTEasy framework here: creacodetive-api with RESTEasy or the whole project including RESTEasy here: RESTful Java App

5.- Creating the persistence layer - Mybatis

Mybatis will be the framework that will help us handle all the operations performed against the relational DB which in this tutorial will be MySQL. The reason why I have decided to use Mybatis is because of its seamless integration with Google Guice - dependency injection framework that we will be using and that will be covered in the next section.

For the sake of concreteness, I am not going to cover how to set up a MySQL instance locally on your computer. In this tutorial, we are going to assume that the reader has already installed a functional MySQL server.

First off we need to add the proper dependencies in order to be able to use Mybatis. Hance, let's get into it updating the pom.xml file inside the ORM module (creacodetive-orm) with the following:


Including these dependencies will allow us to be able to use the Object-Relational Mapping framework within our app as well as perform all kind of operations through the mysql driver. Nevertheless, some configuration work is still needed in order to be able to use Mybatis. Mybatis requires a configuration file (mybatis-config.xml) to be set thus it can figure out all the details about the DB and how to properly make the connection to the database.
Therefore, we need to create a mybatis-config.xml file under the build path src/main/resources. That's the location where Mybatis will expect to find the configuration file.


As you might have noticed, all the DB configuration values are coming from the properties file (jdbc.properties). This is really handy as it gives a lot of flexibility in case we wanted to have different configurations for different environments (dev, qa, pre-prod, etc). Note that the properties file must be located in the same directory as the mybatis-conf.xml file (as specified on the tag ), otherwise it won't be able to find it.


Having reached this point, your orm project should look like the screenshot below:


In order to use Mybatis in any service class (e,g: UserService.class) we must bind the configuration file (mybatis-config.xml) with Mybatis libraries beforehand. In this part of the tutorial, we have created a utils class containing the SQLSessionFactory using the Singleton pattern which restricts the instantiation of this class to just one object. This approach is rather convinient as calling the getSqlSessionFactory() method will always return the same instance of the SqlSessionFactory object. It should be noted though that this is a temporary solution since the creation of the instances will actually be handled by the DI framework Google Guice in the next section. However, this should be enough for now to give us an introductory understanding on how much power the DI framework can bring to the project and how it will take care of complex operations that would be hard to manage otherwise.

package com.creacodetive.utils;

import java.io.IOException;
import java.io.Reader;

import org.apache.ibatis.io.Resources;
import org.apache.ibatis.session.SqlSessionFactory;
import org.apache.ibatis.session.SqlSessionFactoryBuilder;

public class MyBatisUtil {

  private static SqlSessionFactory factory;

  private MyBatisUtil() {
  }

  static
  {
   Reader reader = null;
   try {
    reader = Resources.getResourceAsReader("mybatis-config.xml");
   } catch (IOException e) {
    throw new RuntimeException(e.getMessage());
   }
   factory = new SqlSessionFactoryBuilder().build(reader);
  }

  public static SqlSessionFactory getSqlSessionFactory() 
  {
   return factory;
  }
 
}

Mybatis Utils File (src/main/java/com/creacodetive/utils/MyBatisUtil.java) | creacodetive-orm
Congrats again! Your project is now able to connect to the DB and perform SQL operations. Mmhm wait a sec, we are not done yet. In order for that to be utterly true, we first need to actually test it! Since we already have RESTEasy working just fine, why don't we kill two birds with the same stone and test the whole work flow? With this I mean, calling a REST service end point (e,g: UserService) that will handle all the CRUD operations for the users. This way we will ensure that our orm-project is fully functional and will give us some hands-on experience on both REST and Mybatis.

First let's create the User.java business class inside the model project (creacodetive-model) which will be used by both Mybatis and RESTEasy. The former will utilize the User object-oriented domain model to map the entries in the relational database. Moreover, the User class will be used to persist data to the database without having to deal with JDBC code, manual setting of settings and retrieval of results. The latter (RESTEasy) will handle the tedious tasks of marshalling and un-marshalling of the different message bodies thus we can focus on other parts of the application.


With the User model object in place we can go ahead and create the corresponding mapping file and its mapper interface. Now I guess you must be wondering, how does Mybatis know where to find the object model class and the mapper?. Let's back up a bit to where we set up the Mybatis (mybatis-conf.xml) configuration. As you can notice, there are two different tags <typeAlias> (refering to the model location) and  <mapper> (refering to the mapper location) which are the ones letting Mybatis know where to find both the business object and the corresponding mapper.

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
  "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.creacodetive.mappers.UserMapper">

 <select id="getUserById" parametertype="int" resulttype="com.creacodetive.model.User">
  SELECT
  user_id as userId,
  email_id as emailId ,
  password,
  first_name as firstName,
  last_name as lastName
  FROM USER
  WHERE USER_ID = #{userId}
 </select>
 <!-- Instead of referencing Fully Qualified Class Names we can register 
  Aliases in mybatis-config.xml and use Alias names. -->
 <resultmap id="UserResult" type="User">
  <id column="user_id" property="userId">
  <result column="email_id" property="emailId">
  <result column="password" property="password">
  <result column="first_name" property="firstName">
  <result column="last_name" property="lastName">
 </result></result></result></result></id></resultmap>

 <select id="getAllUsers" resultmap="UserResult">
  SELECT * FROM USER
 </select>

 <insert id="insertUser" keyproperty="userId" parametertype="User" usegeneratedkeys="true">
  INSERT INTO USER(email_id, password, first_name, last_name)
  VALUES(#{emailId}, #{password}, #{firstName}, #{lastName})
 </insert>

 <update id="updateUser" parametertype="User">
  UPDATE USER
  SET
  PASSWORD= #{password},
  FIRST_NAME = #{firstName},
  LAST_NAME = #{lastName}
  WHERE USER_ID = #{userId}
 </update>

 <delete id="deleteUser" parametertype="int">
  DELETE FROM USER WHERE USER_ID = #{userId}
 </delete>

</mapper>

Mapper File (src/main/resources/com/creacodetive/mappers/UserMapper.xml) | creacodetive-orm
Following Mybatis specification, every mapper file should have its own associated mapper interface class as shown as follows. Note that for each operation in the mapper there is a function in the interface that captures the functionality.

package com.creacodetive.mappers;

import java.util.List;

import com.creacodetive.model.User;

public interface UserMapper {

  public void insertUser(User user);

  public User getUserById(Integer userId);

  public List getAllUsers();

  public void updateUser(User user);

  public void deleteUser(Integer userId);
 
}

Mapper Interface File (src/main/java/com/creacodetive/mappers/UserMapper.java)  | creacodetive-orm
Great, at this stage we have all what we need to give the user service a shot and test whether all the pieces work together. Nevertheless before doing it so, we have to slightly adjust the pom file inside the creacodetive-api project to include the orm and module dependencies. Otherwise, we will not be able to use the model and orm projects.

<!-- Creacodetive dependendies -->
  <dependency>
   <groupId>com.creacodetive</groupId>
   <artifactId>creacodetive-model</artifactId>
   <version>${project.version}</version>
  </dependency>
  <dependency>
   <groupId>com.creacodetive</groupId>
   <artifactId>creacodetive-orm</artifactId>
   <version>${project.version}</version>
  </dependency>

Furthermore, the User service containing all the JAX-RS CRUD operations still needs to be implemented:

package com.creacodetive.mappers;
package com.creacodetive.api.services;

import java.util.List;

import javax.ws.rs.Consumes;
import javax.ws.rs.DELETE;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;

import org.apache.ibatis.session.SqlSession;

import com.creacodetive.mappers.UserMapper;
import com.creacodetive.model.User;
import com.creacodetive.utils.MyBatisUtil;

/**
 * 
 * CRUD Operations:
 *  - Create - POST
 *  - Read - GET
 *  - Update - POST
 *  - Delete - DELETE
 * @author dikhanr
 *
 */
@Path("/users")
public class UserService {

 /**
  * @param user
  */
 @PUT
 @Consumes("application/json")
 public void insertUser(User user) 
 {
  SqlSession sqlSession = MyBatisUtil.getSqlSessionFactory()
    .openSession();
  try {
   UserMapper userMapper = sqlSession.getMapper(UserMapper.class);
   userMapper.insertUser(user);
   sqlSession.commit();
  } finally {
   sqlSession.close();
  }
 }
 
 /**
  * @param userId
  * @return
  */
 @GET
 @Produces("application/json")
 @Path("/{userId}")
 public User getUserById(@PathParam("userId") Integer userId) 
 {
  SqlSession sqlSession = MyBatisUtil.getSqlSessionFactory()
    .openSession();
  try {
   UserMapper userMapper = sqlSession.getMapper(UserMapper.class);
   return userMapper.getUserById(userId);
  } finally {
   sqlSession.close();
  }
 }

 /**
  * @return
  */
 @GET
 @Produces
 public List getAllUsers() 
 {
  SqlSession sqlSession = MyBatisUtil.getSqlSessionFactory()
    .openSession();
  try {
   UserMapper userMapper = sqlSession.getMapper(UserMapper.class);
   return userMapper.getAllUsers();
  } finally {
   sqlSession.close();
  }
 }

 /**
  * @param userId
  * @param user
  */
 @POST
 @Consumes("application/json")
 @Path("/{userId}") //@NotNull @NotEmpty
 public void updateUser(@PathParam("userId") Integer userId, User user) 
 {
  SqlSession sqlSession = MyBatisUtil.getSqlSessionFactory()
    .openSession();
  try {
   UserMapper userMapper = sqlSession.getMapper(UserMapper.class);

   userMapper.setUserId(userId);
userMapper.updateUser(user);
   sqlSession.commit();
  } finally {
   sqlSession.close();
  }
 }

 /**
  * @param userId
  */
 @DELETE
 @Consumes("application/json")
 @Path("/{userId}")
 public void deleteUser(@PathParam("userId") Integer userId) 
 {
  SqlSession sqlSession = MyBatisUtil.getSqlSessionFactory()
    .openSession();
  try {
   UserMapper userMapper = sqlSession.getMapper(UserMapper.class);
   userMapper.deleteUser(userId);
   sqlSession.commit();
  } finally {
   sqlSession.close();
  }
 }
}

User Service class (src/main/java/com/creacodetive/api/services/UserService.java) | creacodetive-api
The moment of the truth has arrived and therefore let's do some smoke testing so as to check that the REST services implemented above are working as expected. I usually work with Advance REST Client, an extension for chrome, which comes in really handy when testing http requests and analysing the responses.
Important Note: Prior to starting calling the end points make sure that the project creacodetive-api is up and running under Tomcat and that the MySQL service is running as well.

Test 1: Creating a new user
           
       HTTP Method: PUT
       URL: http://localhost:8080/creacodetive-api/api/users
       Body Payload:
       {
              "emailId":"dikhan@creacotive.com",
              "password":"password01!",
              "firstName":"Daniel Isaac",
              "lastName":"Khan Ramiro"
       }
       Content-Type: application/json
       Response Status 204 No Content

Test 2: Retrieving a user by ID

       HTTP Method: GET
       URL: http://localhost:8080/creacodetive-api/api/users/1
       Response Status 200 OK

Test 3: Retrieving all the users

       HTTP Method: GET
       URL: http://localhost:8080/creacodetive-api/api/users
       Response Status 200 OK

Test 4: Updating existing user by ID

       HTTP Method: POST
       URL: http://localhost:8080/creacodetive-api/api/users/1
       Body Payload:
       {
               "emailId":"dikhan@creacotive.com",
               "password":"passwordsecret",
               "firstName":"Daniel",
               "lastName":"Khan"
       }
       Content-Type: application/json
       Response Status 204 No Content
Test 5: Deleting user by ID

       HTTP Method: DELETE
       URL: http://localhost:8080/creacodetive-api/api/users/1
       Response Status 204 No Content

Download the whole project including the new orm and module projects here.

6.- Adding the DI framework - Google Guice