Sunit Katkar's blog

Setting up Keycloak 10 with MySQL 8 on your Windows machine

noreply@blogger.com (Sunit) — Mon, 06 Jul 2020 01:23:00 +0000

Keycloak is a very good Identity and Access Management solution from Red Hat. It is open-source and works straight out of the box on most operating systems, including Windows. Keycloak allows you to secure your applications and services with the best in class security measures like OpenID, OAuth2, et-al. Please refer to the official site for more details.

I have started using it as the standard for all application security and user management needs. I will share my experiences of using Keycloak to secure Spring Boot traditional MVC apps as well as microservices in a future series of posts.

Purpose of this blog post

There are many good resources on setting up Keycloak on your local machine and in the cloud. The official documentation is a good place to start.

This blog post is NOT about setting up Keycloak to serve as a full fledged Identity and Access Management solution but about setting up an external database for Keycloak to store its data and the realms, users, roles, credentials, etc created by you.

Keycloak comes with a built-in in-memory H2 database out of the box. This is good for getting started with Keycloak on your development machine, but not recommended for using in a production environment. This blog post is about using a database like MySQL (version 8) as the Keycloak database instead of the default in-memory H2 database. Once you understand how it is done, then you can do the same on your production server.

One small note - I am sharing my experiences and success on Windows and so this blog post will show how it is done on Windows. I am sure the same steps can be replicated after adjusting for other operating systems to achieve the same.

Problems when setting up on Windows 10

I use Windows as my development machine and I came across many errors and failed to set up KeyCloak with MySQL on my Windows machine at first go, despite following the official documentation and some blog posts. This is my attempt to record this here so that it might be useful to some of you who face problems setting up on Windows.

Here is a small subset of the issues I faced -

Basically Keycloak was able to connect with a local Postgresql database but not with a MySQL database. So after lot of searching and trying things on my own, borrowing from my experience, I was able to make it all work. I noted down the steps I performed. Now I am sharing them so that you can save time if you face similar issues.

Versions used in this blog post

Keycloak 10.0.2 - Download
- Follow the official guide to setup the server. I have installed it to D:\keycloak on my Windows machine.
MySQL Community Server 8.0.20 - Download
- Follow the official guide to setup the database server. I have used WampServer to install MySQL versions 5 and 8 on my Windows machine. Details in the next section.
MySQL Connector for Java (Connector/J) - Download
- This is needed for Keycloak to talk to the MySQL database. I have downloaded the latest Platform Independent version mysql-connector-java-8.0.20.jar
- Extract and place this jar file in a convenient location for adding it to the module as explained in later sections. I have placed it in D:\ on my Windows machine.

Useful tools

Though I prefer the command line for many tasks, sometimes a GUI tool helps getting things done quicker. I use the following tools. You don't have to use the same or use such tools at all.

HeidiSQL - Database Management GUI tool - Download
- This is a free open-source tool, actively maintained and released with new features and bug fixes, which I find very useful.
WampServer - Download from an aletrnative site which has more related options and tools
- This is a free open-source tool which installs the MySQL, Apache HTTP server and PHP stack - LAMP stack on your Windows machine. It also allows you to have multiple versions of MySQL on your machine as some of your projects might still be on legacy MySQL version 5.7.x

Assumptions

I am assuming that you have installed Keycloak and MySQL. You have configured them enough to be operational as intended. Please go through the official documentation of each to setup and configure just enough. I will show you how the Connector/J comes into the picture further down.

Basic Steps

Keycloak uses the JBoss Wildfly server under the hood. If you know how to use the JBoss/Wildfly CLI and add a datasource to Wildfly, then you might not need to follow all the steps shown here.

Here are the basic steps for configuring your MySQL database as the Keycloak database.

Create a MySQL database, say, keycloakdb with a user, say, keycloakadmin in your MySQL and grant all privileges to this user
Add a module to the Keycloak (Wildfly) server defining your MySQL database and define a datasource along with the database driver (Connector/J), database user credentials, etc.
Restart your Keycloak server

I will detail every step next.

Using JBoss/Wildfly CLI

The official documentation shows the files in Keycloak that you need to edit to configure your database. I have found that manually editing the files can sometimes lead to a problem. I could not pin point the exact reason when I tried, but being a newbie with Wildfly, I realized that using the CLI is a much better way to achieve these steps. Using the CLI works; and you don't have to troubleshoot if your configuration did not work as intended.

Step 1: Create a database in MySQL

Using the MySQL shell (or a GUI tool) create a database in MySQL with the utf8 character set and the collation as utf8_unicode_ci. This is important as Keycloak requires UTF8 (for a few columns) and the official documentation states so here.

CREATE DATABASE keycloakdb CHARACTER SET utf8 COLLATE utf8_unicode_ci;

Step 2: Create a database user for Keycloak

Now you need to create a user and grant privileges. Follow these commands if you are using the MySQL command line (and not a GUI tool). Note that I have used a simple password which is not secure. On production systems, the passwords need to be very secure with features like upper and lower case characters, special characters, numbers, etc. For purpose of this blog post, a simple password is good enough.

CREATE USER 'keycloakadmin'@'%' IDENTIFIED WITH mysql_native_password BY 'keycloak123';

Why use `mysql_native_password` when creating a user?

From MySQL 8.0.x, caching_sha2_password is the default authentication plugin. Upto MySQL 5.x the default authentication plugin was mysql_native_password. Since a development environment, like mine, has two different versions of MySQL to support some legacy projects, I recommend using the older mysql_native_password authentication plugin. If you are just using the latest MySQL 8 for all your development, then you need not use the mysql_native_password keyword in the SQL command shown above.

Step 3: Grant all privileges

You can fine tune the privileges later by reading the Keycloak documentation in detail or talking to your DBA, but for setting up the Keycloak database user, just grant all privileges initially. As far as I know, I am sure that the database user requires all privileges.

GRANT ALL PRIVILEGES ON keycloakdb.* TO 'keycloakadmin'@'%';
--- Tell the server to reload the grant tables
--- by performing a flush privileges operation
FLUSH PRIVILEGES;

Step 4: Ensure that your databse engine is InnoDB

MySQL has several database storage engines with MyISAM and InnoDB being the most prominent. There are many reasons to use one over the other, but that discussion is beyond the scope of this blog post. After reading a lot about this topic, like the documentation for Keycloak and MySQL 8, I found that for the Keycloak database, MySQL 8 storage engine should be set to InnoDB, if it is not set already.

You can check the storage engine by following the MySQL documentation or by using MySQL commands like the following -

--- Should output: default_storage_engine InnoDB
SHOW GLOBAL variables like "default_storage%"

--- If storage engine is not InnoDB, use this to set it
SET GLOBAL default_storage_engine = 'InnoDB';

Step 5: Adding a module with the MySQL driver (Connector/J) to Keycloak

This is about telling Keycloak the database connector/driver you will be using to connect Keycloak to your MySQL database. As I said earlier, I have realized that using the JBoss/Wildfly CLI is the optimal way to configure Keycloak. So I will show you how to add a module using the CLI.

You need to run the Keycloak server so that the JBoss/Wildfly CLI tool can connect to the running server and further actions can be performed.

From the /bin directory of your keycloak installation, run the standalone.bat batch file.

Your command/console window should now show you the regular Keycloak messages and indicate that the server is running.

Start another command prompt.

From the /bin directory of your keycloak installation, run the jboss-cli.bat batch file.

Now enter the connect command to connect to the Keycloak server.

Now enter the following command on the console. Note that the command is all in one line. If it is showing up in multiple lines, then it is because of the responsive design and layout of this blog post.

module add --name=com.mysql --dependencies=javax.api,javax.transaction.api --resources=D:/mysql-connector-java-8.0.20.jar --module-root-dir=../modules/system/layers/keycloak/

What did this `module add` command do?

The above command created a directory structure inside your {Keycloak-Directory}\modules\system\layers\keycloak/ directory and added a module.xml file. After executing the module add command you should see a module file at D:\keycloak\keycloak-10.0.2\modules\system\layers\keycloak\com\mysql\main\module.xml

The module.xml file looks like the XML snippet below. Notice that the connector jar has also been copied inside this newly created directory by this command. So now Keycloak knows the definition of your database connector and the location of the jar file too.

<?xml version='1.0' encoding='UTF-8'?>

<module xmlns="urn:jboss:module:1.1" name="com.mysql">

    <resources>
        <resource-root path="mysql-connector-java-8.0.20.jar"/>
    </resources>

    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
</module>

Step 6: Defining a data source

Now that Keycloak knows about the database connector through its modules, its time to actually define a data source. This will allow Keycloak to connect to your MySQL database instead of the built-in H2 database.

First, go to your {Keycloak-Directory}\standalone\configuration\ and open the standalone.xml file in your text editor.
Search for the word KeycloakDS and you should see a section defining a data source and database driver for the default H2 database the XML snippet below.
You need to do two things - replace the KeycloakDS data source and the database connection driver defined for H2 with your MySQL database.

<datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" 
    use-java-context="true" 
    statistics-enabled="${wildfly.datasources.statistics-enabled:${wildfly.statistics-enabled:false}}">
  <connection-url>jdbc:h2:${jboss.server.data.dir}/keycloak;AUTO_SERVER=TRUE</connection-url>
  <driver>h2</driver>
  <security>
    <user-name>sa</user-name>
    <password>sa</password>
  </security>
</datasource>
<drivers>
  <driver name="h2" module="com.h2database.h2">
    <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
  </driver>
</drivers>

The above two tasks can be achieved using the CLI (and I recommend this versus manually editing the configuration in standalone.xml)

Remove the existing datasource

Enter the following command in the console to first remove the KeycloakDS

/subsystem=datasources/data-source=KeycloakDS:remove

You should see console messages indicating success, like in the screen shot below.

Define your MySQL based driver and data source

Enter the following command in the console to define the MySQL driver

/subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-class-name=com.mysql.cj.jdbc.Driver)

You should see console messages indicating success, like in the screen shot below.

Enter the following command in the console to define the MySQL data source

data-source add --name=KeycloakDS --jndi-name=java:jboss/datasources/KeycloakDS --enabled=true --password=keycloak123 --user-name=keycloakadmin --driver-name=com.mysql --use-java-context=true --connection-url=jdbc:mysql://localhost:3306/keycloakdb?useSSL=false&characterEncoding=UTF-8

You should see console messages indicating success, like in the screen shot below.

If you take a quick look at your standalone.xml file, your data source should now look like the XML snippet below

<datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true">
    <connection-url>jdbc:mysql://localhost:3306/keycloakdb?useSSL=false&amp;characterEncoding=UTF-8</connection-url>
    <driver>com.mysql</driver>
    <security>
        <user-name>keycloakadmin</user-name>
        <password>keycloak123</password>
    </security>
</datasource>
<drivers>
    <driver name="h2" module="com.h2database.h2">
        <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
    </driver>
    <driver name="com.mysql" module="com.mysql">
        <driver-class>com.mysql.cj.jdbc.Driver</driver-class>
    </driver>
</drivers>

There is much more you can do to the datasource configuration like add connection pooling, connection validators, exception handlers, etc. I have not covered all these options as the purpose is to get MySQL connected as the Keycloak database for a development environment. Detailed official documentation about Wildfly server and data sources is available here.
For example, you can manually add connection pooling to the data source configuration (or use the JBoss/Wildfly CLI options) like the XML snippet below.

...
<driver>com.mysql</driver>
    <pool>
        <min-pool-size>4</min-pool-size>
        <initial-pool-size>4</initial-pool-size>
        <max-pool-size>64</max-pool-size>
    </pool>
    <security>
...

You can add some validators to your data source like the XML snippet below.

...
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
  </validation> 
</datasource>
...

About the character encoding parameter in the jdbc connection url

Please note that Keycloak requires that your database be capable of storing data in UTF8 format. Similarly, the connection url also needs to specify that the connection can handle UTF8 data. More details in the official guide here.

Test your database connection

After the above two steps you should test if Keycloak can reach your database.

Enter the following command in the console to test database connectivity

/subsystem=datasources/data-source=KeycloakDS:test-connection-in-pool

You should see console messages indicating success, like in the screen shot below.

Step 7: Database configuration

You are near the very end of your configuration, but please understand the following. Keycloak allows you to customize code and configuration via their SPI or Service Provider Interface facility. For the database configuration it means ensuring that some of the parameters are set properly for Keycloak to create the required tables and apply required constraints in the keycloakdb database in your MySQL.

Open the standalone.xml file once again in your text editor and search for connectionsJpa
You should see configuration like the XML snippet below

<spi name="connectionsJpa">
  <provider name="default" enabled="true">
    <properties>
      <property name="dataSource" value="java:jboss/datasources/KeycloakDS"/>
      <property name="initializeEmpty" value="true"/>
      <property name="migrationStrategy" value="update"/>
      <property name="migrationExport" value="${jboss.home.dir}/keycloak-database-update.sql"/>
    </properties>
  </provider>
</spi>

This section is about telling Keycloak if you want your MySQL database to be initialized for you. Remember that Keycloak uses JPA too for connecting to your database. So the underlying provider is Hibernate. If you have ever worked with Hibernate then you know about configurations like ddl-auto. These configuration parameters are something similar. Please refer to the official documentation here for more details.

Step 8: Restarting Keycloak server

Note that Keycloak was started for configuring MySQL but its administrative UI was not accesssed nor was an administrator user added to it. It is not mandatory, but I prefer adding an intial admin user to Keycloak in the master realm. You can add a admin user via the Keycloak Admin Console UI or via the Keycloak CLI.
Enter the following command from the /bin directory to add a Keycloak user to the master realm.

add-user-keycloak.bat -u superadmin -p superadmin -r master

You are almost done! You need to restart Keycloak so that when it boots up, it will now use the KeycloakDS data source and connect with your MySQL database. This will also allow you to check the tables and constraints added by Keycloak to your database.

Checking Keycloak log messages to see that MySQL connectivity is working as expected

Once you restart the Keycloak server, you can check the log messages. You should see messages like the following, indicating success.

...
[org.jboss.as.connector.subsystems.datasources] (ServerService Thread Pool -- 32) WFLYJCA0005: Deploying non-JDBC-compliant driver class com.mysql.cj.jdbc.Driver (version 8.0)
...
org.jboss.as.connector.deployers.jdbc] (MSC service thread 1-3) WFLYJCA0018: Started Driver service with driver-name = com.mysql
...
[org.hibernate.jpa.internal.util.LogHelper] (ServerService Thread Pool -- 59) HHH000204: Processing PersistenceUnitInfo [
        name: keycloak-default
        ...]
...

About the log message - Deploying non-JDBC-compliant driver class com.mysql.cj.jdbc.Driver

Do not worry about that message. Your configuration will work despite this message. It is a known bug. Please see this.
The simple explanation for this message is that the JDBC driver must have SQL support conforming to the entry level of the SQL92 standard. Unfortunately, MySQL does not support all features that are required by that standard. So JBoss/Wildfly just reports that the driver is not fully compliant. It does not affect the working of your MySQL as the Keycloak database.

Wrapping up

You are now ready to use your MySQL database as the Keycloak data store. I have shown how to configure this on a Windows machine for development purpose. In a real life production scenario, you will probably not run a standalone instance of Keycloak; but most likely clustered mode. Please refer to the official documentation about operating modes.These techniques I have shared will be applicable to those configurations too.

Happy Keycloak-ing! :)

Spring Boot 2 + Thymeleaf - Versioning static assets for client side cache busting

noreply@blogger.com (Sunit) — Tue, 11 Sep 2018 20:10:00 +0000

In a post written some time ago, I showed how you can prevent caching of static resources (javascript and css) in a legacy Spring MVC application. Recently I needed to use the same technique to prevent browser side caching of javascript and css files in a Spring Boot 2 project using Thymeleaf as the view layer.

Purpose of this blog post

This blog post is about sharing a simple way to make your Spring Boot application serve versioned static resources like javascript and css files so that client side caching can be overcome when your static resources change.
Typically browsers download javascript and css files and then refer to them from the local cache. This is okay as long as you do not change the contents of your files. If you do make changes but you keep the same name then the browser will not know about the changes and use the same version from its local cache. Some approaches to defeat the cache are to add add a distinguishing query parameter (like myfile.css?v=1.1) or placing the files in a new subdirectory (like /js/v2/myfile.js) and then updating all the places in the HTML files where these are included. This is tedious and error prone to manually update the version query parameter or rename the file location in all the pages that it is included.

Fortunately Spring allows us to take care of this with minimal effort. Let us see how.

What is used to build the example in this blog post?

This example applies to a Spring Boot 2 application with Thymeleaf as the view layer. I am assuming that you have a standard Spring Boot 2 app with Thymeleaf. I am sure that this can be adapted to any other view technologies barring one as mentioned in the note below.

Before you start, I recommend you refer to the official documentation about serving static resources for further clarity.

Please note that if you are using Spring WebFlux then you cannot use this approach. See the official documentation here for more details.

Step 1: Adding entries to your application.properties (or application.yml) file

You need to add the following three entries in your application.properties file. What these mean is explained very clearly on the Spring documentation here in the Spring Resources Handling section.

File: application.properties

#########################################################
#Adding ResourceUrlEncodingFilter i.e. to version static 
#js and css files to prevent caching by browser
#########################################################

#Whether to enable the Spring Resource Handling chain. 
#By default, disabled unless at least one strategy has 
#been enabled.
spring.resources.chain.enabled=true

# Whether to enable the content Version Strategy.
spring.resources.chain.strategy.content.enabled=true

#Comma-separated list of patterns to apply to the content 
#Version Strategy i.e. where are your js and css files
spring.resources.chain.strategy.content.paths=/js/**,/css/**

Step 2: Define a ResourceUrlEncodingFilter bean

You need to create a ResourceUrlEncodingFilter bean and register it in your application's filter chain. With Spring Boot, it is very simple. Just create a MVC configuration and instantiate the bean there. For example, the following is all you need.

File: CacheBusterMVCConfig.java

@Component
public class CacheBusterMVCConfig implements WebMvcConfigurer {

    /**
     * Define the ResourceUrlEncodingFilter as a bean. 
     * Add the <code>@ConditionalOnEnabledResourceChain</code> 
     * to ensure that the resource chain property 
     * <code>spring.resources.chain.enabled=true</code> 
     * is set to true in the <code>application.properties</code> file.
     * 
     * @return
     */
    @Bean
    @ConditionalOnEnabledResourceChain
    public ResourceUrlEncodingFilter resourceUrlEncodingFilter() {
        return new ResourceUrlEncodingFilter();
    }
}

Results

If you download and run the project, you should see the screen as shown below.

Resources

The example project has been uploaded to Github here. If you like it, please star my repo.

Happy coding :)

Adding tenants without application restart in SaaS style multi-tenant web app with Spring Boot 2 and Spring Security 5

noreply@blogger.com (Sunit) — Fri, 25 May 2018 22:56:00 +0000

In my previous posts (part 1, part 2) about Saas style multi-tenant web applications, the focus was on how multi-tenancy is achieved. In this post I will share how tenants can be added without restarting the application.

Update 4th Sep 2018

Many readers of this blog post have emailed me saying that they run the code but cannot login. This is because they have not populated the user table with username and password for a user nor have they created the necessary databases and schema. In many cases, the readers are not familiar with Spring Security. I request that you please read up on Spring Security first. Here is an excellent example from the official Spring documentation site.

Purpose of this blog post

In my previous posts, I showed how to read the details of the tenant databases from the application.yml file. The focus was on how to set up SaaS style database per tenant multitenancy.

In this post, I will show you how you can add the tenant information in a separate 'master' database and the multi-tenant application will pick up the existing tenants and any tenant added while your application is running. If you were to add a new tenant in the application.yml file, then you would have to restart the application. With the technique I am about to describe, you do not need to restart your application.

Structure of the application

In the previous posts, the application learnt about the tenants from the application.yml file. In this post, the tenant information is not learnt from the application.yml file but from a separate table in the master database.

The application.yml file is still required for application related properties and values, but the tenant database information need not be stored in it.

Datasources - One for the master database and one each for every tenant

The tenant information will be stord in the master database. For example, if the master database is called 'masterdb' and the table for tenant information is called 'master_tenant', then the information might look like this:

It is a simple table with the datasource related information about each tenant, like url, username, password, etc.

Order of setting up datasources and entity managers

It is important how the data sources are set up. Earlier, the tenant information was from the application.yml file. So the only datasources being setup were for each tenant.

The datasource for the 'master_tenant' table needs to be setup first as this table contains the tenant information. Once this datasource is set up, it can be used to read the tenant information and set up a datasource per tenant.

Please pay attention to the package structures. The master and tenant related datasource configurations are kept in separate packages and the master datasource is set up first.

The following source code listings show the way this is done.

File: MasterDatabaseConfig.java

This sets up the master datasource to connect to the masterdb database.

package com.sunitkatkar.blogspot.master.config;

import java.util.Properties;

import javax.persistence.EntityManagerFactory;
import javax.sql.DataSource;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.dao.annotation.
        PersistenceExceptionTranslationPostProcessor;
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.annotation.
        EnableTransactionManagement;

import com.sunitkatkar.blogspot.master.model.MasterTenant;
import com.sunitkatkar.blogspot.master.repository.
        MasterTenantRepository;
import com.zaxxer.hikari.HikariDataSource;

/**
 * Configuration of the master database which holds information about tenants in
 * the application.
 * 
 * @author Sunit Katkar, sunitkatkar@gmail.com
 *         (https://sunitkatkar.blogspot.com/)
 * @since ver 1.0 (May 2018)
 * @version 1.0
 */
@Configuration
@EnableTransactionManagement
@EnableJpaRepositories(basePackages = { "com.sunitkatkar.blogspot.master.model",
                                 "com.sunitkatkar.blogspot.master.repository" }, 
                       entityManagerFactoryRef = "masterEntityManagerFactory", 
                       transactionManagerRef = "masterTransactionManager")
public class MasterDatabaseConfig {

    private static final Logger LOG = LoggerFactory
            .getLogger(MasterDatabaseConfig.class);

    /**
     * Master database configuration properties like username, password, etc.
     */
    @Autowired
    private MasterDatabaseConfigProperties masterDbProperties;

    /**
     * Creates the master datasource bean which is required for creating the
     * entity manager factory bean <br/>
     * <br/>
     * Note that using names for beans is not mandatory but it is a good
     * practice to ensure that the intended beans are being used where required.
     * 
     * @return
     */
    @Bean(name = "masterDataSource")
    public DataSource masterDataSource() {

        LOG.info("Setting up masterDataSource with: "
                + masterDbProperties.toString());

        HikariDataSource ds = new HikariDataSource();

        ds.setUsername(masterDbProperties.getUsername());
        ds.setPassword(masterDbProperties.getPassword());
        ds.setJdbcUrl(masterDbProperties.getUrl());
        ds.setDriverClassName(masterDbProperties.getDriverClassName());
        ds.setPoolName(masterDbProperties.getPoolName());

        // HikariCP settings
        // Maximum number of actual connection in the pool
        ds.setMaximumPoolSize(masterDbProperties.getMaxPoolSize());

        // Minimum number of idle connections in the pool
        ds.setMinimumIdle(masterDbProperties.getMinIdle());

        // Maximum waiting time for a connection from the pool
        ds.setConnectionTimeout(masterDbProperties.getConnectionTimeout());

        // Maximum time that a connection is allowed to sit idle in the pool
        ds.setIdleTimeout(masterDbProperties.getIdleTimeout());
        LOG.info("Setup of masterDataSource succeeded.");
        return ds;
    }

    /**
     * Creates the entity manager factory bean which is required to access the
     * JPA functionalities provided by the JPA persistence provider, i.e.
     * Hibernate in this case. <br/>
     * <br/>
     * Note the <b>{@literal @}Primary</b> annotation which tells Spring boot to
     * create this entity manager as the first thing when starting the
     * application.
     * 
     * @return
     */
    @Primary
    @Bean(name = "masterEntityManagerFactory")
    public LocalContainerEntityManagerFactoryBean masterEntityManagerFactory(){
        LocalContainerEntityManagerFactoryBean em = 
                new LocalContainerEntityManagerFactoryBean();

        // Set the master data source
        em.setDataSource(masterDataSource());

        // The master tenant entity and repository need to be scanned
        em.setPackagesToScan(
                new String[]{MasterTenant.class.getPackage().getName(),
                        MasterTenantRepository.class.getPackage().getName()});
        // Setting a name for the persistence unit as Spring sets it as
        // 'default' if not defined
        em.setPersistenceUnitName("masterdb-persistence-unit");

        // Setting Hibernate as the JPA provider
        JpaVendorAdapter vendorAdapter = new HibernateJpaVendorAdapter();
        em.setJpaVendorAdapter(vendorAdapter);

        // Set the hibernate properties
        em.setJpaProperties(hibernateProperties());
        LOG.info("Setup of masterEntityManagerFactory succeeded.");
        return em;
    }

    /**
     * This transaction manager is appropriate for applications that use a
     * single JPA EntityManagerFactory for transactional data access. <br/>
     * <br/>
     * Note the <b>{@literal @}Qualifier</b> annotation to ensure that the
     * <tt>masterEntityManagerFactory</tt> is used for setting up the
     * transaction manager.
     * 
     * @param emf
     * @return
     */
    @Bean(name = "masterTransactionManager")
    public JpaTransactionManager masterTransactionManager(
            @Qualifier("masterEntityManagerFactory") EntityManagerFactory emf) {
        JpaTransactionManager transactionManager = new JpaTransactionManager();
        transactionManager.setEntityManagerFactory(emf);
        return transactionManager;
    }

    /**
     * Bean post-processor that automatically applies persistence exception
     * translation to any bean marked with Spring's @Repository annotation,
     * adding a corresponding PersistenceExceptionTranslationAdvisor to the
     * exposed proxy (either an existing AOP proxy or a newly generated proxy
     * that implements all of the target's interfaces).
     * 
     * @return
     */
    @Bean
    public PersistenceExceptionTranslationPostProcessor exceptionTranslation() {
        return new PersistenceExceptionTranslationPostProcessor();
    }

    /**
     * The properties for configuring the JPA provider Hibernate.
     * 
     * @return
     */
    private Properties hibernateProperties() {
        Properties properties = new Properties();
        properties.put(org.hibernate.cfg.Environment.DIALECT,
                "org.hibernate.dialect.MySQL5Dialect");
        properties.put(org.hibernate.cfg.Environment.SHOW_SQL, true);
        properties.put(org.hibernate.cfg.Environment.FORMAT_SQL, true);
        properties.put(org.hibernate.cfg.Environment.HBM2DDL_AUTO, "update");
        return properties;
    }
}

File: TenantDatabaseConfig.java

This class sets up the datasources for the tenant databases. Note that this class requires the 'MultiTenantConnectionProvider' for the tenant datasources. These datasources are configured in the 'DataSourceBasedMultiTenantConnectionProviderImpl' class, shown later on in this post.

package com.sunitkatkar.blogspot.tenant.config;

import java.util.HashMap;
import java.util.Map;

import javax.persistence.EntityManagerFactory;

import org.hibernate.MultiTenancyStrategy;
import org.hibernate.context.spi.CurrentTenantIdentifierResolver;
import org.hibernate.engine.jdbc.connections.spi.MultiTenantConnectionProvider;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import org.springframework.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.annotation.EnableTransactionManagement;

import com.sunitkatkar.blogspot.tenant.model.User;
import com.sunitkatkar.blogspot.tenant.repository.UserRepository;
import com.sunitkatkar.blogspot.tenant.service.UserService;

/**
 * This is the tenant data sources configuration which sets up the multitenancy.
 * 
 * @author Sunit Katkar, sunitkatkar@gmail.com
 *         (https://sunitkatkar.blogspot.com/)
 * @since ver 1.0 (May 2018)
 * @version 1.0
 */
@Configuration
@EnableTransactionManagement
@ComponentScan(basePackages = { "com.sunitkatkar.blogspot.tenant.repository",
        "com.sunitkatkar.blogspot.tenant.model" })
@EnableJpaRepositories(basePackages = {
        "com.sunitkatkar.blogspot.tenant.repository",
        "com.sunitkatkar.blogspot.tenant.service" }, 
        entityManagerFactoryRef = "tenantEntityManagerFactory", 
        transactionManagerRef = "tenantTransactionManager")
public class TenantDatabaseConfig {

    private static final Logger LOG = LoggerFactory
            .getLogger(TenantDatabaseConfig.class);


    @Bean(name = "tenantJpaVendorAdapter")
    public JpaVendorAdapter jpaVendorAdapter() {
        return new HibernateJpaVendorAdapter();
    }

    @Bean(name = "tenantTransactionManager")
    public JpaTransactionManager transactionManager(
            EntityManagerFactory tenantEntityManager) {
        JpaTransactionManager transactionManager = new JpaTransactionManager();
        transactionManager.setEntityManagerFactory(tenantEntityManager);
        return transactionManager;
    }

    /**
     * The multi tenant connection provider
     * 
     * @return
     */
    @Bean(name = "datasourceBasedMultitenantConnectionProvider")
    @ConditionalOnBean(name = "masterEntityManagerFactory")
    public MultiTenantConnectionProvider multiTenantConnectionProvider() {
        // Autowires the multi connection provider
        return new DataSourceBasedMultiTenantConnectionProviderImpl();
    }

    /**
     * The current tenant identifier resolver
     * 
     * @return
     */
    @Bean(name = "currentTenantIdentifierResolver")
    public CurrentTenantIdentifierResolver currentTenantIdentifierResolver() {
        return new CurrentTenantIdentifierResolverImpl();
    }

    /**
     * Creates the entity manager factory bean which is required to access the
     * JPA functionalities provided by the JPA persistence provider, i.e.
     * Hibernate in this case.
     * 
     * @param connectionProvider
     * @param tenantResolver
     * @return
     */
    @Bean(name = "tenantEntityManagerFactory")
    @ConditionalOnBean(name = "datasourceBasedMultitenantConnectionProvider")
    public LocalContainerEntityManagerFactoryBean entityManagerFactory(
            @Qualifier("datasourceBasedMultitenantConnectionProvider") 
            MultiTenantConnectionProvider connectionProvider,
            @Qualifier("currentTenantIdentifierResolver") 
            CurrentTenantIdentifierResolver tenantResolver) {

        LocalContainerEntityManagerFactoryBean emfBean = new LocalContainerEntityManagerFactoryBean();
        //All tenant related entities, repositories and service classes must be scanned
        emfBean.setPackagesToScan(
                new String[] { User.class.getPackage().getName(),
                        UserRepository.class.getPackage().getName(),
                        UserService.class.getPackage().getName() });
        emfBean.setJpaVendorAdapter(jpaVendorAdapter());
        emfBean.setPersistenceUnitName("tenantdb-persistence-unit");
        Map<String, Object> properties = new HashMap<>();
        properties.put(org.hibernate.cfg.Environment.MULTI_TENANT,
                MultiTenancyStrategy.SCHEMA);
        properties.put(
                org.hibernate.cfg.Environment.MULTI_TENANT_CONNECTION_PROVIDER,
                connectionProvider);
        properties.put(
                org.hibernate.cfg.Environment.MULTI_TENANT_IDENTIFIER_RESOLVER,
                tenantResolver);
        // ImprovedNamingStrategy is deprecated and unsupported in Hibernate 5
        // properties.put("hibernate.ejb.naming_strategy",
        // "org.hibernate.cfg.ImprovedNamingStrategy");
        properties.put(org.hibernate.cfg.Environment.DIALECT,
                "org.hibernate.dialect.MySQL5Dialect");
        properties.put(org.hibernate.cfg.Environment.SHOW_SQL, true);
        properties.put(org.hibernate.cfg.Environment.FORMAT_SQL, true);
        properties.put(org.hibernate.cfg.Environment.HBM2DDL_AUTO, "update");

        emfBean.setJpaPropertyMap(properties);
        LOG.info("tenantEntityManagerFactory set up successfully!");
        return emfBean;
    }
}

File: DataSourceBasedMultiTenantConnectionProviderImpl.java

This sets up the multi-tenant connection properties required by Hibernate. This is different than the code you have seen in the past 2 blog posts. Here, the datasources are read from the 'master_tenant' table and then stored in a map. This map is used to look up the datasource based on the tenant id. If a tenant is added to the 'master_tenant' table while the application is running, then a request for that tenant will prompt this class to read the 'master_tenant' table once again and recreate the datasource look up map. This is how the application becomes 'dynamic' about using a tenant added at runtime.

package com.sunitkatkar.blogspot.tenant.config;

import java.util.List;
import java.util.Map;
import java.util.TreeMap;

import javax.sql.DataSource;

import org.hibernate.engine.jdbc.connections.
    spi.AbstractDataSourceBasedMultiTenantConnectionProviderImpl;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;

import com.sunitkatkar.blogspot.master.model.MasterTenant;
import com.sunitkatkar.blogspot.master.repository.MasterTenantRepository;
import com.sunitkatkar.blogspot.util.DataSourceUtil;

/**
 * This class does the job of selecting the correct database based on the tenant
 * id found by the {@link CurrentTenantIdentifierResolverImpl}
 * 
 * @author Sunit Katkar, sunitkatkar@gmail.com
 *         (https://sunitkatkar.blogspot.com/)
 * @since ver 1.0 (May 2018)
 * @version 1.0
 *
 */
@Configuration
public class DataSourceBasedMultiTenantConnectionProviderImpl
        extends AbstractDataSourceBasedMultiTenantConnectionProviderImpl {

    private static final Logger LOG = LoggerFactory
            .getLogger(DataSourceBasedMultiTenantConnectionProviderImpl.class);

    private static final long serialVersionUID = 1L;

    /**
     * Injected MasterTenantRepository to access the tenant information from the
     * master_tenant table
     */
    @Autowired
    private MasterTenantRepository masterTenantRepo;

    /**
     * Map to store the tenant ids as key and the data source as the value
     */
    private Map<String, DataSource> dataSourcesMtApp = new TreeMap<>();

    @Override
    protected DataSource selectAnyDataSource() {
        // This method is called more than once. So check if the data source map
        // is empty. If it is then rescan master_tenant table for all tenant
        // entries.
        if (dataSourcesMtApp.isEmpty()) {
            List<MasterTenant> masterTenants = masterTenantRepo.findAll();
            LOG.info(">>>> selectAnyDataSource() -- Total tenants:"
                    + masterTenants.size());
            for (MasterTenant masterTenant : masterTenants) {
                dataSourcesMtApp.put(masterTenant.getTenantId(), DataSourceUtil
                        .createAndConfigureDataSource(masterTenant));
            }
        }
        return this.dataSourcesMtApp.values().iterator().next();
    }


    @Override
    protected DataSource selectDataSource(String tenantIdentifier) {
        // If the requested tenant id is not present check for it in the master
        // database 'master_tenant' table
        if (!this.dataSourcesMtApp.containsKey(tenantIdentifier)) {
            List<MasterTenant> masterTenants = masterTenantRepo.findAll();
            LOG.info(">>>> selectDataSource() -- tenant:" + tenantIdentifier
                    + " Total tenants:" + masterTenants.size());
            for (MasterTenant masterTenant : masterTenants) {
                dataSourcesMtApp.put(masterTenant.getTenantId(), DataSourceUtil
                        .createAndConfigureDataSource(masterTenant));
            }
        }
        return this.dataSourcesMtApp.get(tenantIdentifier);
    }
}

Resources

The complete source code is checked into GitHub. Its a standard Maven project which you can import into your IDE.

In conclusion

That's all there is to reading tenant information at run time. For a production grade application, I recommend that you create a separate Spring Boot app or a microservice to manage the tenant information in the master_tenant table. So this keeps the management of the application separate from the actual application. The master database can be used to store other kinds of app related information and the separate app can be used by the administrators for other app related activities.

Happy coding :)

Update - 10 July 2018

A reader of my blog - Jordan Mackie - found an error which was a mistake on my part in publishing a small but important part of the code. In the file TenantDatabaseConfig.java you need to explicitly name the tenant entity manager factory and use that when passing it in to the transaction manager. So the code should look like

@Bean(name = "tenantTransactionManager")
    public JpaTransactionManager transactionManager(
@Qualifier("tenantEntityManagerFactory")
EntityManagerFactory tenantEntityManager) {
        JpaTransactionManager transactionManager = new JpaTransactionManager();
        transactionManager.setEntityManagerFactory(tenantEntityManager);
        return transactionManager;
    }

Spring Boot 2 generic JPA converter to serialize and deserialize an entity attribute as JSON

noreply@blogger.com (Sunit) — Thu, 10 May 2018 19:10:00 +0000

As I wrote in my previous blog post, I needed to store some custom attributes of entities as JSON strings in the database.

Sometimes an entity attribute is not just a native or simple type like a Date, Long or String. A Java POJO like structure is required as an attribute. One might argue that a separate entity should be created which results in a separate table and a reference to it should be used like in a OneToOne or ManyToOne or OneToMany type of relationship. But there are special business conditions where creating a separate entity is not feasible. So, storing this entity as a JSON string is a good solution.

Purpose of this blog post

In the last blog post, I shared how I wrote a generic encryption decryption JPA Converter. In this blog post I will show you how to store a custom Java POJO like attribute as a JSON string in a database table column.

JPA allows writing 'conversion' code so that an entity attribute (table column) can be converted from one type to another and back. Though this is not a latest feature of JPA nor a bleeding edge topic, I am sharing how I wrote a generic converter for serialization and serialization of a Java POJO object to a string type table column.

Java and JSON

I am assuming you know what JSON is and how it is used for data transformation. If you need to know more then click here.

In our case, we need to convert some Java POJO like JPA attribute to its JSON equivalent and store it in the database table column. Similarly, we need to parse the JSON format and convert it back to the original Java POJO like attribute.

Java and Jackson

Given that JSON is not a complex format, one can attempt to convert a Java POJO like object into a JSON String and back by writing code for each such object. However, this is a tedious and error-prone endeavor. And why do it all yourself when there is a reliable, widely used library to do this? Faster Jackson is an awesome library to help convert your Java POJO like object into JSON (and XML too) and parse the JSON back into the original Java POJO object.

If you are new to Jackson or want to read more, then click here. There is a good tutorial here. For a more Spring framework specific tutorial, click here.

JPA and Converter

JPA allows you to apply a @Converter annotation to any Entity attribute i.e. to any table column definition in your table defintion. This is possible via the AttributeConveter interface. A class implementing this interface needs to implement the methods from this interface

Y convertToDatabaseColumn(X attribute) - Converts the value stored in the entity attribute into the data representation to be stored in the database.
X convertToEntityAttribute(Y dbData) - Converts the data stored in the database column into the value to be stored in the entity attribute. Note that it is the responsibility of the converter writer to specify the correct dbData type for the corresponding column for use by the JDBC driver: i.e., persistence providers are not expected to do such type conversion.

Writing the generic converter

Please keep these two Jackson JSON javadocs open in your browser so that you can refer to them while reading the code I am presenting.

Jackson Core Javadocs
Jackson Databind Javadocs

Though we do not need it for this converter, you can also look at the Jackson JSON Annotation javadocs for more details.

Note that for a good error free conversion of your Java POJO like object, one of the requirements is to provide the class type information to the Jackson ObjectMapper. It is not an absolute must, but having it is better. Also for a generic converter, it becomes quite essential to tell the converter about the Class type of the object.

The generic JSON JPA converter code

Here is the converter code. We just need one concrete class which can then be extended to convert a specific Java POJO like attribute.

package com.sunitkatkar.blogspot.converters;

import java.io.IOException;

import javax.persistence.AttributeConverter;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.fasterxml.jackson.annotation.JsonAutoDetect;
import com.fasterxml.jackson.annotation.JsonInclude.Include;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectReader;
import com.fasterxml.jackson.databind.ObjectWriter;

/**
 * JPA converter class which converts any POJO like object to a JSON string and
 * stores it in the database table column. The JSON string contains the class
 * name of the POJO and its JSON format string. <br/>
 * 
 * Note: An abstract class is not needed as this class takes care of all the
 * JSON serialization and deserialization. You only need to extend this class so
 * that you can use your POJO class for conversion. The extended class should be
 * annotated with the {@literal @}Converter annotation
 * 
 * @author Sunit Katkar, sunitkatkar@gmail.com
 *         (https://sunitkatkar.blogspot.com/)
 * @since ver 1.0 (May 2018)
 * @version 1.0
 * @param <X>
 */
public class GenericJsonAttributeConverter<X>
        implements AttributeConverter<X, String> {

    protected static final Logger LOG = LoggerFactory
            .getLogger(GenericJsonAttributeConverter.class);

    /**
     * To 'write' the attribute POJO as a JSON string
     */
    private final ObjectWriter writer;

    /**
     * To 'read' the JSON string and convert to the attribute POJO
     */
    private final ObjectReader reader;

    /**
     * Default constructor
     */
    public GenericJsonAttributeConverter() {

        ObjectMapper mapper = new ObjectMapper();

        // We want all keys in the key value pair JSON even if the key has no
        // value
        mapper.setSerializationInclusion(Include.ALWAYS);

        //@formatter:off
        // The mapper should be able to 'see' the entity attributes (fields)
        mapper.setVisibility(mapper.getSerializationConfig()
                .getDefaultVisibilityChecker()
                .withFieldVisibility(JsonAutoDetect.Visibility.ANY)
                .withGetterVisibility(JsonAutoDetect.Visibility.NONE)
                .withIsGetterVisibility(JsonAutoDetect.Visibility.NONE));
        //@@formatter:on

        // We are wrapping the entity attribute in a class. See class for
        // details.
        reader = mapper.reader().forType(JsonTypeLike.class);
        writer = mapper.writer().forType(JsonTypeLike.class);
    }

    /*
     * (non-Javadoc)
     * 
     * @see
     * javax.persistence.AttributeConverter#convertToDatabaseColumn(java.lang.
     * Object)
     */
    @Override
    public String convertToDatabaseColumn(X attribute) {
        try {
            if (attribute != null) {
                JsonTypeLike<X> wrapper = new JsonTypeLike<X>(attribute,
                        writer);
                String value = writer.writeValueAsString(wrapper);
                return value;
            } else {
                return null;
            }
        } catch (JsonProcessingException e) {
            LOG.error("Failed to serialize as object into JSON: {}", attribute,
                    e);
            throw new RuntimeException(e);
        }
    }

    /*
     * (non-Javadoc)
     * 
     * @see
     * javax.persistence.AttributeConverter#convertToEntityAttribute(java.lang.
     * Object)
     */
    @Override
    public X convertToEntityAttribute(String dbData) {
        try {
            if (dbData != null) {
                JsonTypeLike<X> wrapper = reader.readValue(dbData);
                X obj = wrapper.readValue(reader);
                return obj;
            } else {
                return null;
            }
        } catch (IOException e) {
            LOG.error("Failed to deserialize as object from JSON: {}", dbData,
                    e);
            throw new RuntimeException(e);
        }
    }

    /**
     * The concrete type is needed for Jackson to serialize or deserialize. This
     * class is created to wrap the entity type &lt;Y&gt; so that the Jackson
     * {@link ObjectReader#forType(Class)} and
     * {@link ObjectWriter#forType(Class))} can be used to get the concrete type
     * of the attribute being serialized/deserialized.
     * 
     * @author Sunit Katkar, sunitkatkar@gmail.com
     *
     * @param <Y>
     */
    public static class JsonTypeLike<Y> {

        // For adding the type (class) of the entity in the generated JSON
        private String entityType;

        // For the actual value which is obtained by reading or writing the JSON
        private String entityValue;

        public JsonTypeLike() {
        }

        /**
         * Constructor which helps initialize the ObjectWriter by providing the
         * concrete class type to the writer
         * 
         * @param obj
         * @param writer
         */
        public JsonTypeLike(Y obj, ObjectWriter writer) {
            // TODO: Need a better way to do type conversion and not get safety
            // warning
            Class<Y> classType = ((Class<Y>) obj.getClass());
            // We are saving the class type as a string in entityType so that
            // while reading
            // back the JSON, the target Class type is known o the mapper.
            this.entityType = obj.getClass().getName();

            try {
                this.entityValue = writer.forType(classType)
                        .writeValueAsString(obj);
            } catch (JsonProcessingException e) {
                LOG.error("Failed serializing object to JSON: {}", obj, e);
            }
        }

        /**
         * Read the JSON format string and create the target Java POJO object
         * 
         * @param reader
         * @return
         */
        public Y readValue(ObjectReader reader) {
            try {
                // Once the json string is read, we need to know what is the
                // destination class
                // type. So reading the entityType value helps in getting the
                // Class details.
                Class<?> clazz = Class.forName(this.entityType);
                Y obj = reader.forType(clazz).readValue(this.entityValue);
                return obj;
            } catch (ClassNotFoundException | IOException e) {
                LOG.error("Failed deserializing object from JSON: {}",
                        this.entityValue, e);
                return null;
            }
        }

        public String getEntityType() {
            return entityType;
        }

        public void setEntityType(String type) {
            this.entityType = type;
        }

        public String getEntityValue() {
            return entityValue;
        }

        public void setValue(String value) {
            this.entityValue = value;
        }
    }
}

Example for using the converter

Let us suppose there is a class called Student and it contains an attribute of another custom type called Course. The Course is a simple Java POJO which contains details about the course that a student enrolls in.

JPA Entity - Student

This JPA entity has a Course attribute. The Student entity will create a table called 'student' in the database and have a column/field called 'course'. This course attribute is the one which needs to be stored as a JSON string.

package com.sunitkatkar.blogspot.model;

import javax.persistence.Column;
import javax.persistence.Convert;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;
import com.sunitkatkar.blogspot.converters.CourseJsonConverter;

/**
 * JPA Entity which will be saved in the database table named 'student'. The
 * attribute (or table column) <tt>course</tt> needs to be converted to a JSON
 * string for storage and converted back to {@link Course} POJO when read.
 * 
 * @author Sunit Katkar, sunitkatkar@gmail.com
 *         (https://sunitkatkar.blogspot.com/)
 * @since ver 1.0 (May 2018)
 * @version 1.0
 */
@Entity
@Table(name = "student")
public class Student {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "student_id")
    private Long id;

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

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

    /**
     * This attribute is the Course POJO which needs to be stored as a JSON
     * string
     */
    @Convert(converter = CourseJsonConverter.class)
    @Column(name = "course")
    private Course course;

    /**
     * Just a field to get the Course POJO as a JSON string and display on the
     * UI
     */
    private String json;

    /**
     * @return the json
     */
    /**
     * Default constructor
     */
    public Student() {
    }

    // Getters and setters
    /**
     * @return the id
     */
    public Long getId() {
        return id;
    }

    /**
     * @param id
     *            the id to set
     */
    public void setId(Long id) {
        this.id = id;
    }

    /**
     * @return the firstName
     */
    public String getFirstName() {
        return firstName;
    }

    /**
     * @param firstName
     *            the firstName to set
     */
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    /**
     * @return the lastName
     */
    public String getLastName() {
        return lastName;
    }

    /**
     * @param lastName
     *            the lastName to set
     */
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    /**
     * @return the course
     */
    public Course getCourse() {
        return course;
    }

    /**
     * @param course
     *            the course to set
     */
    public void setCourse(Course course) {
        this.course = course;
    }

    /**
     * Method to get the Course POJO as a JSON string for display on UI
     * 
     * @return
     */
    public String getJson() {
        ObjectMapper mapper = new ObjectMapper();
        ObjectWriter writer = mapper.writer().forType(Course.class);

        String jsonString = "";
        try {
            jsonString = writer.withDefaultPrettyPrinter()
                    .writeValueAsString(this.course);
            // System.out.println(jsonString);
        } catch (JsonProcessingException e) {
            e.printStackTrace();
        }
        return jsonString;
    }

    /**
     * @param json
     *            the json to set
     */
    public void setJson(String json) {
        this.json = json;
    }
}

Course Java POJO

This is the Course attribute in the Student JPA entity. Do note that when you use java.util.Date fields you must annotate them with a @DateTimeFormat annotation so that Spring understands how to convert a string in a date like format to an actual date format. This is especially applicable when you have a browser based UI to enter dates.

package com.sunitkatkar.blogspot.model;

import java.util.Date;

import org.springframework.format.annotation.DateTimeFormat;

/**
 * This POJO is a attribute of the {@link Student} entity. This will be
 * serialized as a JSON string and stored in the 'course' field in the 'student'
 * table.
 * 
 * @author Sunit Katkar, sunitkatkar@gmail.com
 *         (https://sunitkatkar.blogspot.com/)
 * @since ver 1.0 (May 2018)
 * @version 1.0
 */
public class Course {

    private Long id;

    private String title;

    private String description;

    /**
     * The @DateTimeFormat annotation is required as the browser sends a date in
     * string format and Spring needs to translate it into a date. So we have to
     * specify a format for the date. Note that the browser always sends date in
     * the 'yyyy-MM-dd' format when using the HTML5 attribute type='date' on an
     * 'input' tag.
     */
    @DateTimeFormat(pattern = "yyyy-MM-dd")
    private Date startDate;

    @DateTimeFormat(pattern = "yyyy-MM-dd")
    private Date endDate;

    /**
     * 
     */
    public Course() {
        super();
    }

    /**
     * @return the id
     */
    public Long getId() {
        return id;
    }

    /**
     * @param id
     *            the id to set
     */
    public void setId(Long id) {
        this.id = id;
    }

    /**
     * @return the title
     */
    public String getTitle() {
        return title;
    }

    /**
     * @param title
     *            the title to set
     */
    public void setTitle(String title) {
        this.title = title;
    }

    /**
     * @return the description
     */
    public String getDescription() {
        return description;
    }

    /**
     * @param description
     *            the description to set
     */
    public void setDescription(String description) {
        this.description = description;
    }

    /**
     * @return the startDate
     */
    public Date getStartDate() {
        return startDate;
    }

    /**
     * @param startDate
     *            the startDate to set
     */
    public void setStartDate(Date startDate) {
        this.startDate = startDate;
    }

    /**
     * @return the endDate
     */
    public Date getEndDate() {
        return endDate;
    }

    /**
     * @param endDate
     *            the endDate to set
     */
    public void setEndDate(Date endDate) {
        this.endDate = endDate;
    }

}

Using the JSON JPA Converter

To use the converter, all you need to do is create a class which extends from it. The following example is applicable for the Student entity and its attribute Course. That's all there is to it.

import javax.persistence.Converter;

import com.sunitkatkar.blogspot.model.Course;

/**
 * Concrete converter class which extends the {@link GenericJsonAttributeConverter}
 * class. <br/>
 * Note: No need to do anything here. This is used to pass the attribute type to
 * the GenericJsonAttributeConverter
 * 
 * @author Sunit Katkar, sunitkatkar@gmail.com
 *         (https://sunitkatkar.blogspot.com/)
 * @since ver 1.0 (May 2018)
 * @version 1.0
 */
@Converter(autoApply = false)
public class CourseJsonConverter extends GenericJsonAttributeConverter<Course> {

}

Resources

I have included a complete working Spring Boot application to demonstrate how this JSON converter can be used. Visit my Github repository to download the code. You are free to fork it, but just request you to send me an email when you do so.

Happy coding :)

Spring Boot 2 generic JPA converter to encrypt and decrypt an entity attribute

noreply@blogger.com (Sunit) — Wed, 25 Apr 2018 21:45:00 +0000

A recent requirement in my work mandated that certain columns in a table be encrypted when stored in the database. One can use the javax.crypto package from the standard JDK to achieve this by writing service layer code to encrypt and decrypt data for each entity attribute (table column) that required it.

The entire code-base is built using Spring Boot 2 and JPA (Hibernate), so I was looking for a way to achieve the encryption and decryption without having to write code for each entity attribute. Well, there is such a feature provided by JPA called Converters which provide a way for you to write code once and then apply it to any required table attribute by way of a simple @Converter annotation.

Purpose of this blog post

JPA allows writing 'conversion' code so that an entity attribute (table column) can be converted from one type to another and back. Though this is not a latest feature of JPA nor a bleeding edge topic, I am sharing how I wrote a generic converter for encryption and decryption of a string type table column.

Java and Cryptography

The humble JDK provides a very good cryptography package javax.crypto which provides many facilities to do all things related to cryptography, one of which is to encrypt and decrypt data (or strings). I will not go into the details but just note here that the javax.crypto.Cipher class provides the functionality of a cryptographic cipher or algorithm for encryption and decryption.

How does cryptography work?

I am not a cryptography expert, but understand enough of it to apply it to the problem at hand. Basically I want to encrypt a String and write it to a table column in the database and then decrypt it after reading it so that the other layers in the application can use it.

The crypto facilities basically use an ecryption/decryption algorithm to encrypt/decrypt the string and secure the data by applying a key value, which only you know, to encrpt/decrypt the data. That's it in a nutshell.

For more details on how Java cryptography works please see this excellent tutorial

JPA and Converter

Y convertToDatabaseColumn(X attribute) - Converts the value stored in the entity attribute into the data representation to be stored in the database.
X convertToEntityAttribute(Y dbData) - Converts the data stored in the database column into the value to be stored in the entity attribute. Note that it is the responsibility of the converter writer to specify the correct dbData type for the corresponding column for use by the JDBC driver: i.e., persistence providers are not expected to do such type conversion.

Writing the generic attribute converter

I needed a converter which would essentially take a String type attribute and then encrypt it. So, the method Y convertToDatabaseColumn(X attribute) method needed to take a string and return an encrypted version of it for storage.

The converter also has to read the stored encrypted string and return the decrypted version. So, the method X convertToEntityAttribute(Y dbData) needed to take the encrypted String, decrypt it and and return it to the other layers of the JPA mechanism.

One thought that came naturally to mind, was that I didn't want to write code once again when the need arose to encrypt and decrypt some other type of attribute, say a Date or something else. So the base attribute converter had to have just enough code to perform the encryption and decryption of a String. (Note that we want to store the data as an encrypted String in the table column). The other task of converting the entity attribute type to a String and vice versa would have to be done outside this base class to allow flexibility to allow using any attribute entity type.

With these points in mind, here is how I wrote this attribute converter.

Step 1 - Write the encryption and decryption code

As noted before, use Java cryptography to achieve encryption and decryption. For this a Cipher instance is needed with all its properties set appropriately. Then it can be used for encryption and decryption.

import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.Key;
import java.security.NoSuchAlgorithmException;
import java.security.spec.AlgorithmParameterSpec;

import javax.crypto.Cipher;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;

/**
 * Utility class to generate an instance of {@link javax.crypto.Cipher}
 * 
 * @author Sunit Katkar, sunitkatkar@gmail.com
 * @since ver 1.0 (Apr 2018)
 * @version 1.0
 */
public class CipherMaker {

    private static final String CIPHER_INSTANCE_NAME = "AES/CBC/PKCS5Padding";
    private static final String SECRET_KEY_ALGORITHM = "AES";

    /**
     * @param encryptionMode
     *            - decides whether to ecrypt or decrypt data. Values accepted:
     *            {@link Cipher#ENCRYPT_MODE} for encryption and
     *            {@link Cipher#DECRYPT_MODE} for decryption.
     * @param key
     *            - the key to use for encrypting or decrypting data. This can be a
     *            simple String like "MySecretKey" or a more complex, hard to guess
     *            longer string
     * @return
     * @throws InvalidKeyException
     * @throws NoSuchPaddingException
     * @throws NoSuchAlgorithmException
     * @throws InvalidAlgorithmParameterException
     * @throws InvalidKeyException
     * @throws InvalidAlgorithmParameterException
     */
    public Cipher configureAndGetInstance(int encryptionMode, String key)
            throws InvalidKeyException, NoSuchPaddingException, 
            NoSuchAlgorithmException, InvalidAlgorithmParameterException, 
            InvalidKeyException, InvalidAlgorithmParameterException {

        Cipher cipher = Cipher.getInstance(CIPHER_INSTANCE_NAME);
        Key secretKey = new SecretKeySpec(key.getBytes(), SECRET_KEY_ALGORITHM);

        byte[] ivBytes = new byte[cipher.getBlockSize()];
        AlgorithmParameterSpec algorithmParameters = new IvParameterSpec(ivBytes);

        cipher.init(encryptionMode, secretKey, algorithmParameters);
        return cipher;
    }
}

Step 2 - Write the base attribute converter

As noted before, the attribute converter needs to encrypt and decrypt. So, the CipherMaker class above will be useful here. The source code comments are self-explanatory.

import static org.apache.commons.lang3.StringUtils.isNotEmpty;

import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

import javax.crypto.BadPaddingException;
import javax.crypto.Cipher;
import javax.crypto.IllegalBlockSizeException;
import javax.crypto.NoSuchPaddingException;
import javax.persistence.AttributeConverter;

/**
 * Abstract base class for implementing the JPA Attribute Converter which will
 * encrypt and decrypt an Entity attribute (table column)
 * 
 * @author Sunit Katkar, sunitkatkar@gmail.com
 * @since ver 1.0 (Apr 2018)
 * @version 1.0
 * @param <X>
 */
public abstract class AbstractEncryptDecryptConverter<X>
  implements AttributeConverter<X, String> {

 /**
  * This is the key required for encryption/decryption. This is defined here
  * for example purpose. In production, this should come from a secure
  * location not accessible easily. In Spring Boot, one possible location is
  * the application.properties file. Though its not the most secure way, it
  * will keep this key out of the actual java code.
  */
 private static final String SECRET_ENCRYPTION_KEY = "MySuperSecretKey";

 /** CipherMaker is needed to configure and create instance of Cipher */
 private CipherMaker cipherMaker;

 /**
  * Constructor
  * 
  * @param cipherMaker
  */
 public AbstractEncryptDecryptConverter(CipherMaker cipherMaker) {
  this.cipherMaker = cipherMaker;
 }

 /**
  * Default constructor
  */
 public AbstractEncryptDecryptConverter() {
  this(new CipherMaker());
 }

 /*
  * (non-Javadoc)
  * 
  * @see
  * javax.persistence.AttributeConverter#convertToDatabaseColumn(java.lang.
  * Object)
  */
 @Override
 public String convertToDatabaseColumn(X attribute) {
  if (isNotEmpty(SECRET_ENCRYPTION_KEY) && isNotNullOrEmpty(attribute)) {
   try {
    Cipher cipher = cipherMaker.configureAndGetInstance(
      Cipher.ENCRYPT_MODE, 
      SECRET_ENCRYPTION_KEY);
    return encryptData(cipher, attribute);
   } catch (NoSuchAlgorithmException 
     | InvalidKeyException
     | InvalidAlgorithmParameterException 
     | BadPaddingException
     | NoSuchPaddingException 
     | IllegalBlockSizeException e) {
    throw new RuntimeException(e);
   }
  }
  return convertEntityAttributeToString(attribute);
 }

 /*
  * (non-Javadoc)
  * 
  * @see
  * javax.persistence.AttributeConverter#convertToEntityAttribute(java.lang.
  * Object)
  */
 @Override
 public X convertToEntityAttribute(String dbData) {
  if (isNotEmpty(SECRET_ENCRYPTION_KEY) && isNotEmpty(dbData)) {
   try {
    Cipher cipher = cipherMaker.configureAndGetInstance(
      Cipher.DECRYPT_MODE, 
      SECRET_ENCRYPTION_KEY);
    return decryptData(cipher, dbData);
   } catch (NoSuchAlgorithmException 
     | InvalidAlgorithmParameterException
     | InvalidKeyException 
     | BadPaddingException
     | NoSuchPaddingException 
     | IllegalBlockSizeException e) {
    throw new RuntimeException(e);
   }
  }
  return convertStringToEntityAttribute(dbData);
 }

 /**
  * The concrete class which implements this abstract class will have to
  * provide the implementation. For simple String encryption, the
  * implementation is simple as apache commons lang StringUtils can be used.
  * But this method was abstracted out as there might be other types of null
  * check technique required when a non String entity is to be encrypted
  * 
  * @param attribute
  * @return
  */
 abstract boolean isNotNullOrEmpty(X attribute);

 /**
  * The concrete class which implements this abstract class will have to
  * provide the implementation. For decryption of a String, its simple as a
  * String has to be returned, but for other non String types some more code
  * might have to be implemented. For example, a Date type of Date string.
  * 
  * @param dbData
  * @return
  */
 abstract X convertStringToEntityAttribute(String dbData);

 /**
  * The concrete class which implements this abstract class will have to
  * provide the implementation. For encryption of a String, its simple as a
  * String has to be returned, but for other non String types some more code
  * might have to be implemented. For example, a Date type of Date string.
  * 
  * @param attribute
  * @return
  */
 abstract String convertEntityAttributeToString(X attribute);

 /**
  * Helper method to encrypt data
  * 
  * @param cipher
  * @param attribute
  * @return
  * @throws IllegalBlockSizeException
  * @throws BadPaddingException
  */
 private String encryptData(Cipher cipher, X attribute)
   throws IllegalBlockSizeException, BadPaddingException {
  byte[] bytesToEncrypt = convertEntityAttributeToString(attribute)
    .getBytes();
  byte[] encryptedBytes = cipher.doFinal(bytesToEncrypt);
  return Base64.getEncoder().encodeToString(encryptedBytes);
 }

 /**
  * Helper method to decrypt data
  * 
  * @param cipher
  * @param dbData
  * @return
  * @throws IllegalBlockSizeException
  * @throws BadPaddingException
  */
 private X decryptData(Cipher cipher, String dbData)
   throws IllegalBlockSizeException, BadPaddingException {
  byte[] bytesToDecrypt = Base64.getDecoder().decode(dbData);
  byte[] decryptedBytes = cipher.doFinal(bytesToDecrypt);
  return convertStringToEntityAttribute(new String(decryptedBytes));
 }
}

Step 3 - Implementing the concrete String encryption/descryption JPA attribute converter

Now that the base class and crypto code is ready, the actual implementation for writing a string ecnryption/decryption JPA converter is quite easy.

/**
 * Concrete implementation of the {@link AbstractEncryptDecryptConverter}
 * abstract class to encrypt/decrypt an entity attribute of type
 * {@link java.lang.String} <br/>
 * Note: This is the class where the {@literal @}Converter annotation is applied
 * 
 * @author Sunit Katkar, sunitkatkar@gmail.com
 * @since ver 1.0 (Apr 2018)
 * @version 1.0 *
 */
@Converter(autoApply = false)
public class StringEncryptDecryptConverter
  extends AbstractEncryptDecryptConverter<String> {

 /**
  * Default constructor initializes with an instance of the
  * {@link CipherMaker} crypto class to get a {@link javax.crypto.Cipher}
  * instance
  */
 public StringEncryptDecryptConverter() {
  this(new CipherMaker());
 }

 /**
  * Constructor
  * 
  * @param cipherMaker
  */
 public StringEncryptDecryptConverter(CipherMaker cipherMaker) {
  super(cipherMaker);
 }

 @Override
 boolean isNotNullOrEmpty(String attribute) {
  return isNotEmpty(attribute);
 }

 @Override
 String convertStringToEntityAttribute(String dbData) {
  // the input is a string and output is a string
  return dbData;
 }

 @Override
 String convertEntityAttributeToString(String attribute) {
  // Here too the input is a string and output is a string
  return attribute;
 }
}

Step 4 - Using the String encryption/descryption JPA attribute converter

Using this JPA converter in a JPA Entity is just a matter of annotating the attribute with the @Convert annotation as shown below.

import java.io.Serializable;

import javax.persistence.Column;
import javax.persistence.Convert;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

/**
 * JPA Entity which will be saved in the database table named 'employee'. The
 * attribute (or table column) <tt>sensitiveData</tt> needs to be encrypted for
 * storage and decrypted when read.
 * 
 * @author Sunit Katkar, sunitkatkar@gmail.com
 * @since ver 1.0 (Apr 2018)
 * @version 1.0
 * @param <X>
 */
@Entity
@Table(name = "employee")
public class Employee implements Serializable {

 private static final long serialVersionUID = 1L;

 @Id
 @GeneratedValue(strategy = GenerationType.IDENTITY)
 @Column(name = "employee_id")
 private Long id;

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

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

 /**
  * This String attribute needs to be encrypted
  */
 @Column(name = "sensitive_data")
 @Convert(converter = StringEncryptDecryptConverter.class)
 private String sensitiveData;

 /**
  * @return the id
  */
 public Long getId() {
  return id;
 }

 /**
  * @param id
  *            the id to set
  */
 public void setId(Long id) {
  this.id = id;
 }

 /**
  * @return the firstName
  */
 public String getFirstName() {
  return firstName;
 }

 /**
  * @param firstName
  *            the firstName to set
  */
 public void setFirstName(String firstName) {
  this.firstName = firstName;
 }

 /**
  * @return the lastName
  */
 public String getLastName() {
  return lastName;
 }

 /**
  * @param lastName
  *            the lastName to set
  */
 public void setLastName(String lastName) {
  this.lastName = lastName;
 }

 /**
  * @return the sensitiveData
  */
 public String getSensitiveData() {
  return sensitiveData;
 }

 /**
  * @param sensitiveData
  *            the sensitveData to set
  */
 public void setSensitiveData(String sensitiveData) {
  this.sensitiveData = sensitiveData;
 }
}

Bonus - Converter to encrypt / decrypt LocalDate

Since the basic infrastructure for encrypting and decrypting JPA entity attributes is created, it can be used for converting other types of entities, for example, an attribute of type java.time.LocalDate. Here is the code to do that.

import static java.time.format.DateTimeFormatter.ISO_DATE;
import static org.apache.commons.lang3.StringUtils.isEmpty;

import java.time.LocalDate;

import javax.persistence.Converter;

/**
 * Concrete implementation of the {@link AbstractEncryptDecryptConverter}
 * abstract class to encrypt/decrypt an entity attribute of type
 * {@link java.time.LocalDate} <br/>
 * Note: This is the class where the {@literal @}Converter annotation is applied
 * 
 * @author Sunit Katkar, sunitkatkar@gmail.com
 * @since ver 1.0 (Apr 2018)
 * @version 1.0 *
 */
@Converter(autoApply = false)
public class LocalDateEncryptDecryptConverter
  extends AbstractEncryptDecryptConverter<LocalDate> {

 public LocalDateEncryptDecryptConverter() {
  this(new CipherMaker());
 }

 public LocalDateEncryptDecryptConverter(CipherMaker cipherMaker) {
  super(cipherMaker);
 }

 @Override
 boolean isNotNullOrEmpty(LocalDate attribute) {
  return attribute != null;
 }

 @Override
 LocalDate convertStringToEntityAttribute(String dbData) {
  return isEmpty(dbData) ? null : LocalDate.parse(dbData, ISO_DATE);
 }

 @Override
 String convertEntityAttributeToString(LocalDate attribute) {
  return ((attribute == null) ? null : attribute.format(ISO_DATE));
 }
}

Resources

The source code for this blog post is available as a Spring Boot 2 project on Github. Click here.

Happy coding :)

Building SaaS style multi-tenant web app with Spring Boot 2 and Spring Security 5 - Part 1

noreply@blogger.com (Sunit) — Wed, 11 Apr 2018 16:29:00 +0000

Software as a Service or SaaS has been around for quite some time now. But most of the time, developers are building single tenant applications as per requirements. These applications have just one database and one web server at their core.

Purpose of this blog post

I wanted a solution where multi-tenancy is achieved by having a database per tenant and all user information (username, password, etc) for authentication and authorization stored in a user table in the respective tenant databases. It meant that not only did I need a multi-tenant application, but also a secure application like any other web application secured by Spring Security.

I know how to use Spring Security to secure a web application and how to use Hibernate to connect to a database. The requirement further dictated that all users belonging to a tenant be stored in the tenant database and not a separate or central database. This would allow for complete data isolation for each tenant.

So I did what most people do - I googled :) I found many blog posts and articles published on multi-tenancy and web application security, but could not found a single solution or example implementation which addresses database per tenant approach along with security. Maybe it is too trivial of a topic and hence no blogs or articles ;-)

So I just built my own!

The solution I describe below might sound a little complicated but if you are familiar with the basics of Spring Security and Hibernate, then its quite simple, albeit a bit tedious.

I have broken up this blog post into two parts as the code to set up multi-tenancy and spring security is quite a lot. I don't want you to keep scrolling down to finish reading the blog post. :)

What is used to build the example in this blog post?

Here, I am going to share how I built a SaaS style web app using the latest Spring Boot 2, Spring JPA with Hibernate as the JPA provider to connect to MySQL and Spring Security 5 to secure the web aplication.

What is Multi-Tenancy?

A multi-tenant application is where a tenant (i.e. users in a company) feels that the application has been created and deployed for them. In reality, there are many such tenants and they too are using the same application but get a feel that its built just for them. Typical examples are online applications for time-sheet management, project management, Scrum/Agile Sprint management, etc etc.

A more technical explanation of multi-tenancy

SaaS applications are multi-tenant applications which require tenant data isolation in the database layer. There are different approaches for achieving this data isolation.
The most widely used approaches are

Schema per tenant - all tenants have their own schema but these schema live in the same database
Discriminator per tenant - data for all tenants is in the same schema in the database but is distinguished by a tenant discriminator column
Database per tenant - each tenant has a separate database

Which multi-tenancy approach is better?

There are many factors to consider before choosing a data isolation approach as mentioned above. We will not go into depth of each but focus mainly on building a multi-tenant application using the latest Spring Boot 2 framework along with JPA, Hibernate as the JPA provider and Spring Security 5.

Multi-tenancy using database per tenant approach

In many applications, especially in financial and medical domains, there is a strict need for absolute data isolation, security and privacy in multi-tenant applications. As far as my experience, knowledge and research on this topic goes, multi-tenancy using database per tenant is the best for data isolation and security. I may be wrong and your feedback is welcome.

How does the SaaS application work?

We will build a database per tenant multi-tenant application secured by Spring Security.
In most SaaS applications, there is an entry point where a user belonging to a tenant enters the

tenant name (company name in most cases or some other identifier)
username
password

Step 1 - Process the login form with the extra 'tenant' field

The login form will present the tenant name, username and password to Spring Security for authentication.
The Spring Security UsernamePasswordAuthenticationFilter filter intercepts the login form's request to the server. This filter needs to be extended so that the extra field 'tenant' can be extracted.
This tenant field is the tenant database identifier and is required by Hibernate to identify the tenant database to connect to.
Once the tenant field is extracted by the security filter, it needs to be set in memory so that after the security filter is finished doing its job, this tenant identifier is available to the Hibernate code to connect to the correct tenant database.
To make this happen, the tenant field is stored in a ThreadLocal

Step 2 - Compare the login form values with existing user in the database

Now that the username, password and tenant values are available to Spring Security, the AbstractUserDetailsAuthenticationProvider will use the retrieveUser() method to call upon the UserDetailsService to get the user details from the database.
If the credentials from the login form match those of the result returned by the tenant database, then the authentication is successful and Spring Security will now log the user into the application and create a secure session for the user for further access and interaction with the protected resources in the application.

Step 3 - Select the correct tenant database

Step 3 actually happens along side Step 2.
It means that Spring Security does its job of preparing user credentials for comparison with existing users in the database.
And Hibernate does its job of selecting the correct tenant database to provide such a user record to Spring Security for comparison.

How does Step 3 work?

In Step 2 above, Spring Security queries the database for a user based on the login form username and tenant field. So how does Hibernate know to get the user from the correct tenant database. In Step 1 note that the tenant field is stored in a ThreadLocal for later access.

Hibernate provides CurrentTenantIdentifierResolver for resolving or identifying the correct tenant id. The tenant id is extracted from the ThreadLocal storage.

Hibernate also provides AbstractDataSourceBasedMultiTenantConnectionProviderImpl (also see DataSourceBasedMultiTenantConnectionProviderImpl) whose job is to provide the datasource corresponding to the tenant identifier.

How Spring Security and Hibernate process the login form

Technology Stack

I am assuming that you are comfortable with Spring MVC, Spring Boot, JPA, Hibernate and Spring Security. The example application was built using -

Spring Boot 2 (2.0.1.RELEASE)

Spring Security 5

MySQL

Spring JPA (Spring Boot 2 provides latest Hibernate 5 as the JPA provider)

Java 8

Spring STS IDE

Understanding the code for the application

I will describe the significant code in this section. Rest of the code is available in the GitHub repository for this example application. The link is in the Resources section at the end. If you want to just use the code and run it, then skip to the resources section at the end of part 2 for the GitHub link.

Project Layout

This is how my project layout is in Spring STS

File: pom.xml

Using the Spring Initialzr create a project with Spring Web, Security, Thymeleaf, MySQL and JPA. It should generate a pom.xml as follows:

Note that I have added a few extra dependencies -

Cyber NekoHTML for setting ThymeLeaf in legacy mode. Why? Thymeleaf complains if there are no proper closing tags but HTML5 allows some attributes to not have closing tags. So the fix is to use this dependency. A detailed problem statement and its solution is on this stackoverflow thread.

Apache commons-lang-3 for StringUtils

spring-boot-configuration-processor for helping with reading config properties. When you have annotations like @ConfigurationProperties, the STS IDE itself suggests that this dependency should be added.

This is the final pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <groupId>com.example</groupId>
 <artifactId>multitenancy-mysql</artifactId>
 <version>1.0.1</version>
 <packaging>jar</packaging>
 <name>multitenancy-mysql</name>
 <description>Spring Boot JPA Hibernate with Per Database Multi-Tenancy with Spring Security</description>
 <contributors>
  <contributor>
   <name>Sunit Katkar</name>
   <email>sunitkatkar@gmail.com</email>
   <url>https://sunitkatkar.blogspot.com/</url>
  </contributor>
 </contributors>

 <parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>2.0.1.RELEASE</version>
  <relativePath /> <!-- lookup parent from repository -->
 </parent>

 <properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
  <java.version>1.8</java.version>
 </properties>

 <dependencies>
  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-data-jpa</artifactId>
  </dependency>
  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-security</artifactId>
  </dependency>
  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-thymeleaf</artifactId>
  </dependency>
  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-configuration-processor</artifactId>
   <optional>true</optional>
  </dependency>
  <dependency>
   <groupId>mysql</groupId>
   <artifactId>mysql-connector-java</artifactId>
   <scope>runtime</scope>
  </dependency>
  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-test</artifactId>
   <scope>test</scope>
  </dependency>
  <dependency>
   <groupId>org.springframework.security</groupId>
   <artifactId>spring-security-test</artifactId>
   <scope>test</scope>
  </dependency>
  <dependency>
   <groupId>net.sourceforge.nekohtml</groupId>
   <artifactId>nekohtml</artifactId>
   <version>1.9.21</version>
  </dependency>
  <!-- https://mvnrepository.com/artifact/org.apache.commons/commons-lang3 -->
  <dependency>
   <groupId>org.apache.commons</groupId>
   <artifactId>commons-lang3</artifactId>
   <version>3.7</version>
  </dependency>
 </dependencies>

 <build>
  <plugins>
   <plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
   </plugin>
  </plugins>
 </build>
</project>

File: application.yml

I have worked mostly with application.properties files, but found that the YAML format is easier to use when defining multiple data sources. In this example application, I have defined two data sources multitenancy.mtapp.dataSources which are pointing to 2 MySQL databases running on a MySQL instance.

spring:
  thymeleaf:
    cache: false
    mode: LEGACYHTML5
  jpa:
    database: mysql
    show-sql: true 
    generate-ddl: false
    hibernate: 
      ddl-auto: none  

multitenancy: 
  mtapp: 
    dataSources: 
      -
        tenantId: tenant_1 
        url: jdbc:mysql://localhost:3306/dbtenant1?useSSL=false 
        username: tenant1 
        password: admin123 
        driverClassName: com.mysql.jdbc.Driver 
      -
        tenantId: tenant_2
        url: jdbc:mysql://localhost:3306/dbtenant2?useSSL=false
        username: tenant1
        password: admin123
        driverClassName: com.mysql.jdbc.Driver

Note that spring.thymeleaf.mode is set to LEGACYHTML5. The Cyber NekoHTML dependency will then take care of not being so strict about parsing HTML5 and ThymeLeaf will not complain.

File: CustomUserDetails.java

Note that Spring Security provides the interface UserDetails. An implementation of this interface requires details about the user to be authenticated. For this, Spring Security provides a User class which can be used as is or extended. The example application extends this org.springframework.security.core.userdetails.User class to add the tenant attribute to the User.

package com.example.model;

import java.util.Collection;

import org.springframework.security.core.GrantedAuthority;

/**
 * CustomUserDetails class extends the Spring Security provided
 * {@link org.springframework.security.core.userdetails.User} class for
 * authentication purpose. Do not confuse this with the {@link User} class which
 * is an entity for storing application specific user details like username,
 * password, tenant, etc in the database using the JPA {@literal @}Entity
 * annotation.
 * 
 * @author Sunit Katkar
 * @version 1.0
 * @since 1.0 (April 2018)
 *
 */
public class CustomUserDetails 
    extends org.springframework.security.core.userdetails.User {

    private static final long serialVersionUID = 1L;

    /**
     * The extra field in the login form is for the tenant name
     */
    private String tenant;

    /**
     * Constructor based on the spring security User class but with an extra
     * argument <code>tenant</code> to store the tenant name submitted by the end
     * user.
     * 
     * @param username
     * @param password
     * @param authorities
     * @param tenant
     */
    public CustomUserDetails(String username, String password, 
                Collection<? extends GrantedAuthority> authorities,
                String tenant) {
        super(username, password, authorities);
        this.tenant = tenant;
    }

    // Getters and Setters
    public String getTenant() {
        return tenant;
    }

    public void setTenant(String tenant) {
        this.tenant = tenant;
    }

}

File: CustomUserDetailsServiceImpl.java

Spring Security provides a interface UserDetailsService which has just one method declared in it - loadUserByUsername which returns the UserDetails. Now this UserDetails is used for authentication. In the example application code, the CustomUserDetails already defines the attributes for the User.

package com.example.security;

import java.util.HashSet;
import java.util.Set;

import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.stereotype.Service;

import com.example.model.CustomUserDetails;
import com.example.model.Role;
import com.example.model.User;
import com.example.service.UserService;

/**
 * {@link CustomUserDetailsService} contract defines a single method called
 * loadUserByUsernameAndTenantname.
 * 
 * The {@link CustomUserDetailsServiceImpl} class simply implements the contract
 * and delegates to {@link UserService} to get the
 * {@link com.example.model.User} from the database so that it can be compared
 * with the {@link org.springframework.security.core.userdetails.User} for
 * authentication. Authentication occurs via the
 * {@link CustomUserDetailsAuthenticationProvider}.
 * 
 * @author Sunit Katkar
 * @version 1.0
 * @since 1.0 (April 2018)
 *
 */
@Service("userDetailsService")
public class CustomUserDetailsServiceImpl implements CustomUserDetailsService {

    @Autowired
    private UserService userService;

    @Override
    public UserDetails loadUserByUsernameAndTenantname(String username, String tenant)
            throws UsernameNotFoundException {
        if (StringUtils.isAnyBlank(username, tenant)) {
            throw new UsernameNotFoundException("Username and domain must be provided");
        }
        // Look for the user based on the username and tenant by accessing the
        // UserRepository via the UserService
        User user = userService.findByUsernameAndTenantname(username, tenant);

        if (user == null) {
            throw new UsernameNotFoundException(
                    String.format("Username not found for domain, "
                            + "username=%s, tenant=%s", username, tenant));
        }

        Set<GrantedAuthority> grantedAuthorities = new HashSet<>();
        for (Role role : user.getRoles()) {
            grantedAuthorities.add(new SimpleGrantedAuthority(role.getRole()));
        }

        CustomUserDetails customUserDetails = 
                new CustomUserDetails(user.getUsername(), 
                        user.getPassword(), grantedAuthorities, tenant);
        
        return customUserDetails;
    }
}

File: CustomUserDetailsAuthenticationProvider.java

Spring Security provides class AbstractUserDetailsAuthenticationProvider which allows subclasses to override and work with UserDetails objects. The class is designed to respond to UsernamePasswordAuthenticationToken authentication requests.

The CustomUserDetailsAuthenticationProvider implemented for this application delegates to the CustomUserDetailsService (implemented by CustomUserDetailsServiceImpl) for retrieving the UserDetails for authentication

package com.example.security;

import org.springframework.security.authentication.BadCredentialsException;
import org.springframework.security.authentication.InternalAuthenticationServiceException;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.authentication.dao.AbstractUserDetailsAuthenticationProvider;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.util.Assert;

/**
 * {@link CustomUserDetailsAuthenticationProvider} extends
 * {@link AbstractUserDetailsAuthenticationProvider} and delegates to the
 * {@link CustomUserDetailService} to retrieve the User. The most important
 * feature of this class is the implementation of the <code>retrieveUser</code>
 * method.
 * 
 * Note that the authentication token must be cast to CustomAuthenticationToken
 * to access the custom field - tenant
 * 
 * 
 * @author Sunit Katkar
 * @version 1.0
 * @since 1.0 (April 2018)
 */
public class CustomUserDetailsAuthenticationProvider 
            extends AbstractUserDetailsAuthenticationProvider {

    /**
     * The plaintext password used to perform PasswordEncoder#matches(CharSequence,
     * String)} on when the user is not found to avoid SEC-2056
     * (https://github.com/spring-projects/spring-security/issues/2280).
     */
    private static final String USER_NOT_FOUND_PASSWORD = "userNotFoundPassword";

    /**
     * For encoding and/or matching the encrypted password stored in the database
     * with the user submitted password
     */
    private PasswordEncoder passwordEncoder;

    private CustomUserDetailsService userDetailsService;

    /**
     * The password used to perform
     * {@link PasswordEncoder#matches(CharSequence, String)} on when the user is not
     * found to avoid SEC-2056. This is necessary, because some
     * {@link PasswordEncoder} implementations will short circuit if the password is
     * not in a valid format.
     */
    private String userNotFoundEncodedPassword;

    public CustomUserDetailsAuthenticationProvider(PasswordEncoder passwordEncoder,
            CustomUserDetailsService userDetailsService) {
        this.passwordEncoder = passwordEncoder;
        this.userDetailsService = userDetailsService;
    }

    /*
     * (non-Javadoc)
     * 
     * @see org.springframework.security.authentication.dao.
     * AbstractUserDetailsAuthenticationProvider#additionalAuthenticationChecks(org.
     * springframework.security.core.userdetails.UserDetails,
     * org.springframework.security.authentication.
     * UsernamePasswordAuthenticationToken)
     */
    @Override
    protected void additionalAuthenticationChecks(UserDetails userDetails,
            UsernamePasswordAuthenticationToken authentication) throws AuthenticationException {

        if (authentication.getCredentials() == null) {
            logger.debug("Authentication failed: no credentials provided");
            throw new BadCredentialsException(
                    messages.getMessage("AbstractUserDetailsAuthenticationProvider.badCredentials", 
                            "Bad credentials"));
        }
        // Get the password submitted by the end user
        String presentedPassword = authentication.getCredentials().toString();

        // If the password stored in the database and the user submitted password do not
        // match, then signal a login error
        if (!passwordEncoder.matches(presentedPassword, userDetails.getPassword())) {
            logger.debug("Authentication failed: password does not match stored value");
            throw new BadCredentialsException(
                    messages.getMessage("AbstractUserDetailsAuthenticationProvider.badCredentials", 
                            "Bad credentials"));
        }
    }

    @Override
    protected void doAfterPropertiesSet() throws Exception {
        Assert.notNull(this.userDetailsService, "A UserDetailsService must be set");
        this.userNotFoundEncodedPassword = this.passwordEncoder.encode(USER_NOT_FOUND_PASSWORD);
    }

    /*
     * (non-Javadoc)
     * 
     * @see org.springframework.security.authentication.dao.
     * AbstractUserDetailsAuthenticationProvider#retrieveUser(java.lang.String,
     * org.springframework.security.authentication.
     * UsernamePasswordAuthenticationToken)
     */
    @Override
    protected UserDetails retrieveUser(String username, UsernamePasswordAuthenticationToken authentication)
            throws AuthenticationException {
        CustomAuthenticationToken auth = (CustomAuthenticationToken) authentication;
        UserDetails loadedUser;

        try {
            loadedUser = this.userDetailsService
                    .loadUserByUsernameAndTenantname(auth.getPrincipal().toString(),
                            auth.getTenant());
        } catch (UsernameNotFoundException notFound) {
            if (authentication.getCredentials() != null) {
                String presentedPassword = authentication.getCredentials().toString();
                passwordEncoder.matches(presentedPassword, userNotFoundEncodedPassword);
            }
            throw notFound;
        } catch (Exception repositoryProblem) {
            throw new InternalAuthenticationServiceException(repositoryProblem.getMessage(), 
                    repositoryProblem);
        }

        if (loadedUser == null) {
            throw new InternalAuthenticationServiceException(
                    "UserDetailsService returned null, "
                    + "which is an interface contract violation");
        }
        return loadedUser;
    }
}

Conclusion of Part 1

In this part of the blog post, I have explained how this application works, how to set up your project, how Spring Security is set up.

In the next part, I will show how the JPA and Hibernate part of the code is set up. Also I will show how Spring Security is tied in with the multi-tenancy Hibernate code.

Part 2

Building SaaS style multi-tenant web app with Spring Boot 2 and Spring Security 5 - Part 2

noreply@blogger.com (Sunit) — Wed, 11 Apr 2018 04:10:00 +0000

Continuing from part 1

In part 1 of this blog post, I shared how you can build a SaaS style multi-tenant web application and how it works.

In this part of the blog post, I will continue to show how to set up multi-tenant database access to the tenant databases using Spring JPA and Hibernate. Also how Spring Security is tied into all of this.

Multi-Tenancy data access and tenant database selection

In multi-tenant setup, Hibernate requires a datasource to be fed so that it can establish a connection/session with the database defined by the datasource.

Data access

For a multi-tenancy setup, Hibernate provides two facilities -

CurrentTenantIdentifierResolver - an interface which should be implemented by the application code to identify the tenant
AbstractDataSourceBasedMultiTenantConnectionProviderImpl - an abstract class which provides support for providing the correct datasource based on the tenant id to Hibernate

Tenant identification and data source selection

In part 1 of the blog I had written that the tenant identifier is provided by the end user via the login form. The application code needs to parse this tenant field in the Spring Security layer and store it for tenant id resolution.

Spring provides a UsernamePasswordAuthenticationFilter which is extended by the example application to retrieve the tenant value from the login form. This tenant value is stored in a ThreadLocal variable so that it can be used by the CurrentTenantIdentifierResolver implementation.

Understanding the code used in the application

I will explain the significant pieces of code in this part of the blog post so that you can follow how it is all related and how it all works.

File: MultitenancyProperties.java

As shown in part 1, the application.yml defines the data sources for the tenant databases. These should be available to the application code. MultitenancyProperties class has the @ConfigurationProperties annotation and is asked to parse the properties under the multitenancy.app node from application.yml file.

package com.example.multitenancy;

import java.util.List;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

/**
 * This class reads the <code>multitenancy.mtapp</code> node from
 * <code>application.yml</code> file and populates a list of
 * {@link org.springframework.boot.autoconfigure.jdbc.DataSourceProperties}
 * objects, with each instance containing the data source details about the
 * database like url, username, password etc
 * 
 * @author Sunit Katkar
 * @version 1.0 
 * @since 1.0 (April 2018)
 */
@Configuration
@ConfigurationProperties("multitenancy.mtapp")
public class MultitenancyProperties {

    private List<DataSourceProperties> dataSourcesProps;

    public List<DataSourceProperties> getDataSources() {
        return this.dataSourcesProps;
    }

    public void setDataSources(List<DataSourceProperties> dataSourcesProps) {
        this.dataSourcesProps = dataSourcesProps;
    }

    public static class DataSourceProperties 
        extends org.springframework.boot.autoconfigure.jdbc.DataSourceProperties {

        private String tenantId;

        public String getTenantId() {
            return tenantId;
        }

        public void setTenantId(String tenantId) {
            this.tenantId = tenantId;
        }
    }
}

File: MultiTenancyJpaConfiguration.java

Hibernate needs to be fed with the datasource that it should connect to. MultiTenancyJpaConfiguration reads the data sources from MultitenancyProperties and creates a map of the data sources. This map is then used for selecting the required tenant database based on the tenant identifier and Hibernate establishes a connection with that database.

package com.example.multitenancy;

import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.Map;

import javax.persistence.EntityManagerFactory;
import javax.sql.DataSource;

import org.hibernate.MultiTenancyStrategy;
import org.hibernate.cfg.Environment;
import org.hibernate.context.spi.CurrentTenantIdentifierResolver;
import org.hibernate.engine.jdbc.connections.spi.MultiTenantConnectionProvider;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.orm.jpa.JpaProperties;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.boot.jdbc.DataSourceBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.orm.jpa.JpaTransactionManager;
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 com.example.model.Employee;
import com.example.multitenancy.MultitenancyProperties.DataSourceProperties;

/**
 * This class defines the data sources to be used for accessing the different
 * databases (one database per tenant). It generates the Hibernate session and
 * entity bean for database access via Spring JPA as well as the Transaction
 * manager to be used.
 * 
 * @author Sunit Katkar
 * @version 1.0
 * @since 1.0 (April 2018)
 */
@Configuration
@EnableConfigurationProperties({ MultitenancyProperties.class, JpaProperties.class })
@EnableTransactionManagement
public class MultiTenancyJpaConfiguration {

    @Autowired
    private JpaProperties jpaProperties;

    @Autowired
    private MultitenancyProperties multitenancyProperties;

    /**
     * Builds a map of all data sources defined the application.yml file
     * 
     * @return
     */
    @Primary
    @Bean(name = "dataSourcesMtApp")
    public Map<String, DataSource> dataSourcesMtApp() {
        Map<String, DataSource> result = new HashMap<>();
        for (DataSourceProperties dsProperties : this.multitenancyProperties.getDataSources()) {
            
            DataSourceBuilder factory = DataSourceBuilder.create()
                    .url(dsProperties.getUrl())
                    .username(dsProperties.getUsername())
                    .password(dsProperties.getPassword())
                    .driverClassName(dsProperties.getDriverClassName());
            
            result.put(dsProperties.getTenantId(), factory.build());
        }
        return result;
    }

    /**
     * Autowires the data sources so that they can be used by the Spring JPA to
     * access the database
     * 
     * @return
     */
    @Bean
    public MultiTenantConnectionProvider multiTenantConnectionProvider() {
        // Autowires dataSourcesMtApp
        return new DataSourceBasedMultiTenantConnectionProviderImpl();
    }

    /**
     * Since this is a multi-tenant application, Hibernate requires that the current
     * tenant identifier is resolved for use with
     * {@link org.hibernate.context.spi.CurrentSessionContext} and
     * {@link org.hibernate.SessionFactory#getCurrentSession()}
     * 
     * @return
     */
    @Bean
    public CurrentTenantIdentifierResolver currentTenantIdentifierResolver() {
        return new CurrentTenantIdentifierResolverImpl();
    }

    /**
     * org.springframework.beans.factory.FactoryBean that creates a JPA
     * {@link javax.persistence.EntityManagerFactory} according to JPA's standard
     * container bootstrap contract. This is the most powerful way to set up a
     * shared JPA EntityManagerFactory in a Spring application context; the
     * EntityManagerFactory can then be passed to JPA-based DAOs via dependency
     * injection. Note that switching to a JNDI lookup or to a
     * {@link org.springframework.orm.jpa.LocalEntityManagerFactoryBean} definition
     * is just a matter of configuration!
     * 
     * @param multiTenantConnectionProvider
     * @param currentTenantIdentifierResolver
     * @return
     */
    @Bean
    public LocalContainerEntityManagerFactoryBean entityManagerFactoryBean(
            MultiTenantConnectionProvider multiTenantConnectionProvider,
            CurrentTenantIdentifierResolver currentTenantIdentifierResolver) {

        Map<String, Object> hibernateProps = new LinkedHashMap<>();
        hibernateProps.putAll(this.jpaProperties.getProperties());
        hibernateProps.put(Environment.MULTI_TENANT, MultiTenancyStrategy.DATABASE);
        hibernateProps.put(Environment.MULTI_TENANT_CONNECTION_PROVIDER, multiTenantConnectionProvider);

        hibernateProps.put(Environment.MULTI_TENANT_IDENTIFIER_RESOLVER, currentTenantIdentifierResolver);

        // No dataSource is set to resulting entityManagerFactoryBean
        LocalContainerEntityManagerFactoryBean result = new LocalContainerEntityManagerFactoryBean();
        result.setPackagesToScan(new String[] { Employee.class.getPackage().getName() });
        result.setJpaVendorAdapter(new HibernateJpaVendorAdapter());
        result.setJpaPropertyMap(hibernateProps);

        return result;
    }

    /**
     * Interface used to interact with the entity manager factory for the
     * persistence unit.
     * 
     * @param entityManagerFactoryBean
     * @return
     */
    @Bean
    public EntityManagerFactory entityManagerFactory(LocalContainerEntityManagerFactoryBean 
            entityManagerFactoryBean) {
        return entityManagerFactoryBean.getObject();
    }

    /**
     * Creates a new
     * {@link org.springframework.orm.jpa.JpaTransactionManager#JpaTransactionManager(EntityManagerFactory emf)}
     * instance.
     * 
     * {@link org.springframework.transaction.PlatformTransactionManager} is the
     * central interface in Spring's transaction infrastructure. Applications can
     * use this directly, but it is not primarily meant as API: Typically,
     * applications will work with either TransactionTemplate or declarative
     * transaction demarcation through AOP.
     * 
     * @param entityManagerFactory
     * @return
     */
    @Bean
    public PlatformTransactionManager transactionManager(EntityManagerFactory entityManagerFactory) {
        return new JpaTransactionManager(entityManagerFactory);
    }
}

File: DataSourceBasedMultiTenantConnectionProviderImpl.java

Hibernate provides AbstractDataSourceBasedMultiTenantConnectionProviderImpl which provides support for connections in a multi-tenant setup like the example application.

DataSourceBasedMultiTenantConnectionProviderImpl extends the abstract class and implements the selectDataSource() and selectAnyDataSource() methods. This class basically does the job of selecting the correct database based on the tenant id found by the tenant id resolver, which I will show next.

package com.example.multitenancy;

import java.util.Map;

import javax.sql.DataSource;

import org.hibernate.engine.jdbc.connections.spi.AbstractDataSourceBasedMultiTenantConnectionProviderImpl;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

/**
 * This class does the job of selecting the correct database based on the tenant
 * id found by the {@link CurrentTenantIdentifierResolverImpl}
 * 
 * @author Sunit Katkar
 * @version 1.0
 * @since 1.0 (April 2018)
 */
@Component
public class DataSourceBasedMultiTenantConnectionProviderImpl
        extends AbstractDataSourceBasedMultiTenantConnectionProviderImpl {

    private static final long serialVersionUID = 1L;

    @Autowired
    private Map<String, DataSource> dataSourcesMtApp;

    /*
     * (non-Javadoc)
     * 
     * @see org.hibernate.engine.jdbc.connections.spi.
     * AbstractDataSourceBasedMultiTenantConnectionProviderImpl#selectAnyDataSource(
     * )
     */
    @Override
    protected DataSource selectAnyDataSource() {
        return this.dataSourcesMtApp.values().iterator().next();
    }

    /*
     * (non-Javadoc)
     * 
     * @see org.hibernate.engine.jdbc.connections.spi.
     * AbstractDataSourceBasedMultiTenantConnectionProviderImpl#selectDataSource(
     * java.lang.String)
     */
    @Override
    protected DataSource selectDataSource(String tenantIdentifier) {
        return this.dataSourcesMtApp.get(tenantIdentifier);
    }
}

File: CurrentTenantIdentifierResolverImpl.java

This class does the job of identifying the tenant. In the example application the tenant id is stored in a ThreadLocal variable which is accessed in this class and provided to Hibernate

package com.example.multitenancy;

import org.apache.commons.lang3.StringUtils;
import org.hibernate.context.spi.CurrentTenantIdentifierResolver;
import org.springframework.stereotype.Component;

import com.example.util.TenantContextHolder;

/**
 * Hibernate needs to know which database to use i.e. which tenant to connect
 * to. This class provides a mechanism to provide the correct datasource at run
 * time.
 * 
 * @see {@link com.example.util.TenantContextHolder}
 * @see {@link com.example.security.CustomAuthenticationFilter}
 * 
 * @author Sunit Katkar
 * @version 1.0
 * @since 1.0 (April 2018)
 */
@Component
public class CurrentTenantIdentifierResolverImpl implements CurrentTenantIdentifierResolver {

    private static final String DEFAULT_TENANT_ID = "tenant_1";

    /*
     * (non-Javadoc)
     * 
     * @see org.hibernate.context.spi.CurrentTenantIdentifierResolver#
     * resolveCurrentTenantIdentifier()
     */
    @Override
    public String resolveCurrentTenantIdentifier() {
        // The tenant is stored in a ThreadLocal before the end user's login information
        // is submitted for spring security authentication mechanism. Refer to
        // CustomAuthenticationFilter
        String tenant = TenantContextHolder.getTenant();
        return StringUtils.isNotBlank(tenant) ? tenant : DEFAULT_TENANT_ID;
    }

    /*
     * (non-Javadoc)
     * 
     * @see org.hibernate.context.spi.CurrentTenantIdentifierResolver#
     * validateExistingCurrentSessions()
     */
    @Override
    public boolean validateExistingCurrentSessions() {
        return true;
    }

}

Please note the yellow highlighted line in the code above which retrieves the tenant identifier. I will explain how it was stored and retrieved in the next file description.

File: TenantContextHolder.java

When Spring Security parses the login form which has the extra 'tenant' field, the field value is important. This value is the tenant identifier which will Hibernate which data source to use to connect to the desired tenant database.

ThreadLocal is a good solution to storing this tenant identifier. Please refer to the javadocs for a detailed explanation and some example code to understand the concept if you are new to it.

The following diagram shows how the tenant id is retrieved from the login form and stored in a ThreadLocal variable and finally retrieved from this variable to identify the tenant database.

ThreadLocal storage to store and retrieve tenant identifier

The example application uses the following code for a ThreadLocal variable

package com.example.util;


/**
 * When the end user submits the login form, the tenant id is required to
 * determine which database to connect to. This needs to be captured in the
 * spring security authentication mechanism, specifically in the
 * {@link UsernamePasswordAuthenticationFilter} implemented by
 * {@link CustomAuthenticationFilter}. This tenant id is then required by the
 * {@link CurrentTenantIdentifierResolver} implemeted by the
 * {@link CurrentTenantIdentifierResolverImpl}
 * 
 * <br/>
 * <br/>
 * <b>Explanation:</b> Thread Local can be considered as a scope of access, like
 * a request scope or session scope. It’s a thread scope. You can set any object
 * in Thread Local and this object will be global and local to the specific
 * thread which is accessing this object. Global and local at the same time? :
 * 
 * <ul>
 * <li>Values stored in Thread Local are global to the thread, meaning that they
 * can be accessed from anywhere inside that thread. If a thread calls methods
 * from several classes, then all the methods can see the Thread Local variable
 * set by other methods (because they are executing in same thread). The value
 * need not be passed explicitly. It’s like how you use global variables.</li>
 * <li>Values stored in Thread Local are local to the thread, meaning that each
 * thread will have it’s own Thread Local variable. One thread can not
 * access/modify other thread’s Thread Local variables.</li>
 * </ul>
 * 
 * @see https://dzone.com/articles/painless-introduction-javas-threadlocal-storage
 * @author Sunit Katkar
 * @version 1.0
 * @since 1.0 (April 2018)
 */
public class TenantContextHolder {

    private static final ThreadLocal<String> CONTEXT = new ThreadLocal<>();

    public static void setTenantId(String tenant) {
        CONTEXT.set(tenant);
    }

    public static String getTenant() {
        return CONTEXT.get();
    }

    public static void clear() {
        CONTEXT.remove();
    }
}

These are the significant files for the application. The application described in this blog post is checked into GitHub where you can see other code not explained here.

Modifying the Spring Boot main application class

Typically, the Spring Boot main application class is nothing special as it has a main method which starts the application. But there is a lot of Spring Boot magic going on behind the scenes. A lot of defaults are assumed, a lot of configurations are done automatically by detecting artifacts in the classpath, application properties file and pom.xml analysis.

If you are familiar with Spring Boot and JPA or even JDBC, then you know that any mention of spring jpa properties in the application properties file will cause Spring Boot to automatically configure the datasource. In this web application, we dont want Spring Boot to configure the data sources because we want to define multiple data sources and there is no default data source available when the application starts. Only when a user logs in with tenant information, the correct datasource needs to be used to connect to the tenant database.

So, using a simple exclude attribute to exclude the DataSourceAutoConfiguration class in the main @SpringBootApplication annotation, we can tell Spring Boot to leave data source configuration aside.

Since we have asked Spring Boot to not do some auto configuration related to data sources, it is a good idea to specifically ask Spring Boot to enable JPA Repositories using the @EnableJpaRepositories annotation.

package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;

/**
 * @author Sunit Katkar
 * @version 1.0
 * @since 1.0 (April 2018)
 */
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
@EnableJpaRepositories("com.example.repository")
public class MultitenancyMySqlApplication {

    public static void main(String[] args) {
        SpringApplication.run(MultitenancyMySqlApplication.class, args);
    }
}

Sample SQL to create a tenant database on MySQL

Had this example been set up as a single database application and the property spring.jpa.hibernate.ddl-auto set to create or update, then the following three tables would be generated automatically by Hibernate based on the JPA entity definitions. Read more about it here.

Table: User

CREATE TABLE `user` (
 `user_id` INT(11) NOT NULL,
 `password` VARCHAR(255) NOT NULL,
 `username` VARCHAR(255) NOT NULL,
 `active` BIT(1) NULL DEFAULT NULL,
 `tenant` VARCHAR(255) NULL DEFAULT NULL,
 PRIMARY KEY (`user_id`)
)
COLLATE='latin1_swedish_ci'
ENGINE=MyISAM
;

Table: Role

CREATE TABLE `role` (
 `role_id` INT(11) NOT NULL,
 `role` VARCHAR(255) NULL DEFAULT NULL,
 PRIMARY KEY (`role_id`)
)
COLLATE='latin1_swedish_ci'
ENGINE=MyISAM
;

Table: User_Role

This is the mapping table where users and roles are recordeed

CREATE TABLE `user_role` (
 `user_id` INT(11) NOT NULL,
 `role_id` INT(11) NOT NULL,
 PRIMARY KEY (`user_id`, `role_id`),
 INDEX `FKa68196081fvovjhkek5m97n3y` (`role_id`)
)
COLLATE='latin1_swedish_ci'
ENGINE=MyISAM
;

Resources

The complete source code is checked into GitHub. Its a standard Maven project which you can import into your IDE.

Conclusion

I have explained multi-tenancy and shown you with example code how you can build a SaaS style 'tenant per database' multi-tenant web application with Spring Boot; and how to secure it with Spring Security. I will write about adapting this code to use Microsoft SQL Server in a future blog post as there were some challenges and how I had to change some code to overcome them.

Please do let me know your feedback by adding it in the comments section below. I am sure I will learn something new.

Happy coding :)

Small JSON utility methods for your Spring Boot app

noreply@blogger.com (Sunit) — Wed, 24 Jan 2018 00:28:00 +0000

JSON is almost the lingua-franca when it comes to communication between web-services or Ajax based browser to server communication, though its not limited to just these two.

There are many good JSON utilities and libraries like the the faster jackson library. The maven repository page is here.

Purpose of this blog post

I am sharing two simple methods which I have used and continue to use a lot in all my projects requiring JSON. I understand that there maybe better versions and utilities out there, but I wanted to share what I learnt and developed and use in my work.

Using Faster Jackson in your Spring Boot app

Include the following dependency in your pom.xml

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
</dependency>

In your project's utility class, you can add the following methods - to convert to and from JSON.

Method 1 - To convert a JSON string to a Java POJO.

This is typically useful when the browser sends back form data to the server and you want to process it and convert it to a POJO.

/**
 * Converts a JSON string to a Java POJO
 * 
 * @param json
 *            the JSON string
 * @param clazz
 *            the class of the POJO that will be returned
 * @return instance of T
 */
public static <T> T fromJson(String json, Class<T> clazz) {
    ObjectMapper mapper = new ObjectMapper();
    mapper.configure(DeserializationFeature.FAIL_ON_IGNORED_PROPERTIES, false)
            .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false)
            .configure(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY, true);
    try {
        return (T) mapper.readValue(json, clazz);
    } catch (IOException e) {
        LOG.error(e.getMessage(), e);
    }
    return null;
}

Method 2 - To convert a POJO to a JSON string

This is typically useful when the server sends data back to the browser. Notice that you can send back JSON as a simple String or with proper indentations and line feeds so that the string prints out a well formatted JSON.

/**
 * Convert a Java POJO to a JSON string
 * 
 * @param obj
 *            the Java POJO
 * @param prettyPrint
 *            if true then the string will be indented and the 
 *            {@link ObjectMapper#writerWithDefaultPrettyPrinter()}
 *            will be used to generate a well formatted human 
 *            readable JSON string
 * @return String in json format
 */
public static String toJson(Object obj, boolean prettyPrint) {
    ObjectMapper mapper = new ObjectMapper();
    mapper.configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false);
    String s = null;
    try {
        s = prettyPrint ? mapper.writerWithDefaultPrettyPrinter().writeValueAsString(obj)
                : mapper.writeValueAsString(obj);
    } catch (JsonProcessingException e) {
        LOG.error(e.getMessage(), e);
    }
    return s;
}

Happy coding :)

Setting the timezone for your Spring Boot app

noreply@blogger.com (Sunit) — Tue, 23 Jan 2018 19:40:00 +0000

Purpose of this blog post

Today all non-trivial web applications and web services get deployed in the cloud. One cannot be very sure in which time zone the app is deployed. But sometimes, the app needs to record everything like log statements, database CRUD operations, etc using a specific time zone. Usually using the UTC time zone works best for such applications.

Setting the time zone

This short blog post is a way to show how this can be achieved in a java application, specifically a Spring or Spring Boot application.

There are many ways to do it like passing arguments to the JVM at start time which sets the time zone.

Example

java -Duser.timezone=PST ... <app-main-class>

But this is not the best solution as your app might not be the only application running on the JVM. There might be other apps running there too.

Setting time zone easily in Spring Boot

Add the following snippet to your Spring Boot application, typically in the main application class to set the desired time zone. The snippet shows the UTC time zone.

Example

import java.util.TimeZone;
import javax.annotation.PostConstruct;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(Ver3Application.class, args);
    }
    
    @PostConstruct
    void setUTCTimeZone(){
        TimeZone.setDefault(TimeZone.getTimeZone("UTC"));
    }
}

Happy coding :)

Some utility methods when writing Salesforce APEX code

noreply@blogger.com (Sunit) — Sat, 30 Dec 2017 01:51:00 +0000

Purpose of this blog post

When you work with Salesforce APEX language you come across the Salesforce Object Query Language or SOQL. Any non-trivial APEX script will have some SOQL in it. SOQL is like the standard SQL but with some differences which are more suited to accessing and manipulating Salesforce objects and records.

I found that I needed a few things always in APEX scripts and so extracted them into a utility class. This short blog post is about these code snippets which I have collected in my utility class.

Many of you are seasoned Salesforce professionals, but I thought of putting these simple utility methods on my blog for quick reference when I need them and for others who might shave off some time of their development work.

A note about Salesforce APEX Exceptions

In other programming languages like Java you can throw the provided exceptions like

throw new IllegalArgumentException(...);

But in APEX you can catch but cannot throw provided exceptions.

So for my utility class, I created a simple exception using an existing APEX exception, like this

public class UtilityException extends Exception{
}

I then use this exception for throwing my custom exception when I catch an APEX exception like DMLException, etc. Or I can throw this custom exception just like I would in a Java based method when some arguments are missing. Do read the link to get a full understanding of APEX exceptions.

Tip: You can also include the above class definition within your Utility class and refer to it in the class. There is no strict requirement for it to be in a separate class file of its own. For readability and good code layout, I prefer to keep it in its own separate class file UtilityException.apxc

Getting all fields of an object for a SOQL Select statement OR Select * for SOQL

The first thing you notice when working with SOQL to select is that there is no SQL equivalent of 'SELECT * FROM ...'. With SQL, using 'Select * From' is so common.

In SOQL you have to know the fields in an object to use them in your SELECT statement, but what if you just wanted to have all the fields in your statement like the SQL SELECT *. The following method uses the Salesforce API to get you just that.

Tip: Do look up the documentation for Schema as that's what is in use here to get all the fields.

    /**
     * Provides a list of all fields in a Custom Object
     *
     * @param sObjName - custom object name in string format e.g. 'Account'
     * @return - Returns List of all fields in a custom object
     */
    public static List<String> getAllFieldsForSObject(String sObjName){
        if(String.isBlank(sObjName)){
            throw new UtilityException('Argument \'sObjName\' missing. '
                    + 'Custom Object Name is required');
        }
        List<String> fieldList = 
                new List<String>(Schema.getGlobalDescribe()
                                .get(sObjName)
                                .getDescribe()
                                .fields.getMap()
                                .keySet());
        return fieldList;
    }
    /**
     * Provides a SOQL equivalent of the SQL 'SELECT * FROM ..' statement.
     *
     * @param sObjName - custom object name in string format e.g. 'Account'
     * @return - Returns 'SELECT <field1>, <field2>,... FROM sObjName'
     */
    public String getAllFieldsInSOQLSelect(String sObjName){
        if(String.isBlank(sObjName)){
            throw new UtilityException('Argument \'sObjName\' missing. ' 
                    + 'Custom Object Name is required');
        }
        List<String> fieldList = getAllFieldsForSObject(sObjName);
        String fields = String.join(fieldList,',');
        String soqlQuery = 'SELECT ' + fields + ' FROM ' + sObjName;
        return soqlQuery;
    }
    
    //Example usage:
    //String selectSOQL = getAllFieldsInSOQLSelect('Account');

Getting the field type of a custom object

Sometimes, you have to know the data type of a field in a custom object. Well, you can see your custom object with all its fields and relationships in the Salesforce org UI, but when writing APEX scripts or when using the Salesforce SOAP API, you want to know the field type.

I needed to get a simple idea if a field was a String, a Number, a Date or a DateTime. So I wrote this simple method which does the job. You can always improvise on it, but do let me know so that I can post it here and also use it for my work :)

/**
 * Provides the type of a field on a custom object. 
 * 
 * @param sObjName - custom object name in string format e.g. 'Opportunity'
 * @param fieldName - custom object field name in string format e.g. 'Area__c'
 * 
 * @return - Returns 'STRING' or 'DATE' or 'DATETIME' or 'NUMBER'
 */ 
public static String getFieldType(String sObjName, String fieldName){
    String fieldType = '';
    
    if(String.isBlank(sObjName)){
        throw new UtilityException('Argument \'sObjName\' missing. ' 
                    + 'Custom Object Name is required');
    }
    if(String.isBlank(fieldName)){
        throw new UtilityException('Argument \'fieldName\' missing. ' 
            + 'Custom Object Field Name is required');
    }
    
    Schema.SObjectType objType = Schema.getGlobalDescribe().get(sObjName);
    Schema.DescribeSObjectResult descObjResult = objType.getDescribe();
    Schema.DescribeFieldResult field = descObjResult.fields.getMap()
                                        .get(fieldName)
                                        .getDescribe();
    
    if(field.getType() == Schema.DisplayType.DATE){
        fieldType = 'DATE';
    } else if(field.getType() == Schema.DisplayType.DATETIME){
        fieldType = 'DATETIME';
    } else if(field.getType() == Schema.DisplayType.DOUBLE || 
              field.getType() == Schema.DisplayType.INTEGER){
        fieldType = 'NUMBER';
    } else if(field.getType() == Schema.DisplayType.ADDRESS || 
              field.getType() == Schema.DisplayType.STRING || 
              field.getType() == Schema.DisplayType.PHONE ||
              field.getType() == Schema.DisplayType.TEXTAREA ||
              field.getType() == Schema.DisplayType.PICKLIST){
                  fieldType = 'STRING';
              }
    return fieldType;
}

Finding the duration between two dates

This is a standard requirement in many programming tasks to calculate the duration between two dates or the time elapsed between two dates. Other programming languages like Java have many utilities but here is something I wrote for APEX.

There are two main data types in APEX to deal with date and time - Time and DateTime. I have used these to come up with these utility methods. Do read up on these and you might get some more utility methods out of it.

/**
 * Provides the Time between two times - startTime and endTime
 * @param startTime - the start time
 * @param endTime - the end time
 * @return - the duration between two Time instances 
 */
public static Time GetTimeBetween(Time startTime, Time endTime){
    if(startTime == null || endTime == null){
        return Time.newInstance(0, 0, 0, 0);
    }
    
    Integer elapsedHours = endTime.hour() - startTime.hour();
    Integer elapsedMinutes = endTime.minute() - startTime.minute();
    Integer elapsedSeconds = endTime.second() - startTime.second();
    Integer elapsedMiliseconds = endTime.millisecond() - startTime.millisecond();
    
    return Time.newInstance(elapsedHours, elapsedMinutes, 
                    elapsedSeconds, elapsedMiliseconds);
}

/**
 * Provides the Time between two DateTimes - startTime and endTime
 * @param startDate - the start date
 * @param endDate - the end date
 * @return - the duration between two DateTime instances
 */
public static Time GetTimeBetweenDates(DateTime startDate, DateTime endDate){
    if(startDate == null || endDate == null){
     return Time.newInstance(0, 0, 0, 0);
    }
    return GetTimeBetween(startDate.time(), endDate.time());
}

//Example Usage:
//DateTime startDate = DateTime.newInstance(2017, 12, 29, 20, 30, 00);
//DateTime endDate = DateTime.newInstance(2017, 12, 29, 21, 45, 00);
//Time duration = GetTimeBetweenDates(startDate, endDate);
//System.debug('Duration:' + duration); <-- Duration:01:15:00.000Z

Do let me know if you have some of your own APEX tips and tricks to share.

Happy APEX coding :)

Spring Boot RestTemplate to call Salesforce REST API

noreply@blogger.com (Sunit) — Tue, 21 Nov 2017 00:26:00 +0000

Purpose of this blog post

Using Spring Boot RestTemplate to communicate with a REST API is nothing new. There are many examples on the net. Using RestTemplate to communicate with a Salesforce REST API is also not new and there are many examples out there. This post is an attempt to share my learnings with many others who are not new to Spring Boot RestTemplate but maybe relatively new to the Salesforce REST API. Its my attempt to share the things I discovered and provide a quick way to accomplish this REST based communication.

Example Scenario

You have written a REST API in your Salesforce instance to get details of Accounts. You now want to use an external host like a Heroku hosted java application to query this API and get the results.

Prerequisites

I am assuming you are quite comfortable with Java and Spring Boot. I further assume that you are familiar with Salesforce and can find your way by reading the online documentation and help topics published by Salesforce.

Java

You know what you need, but I will list what I used

Spring STS IDE
Java 8
Spring Boot 1.5.6.RELEASE

I am assuming you are familiar with creating a Spring Boot starter project either in your STS IDE or from the Spring Initializr site.

Salesforce

I am assuming you have access to a Salesforce instance. If not, signup for a free developer edition. I further assume that you know how to create a connected app and write a simple Apex class with SOQL queries to query for standard or custom objects. This blog post cannot cover all the basics of Salesforce and the Apex programming language.

Steps to take on Salesforce side

You need to do two things on the salesforce side -

Create a new connected application or use an existing connected application.
Create a Apex class and expose it via the Salesforce REST API mechanism

Create a new connected application

Create a connected app and ensure that you enable OAuth. Details here.

Use an existing connected application

If you already have a connected app and have not enabled OAuth, then follow these steps

Click on the connected app name.

On the page showing your app details, look at the OAuth Policies section. For getting this example to work, ensure that the IP Relaxation has a value of "Relax IP restrictions".
What this means is that any host can connect with your app. Later on, you can fine tune access based on a set of IP addresses. (Initially, I was unable to connect to the REST API and received error messages when I called the API using CURL from the command line. Finally, I figured out that I needed to set this feature to relax the IP addresses which can call the Salesforce API.)
Now go the Setup page by clicking the link on the top right in the header of the page (next to your name. For the new Lightning Experience UI, this is in a drop down menu.).
Using the left search menu look for "Apps"
Click on the Apps option under the Build -> Create menu on the left side.
You should see your existing connected app listed in the Connected Apps section at the bottom of the page on the right side.
Once again, click on the name of your app to see the details page of your app
Click on the Edit button to edit your application settings
On the edit page, enable OAuth and enter data to make your app's OAuth settings look similar to this screen shot.

When you enable OAuth and click Save you should see the API (Enable OAuth Settings) section populated with important data which is required for connecting to your Salesforce REST API from an external REST client.
Copy the Consumer Key and store it safely. This will be the client_id will be used in the API client code for authentication
Click on the Click to reveal link next to the Consumer Secret to view the value and store it safely. This will be the client_secret which will be used in the API client code for authentication

Writing a Apex class and exposing it via REST

Its quite easy to write an Apex class and expose it via REST. The following example code returns just 2 Account objects when invoked via the REST url. You should refer the official Salesforce documentation for details.

Create a new Apex class, named anything you like, as follows using the Dev console.

 @RestResource(urlMapping = '/Account/*')  
 global with sharing class MyRestResource {  
   @HttpGet  
   global static List<Account> getAccounts() {  
     List<Account> result = [SELECT Id, Name, Phone, Website FROM Account LIMIT 2];  
     return result;  
   }  
 }

Now work is done from Salesforce side. If you are familiar with Curl then you can try calling this URL and test the response. Note that you will have to authenticate first to obtain a OAuth token to access the REST url.

Setting up the Spring Boot RestTemplate code

The following code is brief and meant to just shows how to authenticate and then access the REST url. I assume that you are familiar with creating a Spring Boot starter app.

Configure the Spring RestTemplate

Create a package called config , e.g. com.example.config in your project and copy paste the following class. This will set some defaults like timeout for attributes of the RestTemplate. For more details refer the Spring docs at this link.

import org.springframework.context.annotation.Bean;
import org.springframework.http.client.ClientHttpRequestFactory;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
import org.springframework.stereotype.Component;

@Component
public class RestTemplateConfig {
 
 @Bean
 public ClientHttpRequestFactory clientHttpRequestFactory() {
  int timeout = 5000;
  HttpComponentsClientHttpRequestFactory clientHttpRequestFactory = new HttpComponentsClientHttpRequestFactory();
  clientHttpRequestFactory.setConnectTimeout(timeout);
  clientHttpRequestFactory.setConnectionRequestTimeout(timeout);
  clientHttpRequestFactory.setReadTimeout(timeout);
  return clientHttpRequestFactory;
 }
}

Code that authenticates and calls the REST api

The following code will first authenticate with the Salesforce OAuth service and then call the REST url.

import java.util.Map;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestTemplate;

import com.salesforce.bigobjects.config.RestTemplateConfig;

@RestController
public class RestTemplateRequestToSalesforce {

 private static final Logger LOG = LoggerFactory.getLogger(RestTemplateRequestToSalesforce.class);

 // Inject the Rest template configuration
 @Autowired
 RestTemplateConfig restConfig;

 /**
  * Simple Rest end point in this app to demonstrate authenticating and then calling the Salesforce REST url
  * 
  * @return
  */
 @GetMapping("/accounts")
 public String callRestUrl() {

  // First define the OAuth2 token URL as follows by replacing YOUR_INSTANCE
  // with the actual instance that you have your org on
  String oauthUrl = "https://YOUR_INSTANCE.salesforce.com/services/oauth2/token";

  // Create a multi value map to put necessary attributes
  // for the authentication request
  MultiValueMap<String, String> mvMap = new LinkedMultiValueMap<>();
  mvMap.add("grant_type", "password");
  mvMap.add("client_id", "Your Client Id");
  mvMap.add("client_secret", "Your Client Secret");
  mvMap.add("username", "Your username");
  mvMap.add("password", "Your password");

  // Create an instance of the RestTemplate
  RestTemplate restTemplate = new RestTemplate(restConfig.clientHttpRequestFactory());

  // Send the REST request to get authenticated and receive an OAuth token
  Map<String, String> token = (Map<String, String>) restTemplate.postForObject(oauthUrl, mvMap, Map.class);
  LOG.info("--------------------------------------------");
  LOG.info("Access Token  :: " + token.get("access_token"));
  LOG.info("Instance Url  :: " + token.get("instance_url"));
  LOG.info("Id  :: " + token.get("id"));
  LOG.info("Token_Type  :: " + token.get("token_type"));
  LOG.info("Signature  :: " + token.get("signature"));
  LOG.info("--------------------------------------------");

  // The oauth token is now required for all further calls to the REST resources
  String oauthToken = token.get("access_token");

  // The REST url of your Salesforce Apex class will be of the form
  String restUrl = "https://YOUR_ISTANCE.salesforce.com/services/apexrest/Account";

  // Create Http headers and add the oauth token to them
  HttpHeaders restHeaders = new HttpHeaders();
  restHeaders.setContentType(MediaType.APPLICATION_JSON);
  restHeaders.add("X-PrettyPrint", "1");
  restHeaders.add("Authorization", "OAuth " + oauthToken);

  // Create a Multi value map in case there are query params. In this example
  // there are none so just an empty map is okay
  MultiValueMap<String, String> mv2Map = new LinkedMultiValueMap<>();

  // Following example code is using the RestTemplate exchange(..) method for making a GET request
  // Other methods like getForEntity() or getForObject() can also be used.
  HttpEntity<?> restRequest = new HttpEntity<>(mv2Map, restHeaders);
  RestTemplate getRestTemplate = new RestTemplate(restConfig.clientHttpRequestFactory());
  // Make a request and read the response string
  ResponseEntity<String> responseStr = getRestTemplate.exchange(restUrl, HttpMethod.GET, restRequest,
    String.class);

  // Return just the body of the response. You can examine the headers, etc if you wish
  HttpStatus responseStatus = responseStr.getStatusCode();
  HttpHeaders responseHeaders = responseStr.getHeaders();
  String responseBody = responseStr.getBody();
  LOG.info("REST API response:" + responseBody);
  return responseBody;
 }
}

Summary

The code is quite straightforward. Authenticate and obtain an OAuth token. Use this token is subsequent requests.

Sending form data as a custom object to a Spring MVC Controller

noreply@blogger.com (Sunit) — Mon, 23 Oct 2017 21:53:00 +0000

Form Data and Spring MVC Controllers

In a Spring MVC application, sending form data to the controller is quite well known and trivial. Typically all data gets sent as a bunch of key=value pairs. Each key is a request param which can be captured in the Controller using the @RequestParam("key") String key construct in the method signature.

If the number of fields are less, then you can use the request param construct to capture each form field, but if there are several form fields, then using this approach can create a unwieldy method signature and create room for error.

There are several ways to collect form data but in this post, I am going to address one specific use case.

Motivation for this post

Recently, someone at work asked me how to send data so that it was received by the Spring controller as a custom object/Pojo. I suggested using javascript to massage and format the data as desired and then send it.

Now using jquery forms on the browser side you can send data in any format after converting it to a JSON string.

For some business reasons, javascript was not an option. The HTML form had to be submitted as is using traditional http post method.

The purpose of this short blog post is to demonstrate how to send data from the browser without the help of javascript or any jquery plugins. This is typically useful when you have checkboxes and radio buttons in the UI and there is a relation between them.

Example

I have created an example UI which shows the kind of form that was to be submitted and then the controller code which processes the http post of this form.

As you can see, this form shows a list of car makes and their colors. The idea is that the user will check a checkbox for a car make and then select a color using the radio buttons.

Note that this form is rendered on the server side by reading the car makes and colors and then sent as a HTML page to the browser.

The HTML generated for this form is like this

 <form name="customObjectForm" id="customObjectForm" method="post" action="/submit">  
   <table class="table table-striped table-condensed table-bordered">  
     <thead>  
       <tr>  
         <th>Vehicle</th>  
         <th>Select</th>  
         <th>Color</th>  
       </tr>  
     </thead>  
     <tbody>  
       <tr>  
         <td>Toyota Camry</td>  
         <td><input type="checkbox" name="carModel" value="Camry" /></td>  
         <td>  
           <input type="radio" name="colors[Camry]" value="RED" /> RED &nbsp;  
           <input type="radio" name="colors[Camry]" value="YELLOW" /> YELLOW&nbsp;  
           <input type="radio" name="colors[Camry]" value="GREEN" /> GREEN&nbsp;  
         </td>  
       </tr>  
       <tr>  
         <td>Honda Civic</td>  
         <td><input type="checkbox" name="carModel" value="Honda" /></td>  
         <td>  
           <input type="radio" name="colors[Honda]" value="BLUE" /> BLUE&nbsp;  
           <input type="radio" name="colors[Honda]" value="BLACK" /> BLACK&nbsp;  
           <input type="radio" name="colors[Honda]" value="GREEN" /> GREEN&nbsp;  
         </td>  
       </tr>  
     </tbody>  
     <tfoot>  
       <tr><td colspan="3"><input type="Submit" name="submit" class="btn btn-primary" /></td></tr>  
     </tfoot>  
   </table>  
 </form>

Domain model

If you examine the HTML, you will notice that we can infer a Key Value pair type relationship between the car make and the color options. To relate the car make to the colors, the name of the radio buttons is named like an associative array with the car make as the value of the colors variable.

The car make checkboxes can be represented as a List in the domain model. If a user checks a checkbox then that checkbox value is submitted by the form, otherwise it is not.

Next, the row showing color options must be related to the car make in the domain model. To make that happen, the radio button selection can be submitted as a Map in the domain model.

So the car model can be a List<String> carMakes and the car colors can be a Map<String, String> colors where the key is the car make and the value is the actual selected color.

There can be a better domain model created and the HTML can be structured accordingly, but this is a quick example to show how Spring can convert browser submitted values in ready to use custom objects that you define.

Here is the CarMakeColorModel domain object / POJO.

package com.example.formobjects.model;

import java.util.List;
import java.util.Map;

public class CarMakeColorModel {

 // for the checkboxes for selecting the car makes
 private List<String> carMakes;

 // for the radio buttons to select the car color
 private Map<String, String> colors;

 public CarMakeColorModel() {
  // default constructor
  super();
 }

 public CarMakeColorModel(List<String> carMakes, Map<String, String> colors) {
  super();
  this.carMakes = carMakes;
  this.colors = colors;
 }

 public List<String> getCarMakes() {
  return carMakes;
 }

 public void setCarMakes(List<String> carMakes) {
  this.carMakes = carMakes;
 }

 public Map<String, String> getColors() {
  return colors;
 }

 public void setColors(Map<String, String> colors) {
  this.colors = colors;
 }

}

On the Controller side, use the @ModelAttribute annotation to make Spring collect all the form submitted values and populate the CarMakeColorModel pojo.

And here is the Spring Controller snippet which processes this HTML form.

package com.example.formobjects.controllers;

import java.util.List;
import java.util.Map;

import javax.servlet.http.HttpServletRequest;

import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

import com.example.formobjects.model.CarMakeColorModel;

/**
 * Controller to handle the form submission
 * 
 * @author <a href="mailto:sunitkatkar@gmail.com">Sunit Katkar</a>
 * @version 1.0
 * @since Oct 2017
 */
@Controller
public class FormCustomObjectController {

 @RequestMapping(value = "/", method = RequestMethod.GET)
 public String index(ModelMap modelMap) {
  return "index";
 }

 @RequestMapping(value = "/submit", method = RequestMethod.POST)
 public String submit(HttpServletRequest request, ModelMap modelMap,
   @ModelAttribute CarMakeColorModel carMakeColorModel) {

  List<String> carMakes = carMakeColorModel.getCarMakes();
  Map<String, String> carColors = carMakeColorModel.getColors();
  for (String carModel : carMakes) {
   String color = carColors.get(carModel);
   System.out.println("Car make:" + carModel + " Car color:" + color);
  }
  return "index";
 }

}

What I have shown is a known way of processing forms completely on the server side without aid of javascript. Though many of you know this technique, I am sure there are some out there, like my colleague, who are not aware of this; hence this post.

That's all there is to it. Happy coding :)

Preventing caching of static resources in Spring MVC legacy projects using XML config

noreply@blogger.com (Sunit) — Tue, 26 Apr 2016 06:05:00 +0000

Update (11 Sep 2018)

For Spring Boot 2, an updated version is available here

Do read this post first to understand how Spring handles resource url encoding and then proceed to the updated version.

Resource caching

Browsers typically cache static resources like javascript, css and image files. This is good as your app loads faster after the initial download of such resources. The next time around, if the resources have not changed, then the browser just fetches these from the cache.

Problems arise when you release the next version of your web application and the javascript, css or image files have changed. The browser will tend to get the files from it's own cache.

Well you know all of this, but I am just stating it here.

Preventing browser caching

Typical web applications, built using different technologies like PHP, Python, Java Servlets, etc usually employ a simplistic approach of including a query parameter after the javascript file. This version is then changed for every release.

Example:

<script href="/resources/scripts/myjscript.js?v=1.1"></script>

But this is mainly a manual process, though smart usage of build properties and build scripts can automate this to quite an extent. Spring does this versioning automatically for you and you need not make any special changes to your maven/gradle build scripts nor perform manual update of version numbers in any properties file.

Spring 4.1 offers an effective yet simple to setup way

Spring can create fingerprints of your resource - javascript, css and image - urls. By fingerprints, it means that your url will have a MD5 hash in it. This hash is created by MD5 one-way hashing of the contents of your resource.

Example:

/resources/scripts/cachebuster2-36ed9000c1c01d0f17d42b18c814dcdb.js

All this is possible due to the ResourceUrlEncodingFilter and any one of the version resolvers like VersionResourceResolver introduced in Spring 4.1. This official Spring blog post will give you a clear idea. You should also read the Spring documentation on static content serving and the new facilities you get.

Why bother with XML config?

Since Spring Boot has caught on rapidly, all new projects, examples and tutorials use the Java config way of configuring the application. But in an organisation there are legacy applications which were built using XML config. You do not have the luxury of updating the application by using Java Config.

I have seen applications which use Spring 4.x and XML configuration though Java config has existed for some time before Spring 4. Sometimes, developers are used to the XML config and feel more comfortable using it. The reasons maybe many, but XML configs exist and will continue to for some time in the future.

Note:
For those who want to do this using Java config, I have included a link to a very good tutorial on how to achieve this using Java config at the end of this blog post.

What you need to do to bust that browser cache

So, without further ado, this is what you need to do

Modify your web.xml to register a ResourceUrlEncodingFilter
Configure any of the provided ResourceResolvers
Use the Spring tag or the JSTL tag to inject URLs of your static resources in your JSP page

Step 1: Modify the web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

 <!-- The definition of the Root Spring Container shared by all Servlets 
  and Filters -->
 <context-param>
  <param-name>contextConfigLocation</param-name>
  <param-value>/WEB-INF/spring/root-context.xml</param-value>
 </context-param>

 <!-- Creates the Spring Container shared by all Servlets and Filters -->
 <listener>
  <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
 </listener>
          <!-- Add the ResourceUrlEncodingFilter -->
<filter>
  <filter-name>resourceUrlEncodingFilter</filter-name>
  <filter-class>org.springframework.web.servlet.resource.ResourceUrlEncodingFilter</filter-class>
 </filter>
 <!-- Ensure that you map it to the DispatcherServlet -->
 <filter-mapping>
  <filter-name>resourceUrlEncodingFilter</filter-name>
  <servlet-name>appServlet</servlet-name>
 </filter-mapping>
        
<!-- Processes application requests -->
 <servlet>
  <servlet-name>appServlet</servlet-name>
  <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
  <init-param>
   <param-name>contextConfigLocation</param-name>
   <param-value>/WEB-INF/spring/appServlet/servlet-context.xml</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
 </servlet>

 <servlet-mapping>
  <servlet-name>appServlet</servlet-name>
  <url-pattern>/</url-pattern>
 </servlet-mapping>
</web-app>

Step 2: Configure the ResourceResolver in the application context xml file

<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns:mvc="http://www.springframework.org/schema/mvc"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:beans="http://www.springframework.org/schema/beans"
 xmlns:context="http://www.springframework.org/schema/context"
 xsi:schemaLocation="http://www.springframework.org/schema/mvc 
      http://www.springframework.org/schema/mvc/spring-mvc.xsd
      http://www.springframework.org/schema/beans 
      http://www.springframework.org/schema/beans/spring-beans.xsd
      http://www.springframework.org/schema/context 
      http://www.springframework.org/schema/context/spring-context.xsd">

 <!-- DispatcherServlet Context: defines this servlet's request-processing 
  infrastructure -->

 <!-- Enables the Spring MVC @Controller programming model -->
 <mvc:annotation-driven />
         <!-- Handles HTTP GET requests for /resources/** by efficiently serving up static resources in the 
                ${webappRoot}/resources directory. The resolvers help in adding either a version number or a 
                hash to the javascript, css, image urls to prevent browser caching -->
<mvc:resources mapping="/resources/**" location="/resources/">
  <mvc:resource-chain resource-cache="true"
   auto-registration="true">
   <mvc:resolvers>
    <mvc:version-resolver>
     <mvc:content-version-strategy
      patterns="/**" />
     <!-- <mvc:fixed-version-strategy version="1.1.1" patterns="/**"/> -->
    </mvc:version-resolver>
   </mvc:resolvers>
  </mvc:resource-chain>
 </mvc:resources>
        
 <!-- Resolves views selected for rendering by @Controllers to .jsp resources 
  in the /WEB-INF/views directory -->
 <beans:bean
  class="org.springframework.web.servlet.view.InternalResourceViewResolver">
  <beans:property name="prefix" value="/WEB-INF/views/" />
  <beans:property name="suffix" value=".jsp" />
 </beans:bean>

 <context:component-scan base-package="com.blogspot.sunitkatkar" />
</beans:beans>

Step 3: Use the JSTL or Spring tags for URLs in your JSP pages

<!DOCTYPE html>
<%@ page language="java" contentType="text/html; charset=UTF-8"pageEncoding="UTF-8"%>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core"%>
<%@ taglib prefix="spring" uri="http://www.springframework.org/tags"%>
<spring:url value="/resources/scripts/cachebuster2.js" var="cachebusterjs" />
<c:url value="/resources/styles/cachebuster2.css" var="cachebustercss" />

<html>
<head>
<title>Spring MVC Resource Versioning</title>
<script src="https://code.jquery.com/jquery-2.2.3.min.js"
 integrity="sha256-a23g1Nt4dtEYOj7bR+vTu7+T8VP13humZFBJNIYoEJo="
 crossorigin="anonymous"></script>
<script src="${cachebusterjs}"></script>
<link href="${cachebustercss}" rel="stylesheet" />
</head>
<body>
 <h1>Hello versioned static resources world!</h1>
 <h4>The time on the server is ${serverTime}.</h4>
 <p>JS url: ${cachebusterjs}</p>
 <p>CSS url: ${cachebustercss}</p>
 <p>
  <button id="btnWelcome">Click Me</button>
 </p>
</body>
</html>

Results

If you run the project, you should see the main screen as below:

Resources

The above code has been uploaded as an example project "cachebuster2" on github.
If you want to do this using Java config, this is a good example.

Spring 4 WebSockets with SockJS, STOMP and Spring Security 3.2

noreply@blogger.com (Sunit) — Wed, 15 Jan 2014 12:52:00 +0000

What are WebSockets?

You may already know this, but I’m adding an excerpt from Wikipedia.

WebSocket is a protocol providing full-duplex communications channels over a single TCP connection. The WebSocket protocol was standardized by the IETF as RFC 6455 in 2011.

Modern browsers like Google Chrome and FireFox have been supporting WebSockets for some time now.

Spring 4 and WebSockets

Spring has grown to be a full fledged Enterprise solution. The latest offering of interest in Spring 4 is the implementation of the WebSocket specification as per JSR 356. Oracle has already published a tutorial on how to use the Java (Java EE 7.0) implementation of JSR 356. But I prefer to use the Spring 4 implementation so that it fits snugly in the Spring based ecosystem already in place.

This diagram depicts what I have understood on how WebSockets work. Traditional HTTP is a Request and Response based system. WebSockets is a full duplex communication channel. Its like opening a socket connection from the browser to the web server. Usually you need a thick client like a Java applet or an ActiveX plugin to create and open a socket connection from the browser to the web server. With WebSockets this ‘socket connection’ is now provided by the browser and understood by the server. Please do not confuse WebSockets with TCP connections. Differences between these two are well explained in these stackoverflow answers here and here.

Http uses the http:// and https:// for regular and secured connections respectively from the browser to the web server. With WebSockets you use the ws:// and wss:// for regular and secured connections respectively.

Obviously you are not going to replace http:// with ws:// in the browser’s address bar as you explore using WebSockets as an alternative to the prevalent Ajax communication. Read more on this topic here.

Why should we bother about WebSockets? It’s just another transport mechanism …

Do watch this video which shows a quick comparison on the performance of using WebSockets as a transport for real-time web applications, as opposed to the traditional HTTP (long) polling.

YAWT (Yet Another WebSockets Tutorial) ??

There are many resources on this topic already on the web. Then why am I doing this? Well, I like to share what I learnt with others, in my own way.

Also the Spring example demonstrates WebSockets by using Spring Boot.

I wanted to 'retro-fit' my existing traditional Spring MVC application with WebSockets.

Hence this blog post.

Learning WebSockets

I am sharing my WebSocket learning experience with you through the example below. We will build a simple web application which will connect with a WebSocket server and echo back messages that we send to it. Sounds boring, but it’s the most basic example on how to go about WebSockets. In a later post I will share something more meaty.

What you will need

Before we get into WebSockets, you will need the following:

Spring Tool Suite (STS) ver. 3.4.0 (You can use Eclipse or IntelliJ too. I prefer STS and this example was built using STS)
Java 7 (JDK 1.7_0_45)
Tomcat ver. 7.0.47
Spring 4.0.0.RELEASE (See Reference Documentation)

You don't need to create a fancy UI, but I decided to use some ready made UI components provided by Twitter Bootstrap. It creates responsive web pages which are suitable for rendering on mobile devices as well as traditional laptop screens. And all this without having to be a HTML5 and CSS expert!

Twitter Bootstrap ver 3.0

Spring 4 WebSockets natively supports SockJS on the server side. So you will need the client side SockJS javascript framework. For this you will need to download -

Do all browsers support WebSockets?

Unfortunately, not all browsers support WebSockets. For example, IE10 was the first version of Internet Explorer browser to support it, while Google Chrome and FireFox have been supporting it since quite some time.

Many organizations still use older versions of Internet Explorer. Not everyone uses Google Chrome or FireFox. So in such cases you need a way to fallback on some other mechanisms like Ajax to communicate with the server. Also some networks are configured in such a way that proxies wont support WebSockets. In both cases you need a ‘fallback’ mechanism so that users can use WebSocket based applications.
You can test if your browser supports WebSockets by clicking here.

Project Setup

Using STS, create a simple Spring MVC Web Application. See the following screenshots to setup your project.

STS Project Setup 1: Select a wizard

STS Project Setup 2: Select Template

Note: We will change the Spring version 3.2.2 that the example MVC project uses to 4.0.0.RELEASE via the pom.xml file once the project is set up.

STS Project Setup 3: Project Specific Settings

STS Project Setup 4: Package Explorer

After you have setup your project, you should have a project layout similar to the above screenshot. The packages like com.blogspot.sunitkatkar.config , etc. will be added by you as you write code. The downloadable project file has the entire source code as per the screenshot below.

Modifying the pom.xml

We need to modify the example pom.xml file to have the proper Spring version in place. Let's look at the first section of the pom.xml file.

<!-- Properties -->
<properties>
  <!-- pom.xml -->
  <!-- Generic properties -->
  <java-version>1.7</java-version>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

  <!-- Spring framework -->
  <org.springframework-version>4.0.0.RELEASE</org.springframework-version>
  <org.springframework.security-version>3.2.0.RELEASE</org.springframework.security-version>

  <!-- Logging - Using Logback instead of Log4J -->
  <logback.version>1.0.13</logback.version>
  <org.slf4j-version>1.7.5</org.slf4j-version>

  <!-- Web -->
  <jsp.version>2.2</jsp.version>
  <jstl.version>1.2</jstl.version>
  <servlet.version>3.1.0</servlet.version>

  <!-- Test -->
  <junit.version>4.11</junit.version>

</properties>
<!-- /Properties -->

The rest of the pom.xml is a standard pom for Spring MVC projects. I have been using Log4J for logging, but for this project I decided to try the newer logging framework Logback by the creator of Log4J. More details here

Spring XML configuration

We are using XML based Spring configuration for this example. Here is the standard configuration via servlet-context.xml file.

    <?xml version="1.0" encoding="UTF-8"?>
<!-- servlet-context.xml -->
<beans:beans xmlns="http://www.springframework.org/schema/mvc"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:beans="http://www.springframework.org/schema/beans"
  xmlns:context="http://www.springframework.org/schema/context"
  xsi:schemaLocation="http://www.springframework.org/schema/mvc 
                      http://www.springframework.org/schema/mvc/spring-mvc.xsd
                      http://www.springframework.org/schema/beans 
                      http://www.springframework.org/schema/beans/spring-beans.xsd
                      http://www.springframework.org/schema/context 
                      http://www.springframework.org/schema/context/spring-context.xsd">

  <!-- DispatcherServlet Context: defines this servlet's request-processing infrastructure -->
  <context:component-scan base-package="com.blogspot.sunitkatkar" />

  <!-- Enables the Spring MVC @Controller programming model -->
  <annotation-driven />

  <!-- Handles HTTP GET requests for /resources/** by efficiently serving 
    up static resources in the ${webappRoot}/resources directory -->
  <resources mapping="/resources/**" location="/resources/" />

  <!-- Resolves views selected for rendering by @Controllers to .jsp resources 
    in the /WEB-INF/views directory -->
  <beans:bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
    <beans:property name="prefix" value="/WEB-INF/views/" />
    <beans:property name="suffix" value=".jsp" />
  </beans:bean>
</beans:beans>

Setting up Spring Security

Today the trend is to use Java based application and application security configuration for Spring based apps. However, I want to retro-fit my existing Spring MVC secured web application. So I continue to use XML based security configuration.

In our example, we want a simple login form. To achieve this, I have used the following security configuration via the application-security.xml file.

By using Spring Security XML configuration element <form-login> we can restrict access to secured web pages. Any attempt to access these pages will result in a login form being shown to the user. Once the user enters credentials and is authenticated then access is granted to the secured pages.

<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="http://www.springframework.org/schema/security"
  xmlns:beans="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.springframework.org/schema/beans  
                      http://www.springframework.org/schema/beans/spring-beans-3.0.xsd  
                      http://www.springframework.org/schema/security 
                      http://www.springframework.org/schema/security/spring-security.xsd">


  <!-- Get a basic Spring Security provided form based login infra -->
  <http auto-config="true" use-expressions="true">
    <intercept-url pattern="/index" access="permitAll" />
    <intercept-url pattern="/index.jsp" access="permitAll" />
    <intercept-url pattern="/app/**" access="permitAll" />
    <intercept-url pattern="/simplemessages/**" access="permitAll" />
    <intercept-url pattern="/topic/**" access="permitAll" />
    <intercept-url pattern="/topic/simplemessages" access="permitAll" />
    <intercept-url pattern="/resources/**" access="permitAll" />
    <intercept-url pattern="/login" access="permitAll" />
    <intercept-url pattern="/loginPage" access="permitAll" />
    <!-- Requests to secured pages need to be authenticated and authorized -->
    <intercept-url pattern="/secured/*"
      access="hasAnyRole('ROLE_ADMIN','ROLE_USER')" />
    <!-- Define the security form login and logout pages/urls -->
                    <form-login login-processing-url="/login" login-page="/loginPage"
      username-parameter="username" password-parameter="password"
      default-target-url="/secured/basicWebsockets"
      authentication-failure-url="/loginPage?auth=fail" />
<logout invalidate-session="true" logout-url="/logout"
      logout-success-url="/logoutPage" />
  </http>

  <!-- Define some example users and admins who have role based access to 
    the application. In a real world scenario this would be linked with a user 
    credentials database or a custom authentication provider. Some examples: 
    1) http://krams915.blogspot.in/2012/01/spring-security-31-implement_1244.html 
    2) http://krams915.blogspot.in/2010/12/spring-security-mvc-integration-using_26.html -->
  <authentication-manager>
    <authentication-provider>
      <user-service>
        <user name="john" password="doe" authorities="ROLE_USER" />
        <user name="sunit" password="katkar" authorities="ROLE_USER" />
        <user name="admin" password="admin" authorities="ROLE_USER,ROLE_ADMIN" />
      </user-service>
    </authentication-provider>
  </authentication-manager>
</beans:beans>

login-page: Mapping URL of the custom login page. If not defined, then Spring Security will create a default URL at '/spring_security_login' and render a default login form.
login-processing-url: Login form needs to be posted to this URL. If not defined then, it needs to be posted to default URL '/j_spring_security_check'.
username-parameter: Request parameter name which contains the username Default is 'j_username'.
password-parameter: Request parameter name which contains the password. Default is 'j_password'.
default-target-url: User will be redirected to this URL after successful login.
authentication-failure-url: If authentication failed, then user will be forwarded to this URL. Default is '/spring_security_login?login_error'. In this example we have set it to '/loginPage?auth=fail'. That means user will be redirected to the same login page and there we'll use request parameter 'auth=fail' as indicator to show the authentication failure message.

Adding Spring Security To The Spring MVC Web App

Now that the Spring security configuration is done via the application-security.xml file, it is time to combine it with Spring configuration file servlet-context.xml. This is done via the web.xmlb> file as shown

    <?xml version="1.0" encoding="UTF-8"?>
<!-- web.xml -->
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
  version="3.0">

  <!-- The definition of the Root Spring Container shared by all Servlets 
    and Filters -->
  <context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>
         /WEB-INF/spring/appServlet/servlet-context.xml
         /WEB-INF/application-security.xml
</param-value>
  </context-param>

  <!-- Creates the Spring Container shared by all Servlets and Filters -->
  <listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
  </listener>

  <!-- Processes application requests -->
  <servlet>
    <servlet-name>appServlet</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
      <param-name>contextConfigLocation</param-name>
      <param-value>
          /WEB-INF/spring/appServlet/servlet-context.xml
      </param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>

  <servlet-mapping>
    <servlet-name>appServlet</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>

  <!-- Spring standard form based login security -->
    <filter>
    <filter-name>springSecurityFilterChain</filter-name>
    <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
  </filter>
  
<filter-mapping>
    <filter-name>springSecurityFilterChain</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>
</web-app>

Spring MVC Controller

In this example, there is a LearnWebSocketsMVCController which receives all requests. We need to add methods to handle the requests for authentication as shown below.

/**
 * Copyright &copy; Sunit Katkar (sunitkatkar@gmail.com) http://sunitkatkar.blogspot.com
 */
package com.blogspot.sunitkatkar.controllers;

import java.security.Principal;
import java.util.Locale;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

import com.blogspot.sunitkatkar.util.Util;

/**
 * {@link LearnWebSocketsMVCController} is for handling the user login and logout. Simple form based security is used.
 * Refer to <code>application-security.xml</code> and <code>web.xml</code> for details.
 * 
 * @author <a href="mailto:sunitkatkar@gmail.com">Sunit Katkar</a>
 * @since 1.0
 * @version 1.0.0.1
 */
@Controller
public class LearnWebSocketsMVCController {

    private static final Logger LOG = LoggerFactory.getLogger(LearnWebSocketsMVCController.class);

    /**
     * To handle the regular request to the application context. e.g. http://localhost:8080/learn-websockets-1
     * 
     * @param model
     * @param locale
     * @return
     */
    @RequestMapping("/")
    public String handleIndexPage(Model model, Locale locale) {
        LOG.info("Request for default / url processed at {}", Util.getSimpleDate());
        return "loginPage";
    }

    /**
     * Method is executed when there is a call to the <code>/logoutPage</code> url.
     * 
     * @return
     */
    @RequestMapping(value = "/logoutPage", method = RequestMethod.GET)
public String logoutPage() {
        LOG.info("Request for /logoutPage url processed at {}", Util.getSimpleDate());
        return "logoutPage";
    }

    /**
     * Method is executed when there is a call to the <code>/loginPage</code> url. 
     * On successful login, the user is re-directed to the <code>/secured/myPage</code> url.
     * 
     * @return
     */
    @RequestMapping(value = "/loginPage", method = RequestMethod.GET)
public String loginPage() {
        LOG.info("Request for /loginPage url processed at {}", Util.getSimpleDate());
        return "loginPage";
    }

    /**
     * Method gets executed when there are requests to the <code>/secured/basicWebsockets</code> url. 
     * This url is called after a successful login.
     * 
     * @param model
     * @param principal
     * @param locale
     * @return
     */
    @RequestMapping("/secured/basicWebsockets")
public String basicWebsocketsPage(Model model, Principal principal, Locale locale) {

        // Get a simple human readable date and time
        String formattedDate = Util.getSimpleDate(locale);

        // Get the logged in user's name
        String userName = principal.getName();

        // Set some sample messages to show on the landing 'basicWebsockets.jsp' page.
        model.addAttribute("username", userName);
        model.addAttribute("time", formattedDate);

        LOG.info("Request from user:{} for /secured/basicWebsockets url processed at time:{}", userName, formattedDate);

        return "secured/basicWebsockets";
    }
}

Creating Views Using JSP

I have used Twitter Bootstrap to get a quick yet responsive and visually elegant user interface. This example has four jsp files.

index.jsp - Has a simple redirect to the loginPage.jsp
loginPage.jsp - To show the login form
logoutPage.jsp - To show the 'session ended' message
basicWebsockets.jsp - The landing page after authentication. This also has the WebSockets user interface and client side code

index.jsp

<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<c:redirect url="/loginPage"/>

loginPage.jsp

<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%>
<%@ taglib uri='http://java.sun.com/jsp/jstl/core' prefix='c'%>
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<!--  Bootstrap related -->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- Latest compiled and minified CSS -->
<link rel="stylesheet" href="<c:url value="/resources/scripts/bootstrap/css/bootstrap.min.css"/>">
<%-- <link href="<c:url value="/resources/css/login.css"/>" rel="stylesheet"> --%>
<title>Login :: Learn WebSockets</title>
</head>
<body>
  <div class="container">
    <div class="span12">
      <div id="heading" class="masthead">
        <h3 class="muted">Login</h3>
      </div>
      <div class="row">
        <div class="col-sm-6">
          <div class="panel panel-default">
            <div class="panel-body">
              <form action="${pageContext.request.contextPath}/login" method="post" 
                  class="form-signin" role="form">
                <div class="form-group">
                  <label for="username">User name:</label> 
                  <input type="text" name="username" id="username" class="form-control" 
                    placeholder="User name" required autofocus />
                </div>
                <div class="form-group">
                  <label for="password">Password:</label> <input type="password" name="password" id="password"
                    class="form-control" placeholder="Password" required>
                </div>
                <input name="submit" type="submit" value="Submit" class="btn btn-success">
              </form>
              <c:if test="${'fail' eq param.auth}">
                <p>
                <div class="alert alert-danger">Login Failed!!! Reason :
                  ${sessionScope["SPRING_SECURITY_LAST_EXCEPTION"].message}</div>
              </c:if>
            </div>
          </div>
        </div>
        <!-- .panel-body -->
      </div>
      <!-- .panel -->
    </div>
    <!-- .span12 -->
  </div>
  <!-- .container -->
  <!-- .container -->
  <!-- Compiled and minified JQuery JavaScript (necessary for Bootstrap's JavaScript plugins). 
       Placed at the end of the document so the pages load faster -->
  <script src="<c:url value="/resources/scripts/jquery-1.10.2.min.js"/>"></script>
  <!-- Include all compiled plugins (below), or include individual files as needed -->
  <script src="<c:url value="/resources/scripts/bootstrap/js/bootstrap.min.js"/>"></script>
</body>
</html>

logoutPage.jsp

<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%>
<%@ taglib uri='http://java.sun.com/jsp/jstl/core' prefix='c'%>
<!DOCTYPE html>
<!-- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<!--  Bootstrap related -->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- Latest compiled and minified CSS -->
<link rel="stylesheet" href="<c:url value="/resources/scripts/bootstrap/css/bootstrap.min.css"/>">
<title>Logout :: Learn WebSockets</title>
</head>
<body>
  <div class="container">
    <div class="span12">
      <div id="heading" class="masthead">
        <h3 class="muted">Logged Out</h3>
      </div>
      <div class="row">
        <div class="col-sm-12">
          <div class="panel panel-default">
            <div class="panel-body">
              Your session has ended. Click here 
              to <a href="${pageContext.request.contextPath}/secured/basicWebsockets">login</a>
              again.
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
  <!-- Compiled and minified JQuery JavaScript (necessary for Bootstrap's JavaScript plugins). 
    Placed at the end of the document so the pages load faster -->
  <script src="<c:url value="/resources/scripts/jquery-1.10.2.min.js"/>"></script>
  <!-- Include all compiled plugins (below), or include individual files as needed -->
  <script src="<c:url value="/resources/scripts/bootstrap/js/bootstrap.min.js"/>"></script>
</body>
</html>

basicWebsockets.jsp

We will look at this page after we delve into server and client side code for WebSockets

Server side code for WebSockets

Before we look at the client side javascript required for WebSockets, let's look at the server side code. We need to make our 'legacy' MVC application aware of the new 'WebSockets' feature.

Configuring WebSockets

We have used XML for configuring the MVC app. Now this is the 'legacy' app which we will retro-fit with WebSockets. Note that you can use XML based WebSocket configuration, but we will use Java based configuration. You can mix and match XML and Java based configuration in a Spring MVC app. When starting new projects you can keep it clean by going either complete XML or complete Java based configuration.

Here is Java based configuration for 'retro-fitting' WebSockets in our MVC example via the WebSocketConfig class. The source code has self explanatory comments.

    
/**
 * Copyright &copy; 2013-2014 <a href="http://sunitkatkar.blogspot.com">Sunit's blog</a>
 */
package com.blogspot.sunitkatkar.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.messaging.simp.config.ChannelRegistration;
import org.springframework.messaging.simp.config.MessageBrokerRegistry;
import org.springframework.scheduling.annotation.EnableScheduling;
import org.springframework.web.socket.config.annotation.EnableWebSocketMessageBroker;
import org.springframework.web.socket.config.annotation.StompEndpointRegistry;
import org.springframework.web.socket.config.annotation.WebSocketMessageBrokerConfigurer;

/**
 * Defines methods for configuring message handling with simple messaging
 * protocols (e.g. STOMP) from WebSocket clients. Typically used to customize
 * the configuration provided via the {@link EnableWebSocketMessageBroker}
 * annotation. <br/>
 * <br/>
 * WebSocketConfig is annotated with <code>@Configuration</code> to indicate
 * that it is a Spring configuration class. It is also annotated with
 * <code>@EnableWebSocketMessageBroker</code>. As its name suggests,
 * <code>@EnableWebSocketMessageBroker</code> enables WebSocket message
 * handling, backed by a message broker. <br/>
* <br/>
 * Furthermore, this is also annotated with the <code>@EnableScheduling</code>
 * annotation. This enables Spring's scheduled task execution ability.
 * 
 * @author <a href="mailto:sunitkatkar@gmail.com">Sunit Katkar</a>
 * @since 1.0
 * @version 1.0.0.1
 */

@Configuration
@EnableWebSocketMessageBroker
@EnableScheduling
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    /**
     * Configure STOMP over WebSocket end-points.
     * 
     * @see com.blogspot.sunitkatkar.WebSocketBroadcastController.controllers.WebsocketBroadcastController
     */
    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        // The registerStompEndpoints() method registers the "/simplemessages"
        // endpoint, enabling SockJS fallback options so that alternative
        // messaging options may be used if WebSocket is not available. This
        // endpoint when prefixed with "/app", is the endpoint that the
        // WebSocketBroadcastController.processMessageFromClient() method is
        // mapped to handle.
        registry.addEndpoint("/simplemessages").withSockJS();
    }

    /**
     * Configure message broker options.
     */
    @Override
    public void configureMessageBroker(MessageBrokerRegistry config) {
        // The configureMessageBroker() method overrides the default method in
        // WebSocketMessageBrokerConfigurer to configure the message broker. It
        // starts by calling enableSimpleBroker() to enable a simple
        // memory-based message broker to carry the greeting messages back to
        // the client on destinations prefixed with "/topic/". It also
        // designates the "/app" prefix for messages that are bound for
        // @MessageMapping-annotated methods.

        config.enableSimpleBroker("/topic/", "/queue/");
        config.setApplicationDestinationPrefixes("/app");
    }

    /**
     * 
     * Configure the {@link org.springframework.messaging.MessageChannel} used
     * for incoming messages from WebSocket clients. By default the channel is
     * backed by a thread pool of size 1. It is recommended to customize thread
     * pool settings for production use.
     */
    @Override
    public void configureClientInboundChannel(ChannelRegistration registration) {

    }

    /**
     * Configure the {@link org.springframework.messaging.MessageChannel} used
     * for outgoing messages to WebSocket clients. By default the channel is
     * backed by a thread pool of size 1. It is recommended to customize thread
     * pool settings for production use.
     */
    @Override
    public void configureClientOutboundChannel(ChannelRegistration registration) {
        registration.taskExecutor().corePoolSize(4).maxPoolSize(10);
    }

}

Handling WebSocket [ws(s)://] Requests

Handling WebSocket requests is similar to handling regular http(s) requests in Spring based code. We create a regular Spring Controller WebSocketBroadcastController but use the messaging annotations (e.g. @MessageMapping) to handle requests and serve content. Take a look at the Spring docs for more details.

Here is the WebSocketBroadcastController class with self explanatory source code comments.

    
/**
 * Copyright &copy; Sunit Katkar (sunitkatkar@gmail.com) http://sunitkatkar.blogspot.com
 */
package com.blogspot.sunitkatkar.controllers;

import java.security.Principal;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.messaging.handler.annotation.MessageExceptionHandler;
import org.springframework.messaging.handler.annotation.MessageMapping;
import org.springframework.messaging.handler.annotation.SendTo;
import org.springframework.messaging.simp.annotation.SendToUser;
import org.springframework.stereotype.Controller;

import com.blogspot.sunitkatkar.model.MessageBroadcast;
import com.blogspot.sunitkatkar.model.SimpleMessage;
import com.blogspot.sunitkatkar.util.Util;

/**
 * {@link WebSocketBroadcastController} is a regular Spring Controller as seen
 * in most Spring MVC applications. Its job is to receive {@link SimpleMessage}
 * message objects from the client, extract the <code>payload</code> (or
 * contents) of the message, prepend it with some simple text and finally
 * broadcast (or publish) the message to all clients who have subscribed to the
 * <code>/topic/simplemessages</code> message queue.
 * 
 * 
 * @author <a href="mailto:sunitkatkar@gmail.com">Sunit Katkar</a>
 * @since 1.0
 * @version 1.0.0.1
 */

@Controller
public class WebSocketBroadcastController {

    private static final Logger LOG = LoggerFactory
            .getLogger(WebSocketBroadcastController.class);

    /**
     * Method to handle the requests sent to this controller at
     * <code>/simplemessages</code> <br/>
     * <br/>
     * <b>Explanation:</b> The <code>@MessageMapping</code> annotation ensures
     * that if a message is sent to destination <code>/simplemessages</code>,
     * then the
     * {@link WebSocketBroadcastController#processMessageFromClient(SimpleMessage)}
     * method is called. <br/>
     * <br/>
     * The message payload is bound to the {@link SimpleMessage} object. For
     * simplicity, this method simulates a 3 second delay before sending back
     * the message as a {@link MessageBroadcast} object. The return value is
     * broadcast to all subscribers to
     * <code>/topic/simplemessagesresponse</code> as specified in the
     * <code>@SendTo</code> annotation. <br/>
     * <br/>
     * <b>Note:</b> The 3 second delay demonstrates that after the server
     * receives a message from the client, the client is free to continue any
     * other processing while the server takes its own time to act on the
     * received message.
     * 
     * @param message
     * @param principal
     * @param locale
     * @return
     * @throws Exception
     */
   @MessageMapping("/simplemessages")
@SendTo("/topic/simplemessagesresponse")
public MessageBroadcast processMessageFromClient(SimpleMessage message,
            Principal principal) throws Exception {
        // Simulate a delay of 3 seconds
        Thread.sleep(3000);
        LOG.info("Sending server side response '{}' for user: {}", message,
                principal.getName());
        return new MessageBroadcast("Server response: Did you send &lt;b&gt;'"
                + message.getMessage() + "'&lt;/b&gt;? (Server Response at: "
                + Util.getSimpleDate() + ")");
    }

    /**
     * If there are any exceptions thrown by any of the messaging infrastructure
     * then they can be sent to the end user on the <code>/queue/errors</code>
     * destination.
     * 
     * @param exception
     * @return
     */
    @MessageExceptionHandler
    @SendToUser("/queue/errors")
    public String handleException(Throwable exception) {
        return exception.getMessage();
    }
}

Client Side WebSockets Code - basickWebsockets.jsp

On the client side we will use the SockJS javascript library to create a WebSocket connection and then communicate with the server. The following jsp page basicWebsockets.jsp has the HTML and Javascript together for easier reading. Note that I have used Twitter Bootstrap and hence there is some javascript code to handle the UI interactions. You can create a bare bones HTML page too.

The code has self explanatory comments.

<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%>
<%@ taglib uri='http://java.sun.com/jsp/jstl/core' prefix='c'%>
<!-- basicWebsockets.jsp -->
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta http-equiv="Cache-Control" content="no-store, no-cache, must-revalidate, max-age=0">
<!--  Bootstrap related -->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- Latest compiled and minified Bootstrap CSS -->
<link rel="stylesheet" href="<c:url value="/resources/scripts/bootstrap/css/bootstrap.min.css"/>">
<title>Learn WebSockets 1</title>
<!-- WebSocket related javascript includes -->
<script src="<c:url value="/resources/scripts/sockjs-0.3.4.min.js"/>"></script>
<script src="<c:url value="/resources/scripts/stomp.js"/>"></script>
</head>
<body>
  <noscript>
    <h2 style="color: #ff0000">Seems your browser doesn't support Javascript! WebSocket relies on Javascript being enabled. Please enable Javascript and reload this page!</h2>
  </noscript>
  <c:url var="imageUrl" value="/resources/images/user01.png" />
  <div class="container">
    <div class="row">
      <div class="col-sm-10">
        <!-- WebSocket related Twitter Bootstrap 3.0 based UI elements -->
        <div id="heading" class="masthead">
          <div class="pull-right">
            Logged In: <strong>${username}</strong> | ${time } | <a href="${pageContext.request.contextPath}/logout">Logout&nbsp;<span class="glyphicon glyphicon-remove"></span></a>
          </div>
          <h3 class="muted">
            <img src="${imageUrl}" />Welcome to Learning WebSockets 1
          </h3>
        </div>
      </div>
    </div>
    <div class="row">
      <div class="col-sm-6">
        <p>&nbsp;</p>
        <!-- Connect and Disconnect buttons to establish/terminate a connection to the websocket service -->
        <div class="panel">
          <button id="connect" class="btn btn-success btn-sm">Connect</button>
          <button id="disconnect" class="btn btn-danger btn-sm">Disconnect</button>
        </div>
        <p />
        <div class="panel panel-default">
          <div class="panel-heading">Send Messages To WebSocket Server</div>
          <div class="panel-body" id="conversationDiv">
            <div class="input-group">
              <input type="text" class="form-control" id="txtSendMessage" placeholder="Enter message"> <span class="input-group-btn">
                <button id="sendMessage" class="btn btn-primary">
                  <span class="glyphicon glyphicon-share-alt"></span>&nbsp;Send
                </button>
              </span>
            </div>
            <!-- Error alert -->
            <div class="alert alert-danger alert-dismissable" id="formAlert">
              <button type="button" class="close" data-dismiss="alert" aria-hidden="true">&times;</button>
              <strong>Error!</strong> Message cannot be blank.
            </div>
            <!-- /Error alert -->
            <!-- Info alert -->
            <div class="alert alert-info alert-dismissable" id="formInfoAlert">
              <button type="button" class="close" data-dismiss="alert" aria-hidden="true">&times;</button>
              <strong>Message Sent!</strong> <br />Your message has been sent to the server. You can continue to do other actions. Server response will be shown when it arrives.
            </div>
            <!-- /Info alert -->
            <!-- .input-group -->
          </div>
          <!-- .panel-body -->
          <div class="panel-body" id="response"></div>
          <!-- Div to show the server responses -->
        </div>
        <!-- .panel -->
      </div>
    </div>
  </div>
  <!-- .container -->
  <!-- External Javascripts -->
  <!-- Latest compiled and minified JQuery JavaScript (necessary for Bootstrap's JavaScript plugins). Placed at the end of the document so the pages load faster -->
  <script src="<c:url value="/resources/scripts/jquery-1.10.2.min.js"/>"></script>
  <!-- Include all compiled plugins (below), or include individual files as needed -->
  <script src="<c:url value="/resources/scripts/bootstrap/js/bootstrap.min.js"/>"></script>
  <!-- Knockout data-binding MVVM library. More at http://knockoutjs.com/  -->
  <script src="<c:url value="/resources/scripts/knockout-3.0.0.js"/>"></script>
  <%-- URL for the STOMP end point for registering a stomp client--%>
  <c:url value="/simplemessages" var="socketDest" />
  <script type="text/javascript">
            /***********************************************/
            /* PLEASE READ UP ON STOMP AND SOCKJS          */
            /* 1) http://jmesnil.net/stomp-websocket/doc/  */
            /* 2) https://github.com/sockjs/sockjs-client  */
            /***********************************************/

            //Declare a stompclient which will connect to the server
            var stompClient = null;

            /************************************************************************** 
            /*  JQUERY WAY OF BEING UNOBTRUSIVE AND ADDING EVENT HANDLERS TO WIDGETS, 
            /*  THUS KEEPING HTML AND JAVASCRIPT SEPARATE 
            /*************************************************************************/
            // Runs this code only when the DOM (all elements) are ready
            $(document).ready(function() {
                // On page load the text input field 'MESSAGE', 'DISCONNECT' and 'SEND' buttons 
                // should all be disabled as user has not clickedd 'CONNECT' button yet.
                $("#disconnect").prop('disabled', true);
                $("#txtSendMessage").prop('disabled', true);
                $("#sendMessage").prop('disabled', true);

                //Also all text in server message should be empty
                $("#txtSendMessage").val("");
                //Remove any server responses from previous interactions
                $("#response").empty();
                //Hide the validation and info alerts on page load
                $(".alert").hide();
                // Event handler: Connect button
                $("#connect").on("click", function(e) {
                    // If alert is visible, hide it
                    $("#formAlert").slideUp(400);
                    connect();
                });

                // Event handler: Disconnect button 
                $("#disconnect").on("click", function(e) {
                    // If alert is visible, hide it
                    $("#formAlert").slideUp(400);
                    disconnect();
                });
                // Event handler: X button on top right of info alert.
                // Clicking the X button on top right will dismiss it from the screen and hide it
                $(".alert").find(".close").on("click", function(e) {
                    // Find all elements with the "alert" class, get all descendant elements 
                    // with the class "close", and bind a "click" event handler

                    // Don't allow the click to bubble up the DOM
                    e.stopPropagation();

                    // Don't let any default functionality occur (in case it's a link)
                    e.preventDefault();

                    // Hide this specific Alert
                    $(this).closest(".alert").slideUp(400);

                    // Focus on the Send Message textfield
                    $("#txtSendMessage").select();
                    $("#txtSendMessage").focus();
                });

                // Event handler: Send button
                $("#sendMessage").on("click", function(e) {

                    // Find the input text element for the server message
                    var messageForServer = $("#txtSendMessage").val();

                    if (messageForServer === "") {

                        // If message is empty prevent submission and show the alert
                        e.preventDefault();
                        $("#formAlert").slideDown(400);

                    } else {

                        // Message is not empty so send to server
                        $("#formAlert").slideUp(400);

                        // Show a please wait alert
                        $("#formInfoAlert").slideDown(400);

                        // Send message to server. The message for the server must 
                        // be in JSON format. 
                        // Also refer SimpleMessage.java POJO.
                        sendMessageToServer(messageForServer);
                    }
                });
            });

            //Function sets the state of the Connect and Disconnect buttons
            function setConnected(connected) {
                //Since we are using bootstrap, this is how you disable buttons 
                // and input widgets
                $("#connect").prop('disabled', connected);
                $("#disconnect").prop('disabled', !connected);
                $("#sendMessage").prop('disabled', !connected);
                $("#txtSendMessage").prop('disabled', !connected)
            }

            // Function to connect the web client to the websocket server
            function connect() {
                //Remove any server responses from previous interactions
                $("#response").empty();
                //Also all text in server message input field should be empty
                $("#txtSendMessage").val("");
                $("#txtSendMessage").focus();
                $("#txtSendMessage").select();
                // Register a websocket endpoint using SockJS and stomp.js
                // Refer to Java class Refer to Java class 
                // WebSocketConfig.java#registerStompEndpoints(StompEndpointRegistry registry)
                var socket = new SockJS('${socketDest}');
                stompClient = Stomp.over(socket);
                // Now that a stomp client is defined, its time to open a connection
                // 1) First we connect to the websocket server
                // Notice that we dont pass in username and password as Spring Security
                // has already provided the server with the Principal object containing user credentials
                // 2) The last argument is a callback function which is called when connection succeeds
                stompClient.connect('', '', function(frame) {
                    //set the connect and disconnect button state. (disable connect button)
                    setConnected(true);
                    // In production code remove the next line
                    console.log("Connected: " + frame);
                    //Lets show a connection success message
                    showServerBroadcast("Connection established: " + frame, false);
                    // Now subscribe to a topic of interest.
                    // Refer to Java class WebsocketBroadcastController.java#processMessageFromClient(SimpleMessage message)
                    // WebsocketBroadcastController is waiting for connections. Upon successful connection, it subscribes to
                    // the "/topic/simplemessagesresponse" destination where the server will echo the messages.
                    // When a broadcast message is received by the client on that destination, it will be shown by appending
                    // a paragraph to the DOM in the client browser.
                    stompClient.subscribe("/topic/simplemessagesresponse", function(servermessage) {//Callback when server responds
                        showServerBroadcast(JSON.parse(servermessage.body).messageContent, false);
                        //Server responded so hide the info alert
                        $("#formInfoAlert").slideUp(400);
                        //Also all text in server message input field should be empty
                        $("#txtSendMessage").val("");
                        $("#txtSendMessage").focus();
                        $("#txtSendMessage").select();
                    });
                });
            }

            // Function to disconnect the web client to the websocket server
            function disconnect() {
                //First hide any alerts
                $("#formAlert").slideUp(400);
                $("#formInfoAlert").slideUp(400);
                // Disconnect the stompClient
                stompClient.disconnect();
                // Set the connect and disconnect button states
                setConnected(false);
                // In production remove the next line
                console.log("Disconnected");
                showServerBroadcast("WebSocket connection is now terminated!", true);
            }

            // Function to send the message typed in by the user to the "/app/simplemessages" destination on the server.
            // WebsocketBroadcastController will receive this message and broadcast the results after 
            // an artificially introduced delay.
            function sendMessageToServer(messageForServer) {
                //Show on the browser page that a message is being sent
                showServerBroadcast("Your message '" + messageForServer + "' is being sent to the server.", true);
                // The message for the server must be in JSON format. Also refer SimpleMessage.java POJO.
                stompClient.send("/app/simplemessages", {}, JSON.stringify({
                    'message' : messageForServer
                }));
            }

            /**
             * Function to show the server response on the web page
             * @param servermessage - text to be shown on webpage
             * @param localMessage - boolean, if true then it means its a 
             *                       client side javascript generated message.
             */
            function showServerBroadcast(servermessage, localMessage) {
                // Server surrounds the user sent message with <b> and </b> 
                // as &ltb&gt;message%lt;/b&gt;
                // Use Jquery to decode the HTML and show it as <b>message</b>
                var decoded = $("<div/>").html(servermessage).text();

                var tmp = "";
                var serverResponse = document.getElementById("response");
                var p = document.createElement('p');
                p.style.wordWrap = 'break-word';

                if (localMessage) {
                    p.style.color = '#006600';
                    tmp = "<span class='glyphicon glyphicon-dashboard'></span> " + decoded + " (Browser time:" + getCurrentDateTime() + ")";
                } else {
                    p.style.color = '#8A0808';
                    tmp = "<span class='glyphicon glyphicon-arrow-right'></span> " + decoded;
                }
                //Assigning the decoded HTML to the <p> element
                p.innerHTML = tmp;
                serverResponse.appendChild(p);
            }

            /**
             * Utility function to return the date time in simple format
             * like Tue Jan 07 2014 @ 11:47:24 AM
             */
            function getCurrentDateTime() {
                var date = new Date();
                var n = date.toDateString();
                var time = date.toLocaleTimeString();
                return n + " @ " + time;
            }
        </script>
</body>
</html>

The Final Result

Download the project (link at the end of this post) and run it.

You can access the WebSockets app in the browser at the url http://localhost:8080/learn-websockets-1. Happy WebSocket-ing :)

Download the app from this location

Using Threads in VB.Net for showing a progress bar in a separate dialog

noreply@blogger.com (Sunit) — Mon, 01 Apr 2013 10:17:00 +0000

I am new to VB.NET. I had programmed in Visual Basic 4 many many years ago. Recently I had to use Visual Studio 2010 to create a quick application for internal usage. Now there was a task which took a long time. As per good user interface design it was obvious that a progress update should be shown to keep the end user informed and updated till the task completed.

To cut a long story short, the requirement was to let the long running task continue while a progress bar showed the progress of the task. After searching for examples, I got a basic idea on how to use threads in VB.Net to accomplish the task I had at hand.

Fig. 1 Main Dialog

Fig. 2 Separately Launched Progress Dialog

I have attached the VS2010 project for you to download and see the code. The main working parts are explained here.

Basic Steps

Step 1 - Create a basic Windows Form application
Step 2 - Create a simple Dialog and add a ProgressBar and a Label to it
Step 3 - Write a method which will launch a separate Thread to perform the long running task
Step 4 - Write Delegate methods in the Dialog

The code is self explanatory.

Code for the Main Form

Option Explicit On
Option Strict On

Imports System.Threading

' Main form which launches a long running task and 
' shows progress update in a separate dialog
Public Class MainForm
    Inherits Form

    'Flag that indcates if a process is running
    Dim isProcessRunning As Boolean = False

    'Progress bar dialog
    Dim progressDlg As New ProgressDialog


    'Long running background process with 
    'a determinate progress indicator, 
    'using a seperate modal dialog containing
    'a progress bar

    <MTAThread()> _
    Private Sub ButtonClick1_Click(ByVal sender As System.Object, _
                                   ByVal e As System.EventArgs) _
                               Handles ButtonClick1.Click

        'If a process is already running, 
        'warn the user and cancel the operation
        If isProcessRunning = True Then
            MessageBox.Show("Sorry, a process is already running.", _
                            "Status", MessageBoxButtons.OK, _
                            MessageBoxIcon.Exclamation)
            Return
        End If

        'Define a background thread and start the 
        'long running process in this separate thread
        Dim backgroundThread As _
            New Threading.Thread(AddressOf DoLongRunningProcess)

        ' Start the background process thread
        backgroundThread.Start()

        ' Open the dialog
        progressDlg.Show()
    
End Sub

     
    ' The long running process 

    Public Sub DoLongRunningProcess()
        ' Set the flag that indicates if a 
        ' process is currently running
        isProcessRunning = True
        
        ' Iterate from 0 - 100
        ' On each iteration, pause the thread 
        ' for .05 seconds, then update the 
        ' dialog's progress bar
        For n As Integer = 0 To 100
            Thread.Sleep(100)
            progressDlg.UpdateProgress(n)
        Next
        
        ' Show a dialog box that confirms the process 
        ' has completed
        MessageBox.Show("Thread completed!", "Status", _
                        MessageBoxButtons.OK, _
                        MessageBoxIcon.Information)
        'Close the dialog when user clicks OK
        progressDlg.Close()
        ' Reset the flag that indicates if a process is
        ' currently running
        isProcessRunning = False
    End Sub
  
End Class

Code for the Progress Dialog

Option Explicit On
Option Strict On
Imports System.Windows.Forms
  
' Dialog class with a ProgressBar widget to 
' show the progress of a long running task
 
Public Class ProgressDialog
    Inherits Form

    ' Delegate to update the progress 
    ' of the ProgressBar widget
    Delegate Sub DelegateUpdate(ByVal progress As Integer)
   
    ' Delegate to handle the Close event 
    ' for this dialog
    Delegate Sub DelegateClose(ByRef dialog As Form)

    ' Default constructor which initializes 
    ' this control
    Public Sub New()
        InitializeComponent()
    End Sub


    
    ' Method to update the progress bar widget. This 
    ' uses the InvokeRequired and BeginInvoke methods
    Public Sub UpdateProgress(ByVal progress As Integer)
        If ProgressBar1.InvokeRequired Then
            ProgressBar1.BeginInvoke(New DelegateUpdate(AddressOf UpdateDelegateImpl), progress)
        Else
            ProgressBar1.Value = progress
        End If
    End Sub

    ' Overloads the Close method
    Public Overloads Sub Close()
        If Me.InvokeRequired Then
            Me.BeginInvoke(New  _
                           DelegateClose(AddressOf CloseDelegateImpl), Me)
        Else
            Me.Close()
        End If
    End Sub
   
    ' Implementation of the DelegateUpdate
    Sub UpdateDelegateImpl(ByVal progress As Integer)
        ProgressBar1.Value = progress
        LabelProgress.Text = ""
        LabelProgress.Text = progress & CStr("%")
    End Sub
    
    ' Implmentation of the DelegateClose
    Sub CloseDelegateImpl(ByRef dialog As Form)
        dialog.Close()
    End Sub

End Class

Download Project
I have uploaded the project as a ZIP archive on Google Drive. Click to download.

Quickly and selectively clean up your Internet Explorer cache

noreply@blogger.com (Sunit) — Fri, 21 Jan 2011 23:26:00 +0000

While testing GWT applications it is sometimes necessary to clean up your entire cache. Firefox has simple shortcut keys to achieve this, but IE does not. Especially IE7. (Yes we have to support IE7 as the lowest version)

Here is a quick way to do it. You can run this from a command prompt, or a batch file or simply from the 'Run' menu which pops up when you click Run from the Start menu.

#To clear IE7 temporary Internet files 
RunDll32.exe InetCpl.cpl,ClearMyTracksByProcess 8

#To clear IE7 browsing cookies 
RunDll32.exe InetCpl.cpl,ClearMyTracksByProcess 2

#To clear IE7 browsing history 
RunDll32.exe InetCpl.cpl,ClearMyTracksByProcess 1

#To clear IE7 form data 
RunDll32.exe InetCpl.cpl,ClearMyTracksByProcess 16

#To clear IE7 remembered passwords for filling web login forms 
RunDll32.exe InetCpl.cpl,ClearMyTracksByProcess 32

#To clear or delete all IE7 browsing history i.e all of the above! 
RunDll32.exe InetCpl.cpl,ClearMyTracksByProcess 255

Testing Windows Live Writer to post to my blog

noreply@blogger.com (Sunit) — Wed, 07 Oct 2009 21:00:00 +0000

Just testing how Windows Live Writer works to post directly to my blog. Apparently it works just fine :)

Looking at BlackBerry as a development platform

noreply@blogger.com (Sunit) — Tue, 23 Jun 2009 17:21:00 +0000

I found an interesting article about experiences of developing for the BlackBerry.

Should I take the plunge into iPhone development?

noreply@blogger.com (Sunit) — Thu, 11 Jun 2009 17:44:00 +0000

I have been delaying getting into iPhone Application development. I had so many ideas for developing applications for the mobile device. Android definitely helped me get a feel of what it takes to develop mobile apps. My last experience developing for a hand held device was with Palm OS 3.0 with Code Warrior IDE about a decade ago. After that Android has been my only foray into mobile development.

The reason I feel that I should finally give in to iPhone is that I dont see much traction for Android applications. The market place and success stories of iPhone developers lure me more towards it. The other reason is that I want to keep my skills current and relevant. When Palm Pre was to be released there was much excitement in the developer community, but now it seems to have fizzled out.

I want to be able to learn an exciting new platform and also look at it in a slightly commerical light. Why should I not be able to translate my efforts to dollars?

My biggest mental block to iPhone is perhaps the requirements where I have to get a Mac. I have always been a developer who has used Windows and Linux to quite an extent. I have only used a Mac for maybe an hour or so in my entire career.

Or should I look into Symbian? It has a Windows based development environment.

Anyone out there who has some experience with this? Please share your thoughts.

Android SendMail - Send Email Programmatically

noreply@blogger.com (Sunit) — Wed, 17 Dec 2008 19:27:00 +0000

SendMail is really an excellent email program found on most Unix systems. I just borrowed the name for my tutorial on sending email programmatically from an Android phone.

Long ago, when I worked on the Palm OS, one could create an email message programmatically, and then place it in the Outbox of the Email application. Once the PDA was synced with the PC, the email would be sent. I was looking for a similar way to send email from the Android phone. After searching the google groups and scouring websites and android docs, I managed to piece together a simple example.

Tipster on the real Android G phone

noreply@blogger.com (Sunit) — Sat, 01 Nov 2008 18:05:00 +0000

I finally got a chance to run the Tipster application on a real Android powered T-Mobile G phone. I realised that you have to slide open the keyboard to enter values, thus changing the view into a 'landscape mode'. When you do that, the results of the tip calculations are not visible as they are towards the bottom half of the screen. So I experimented and found that I needed to allow 'scrolling' of the view. I have updated the the tutorial with the simple enhancements to make the application visible even in landscape mode.

Some folks are really cowards!

noreply@blogger.com (Sunit) — Sat, 01 Nov 2008 02:44:00 +0000

Just today I got hold of a G1 phone. As I was searching the Android App Market, what do I see? I see that some person by the name 'Steve Coward' has copied my tutorial and packaged it as his own! He has published it as Tip Calculator on the App Market for free download.

I dont mind people using my source code, but I had expressly written in the source code that please dont redistribute this code!

At the very least he could have given some credit to me!

I really feel that some folks dont get the meaning of tutorials, helping hands, requests to not do certain things. Very unethical!

How to develop applications for the Google Android OS

noreply@blogger.com (Sunit) — Wed, 15 Oct 2008 23:30:00 +0000

Recently I started exploring the Google Android OS for mobile phones. It is quite an interesting OS and a joy to develop for. I have written this tutorial which shows you how you can write a simple Tip Calculator application for your Google Android powered phone.

Sunit Katkar's blog

Setting up Keycloak 10 with MySQL 8 on your Windows machine

Purpose of this blog post

Problems when setting up on Windows 10

Versions used in this blog post

Useful tools

Assumptions

Basic Steps

Using JBoss/Wildfly CLI

Step 1: Create a database in MySQL

Step 2: Create a database user for Keycloak

Why use mysql_native_password when creating a user?

Step 3: Grant all privileges

Step 4: Ensure that your databse engine is InnoDB

Step 5: Adding a module with the MySQL driver (Connector/J) to Keycloak

What did this module add command do?

Step 6: Defining a data source

Remove the existing datasource

Define your MySQL based driver and data source

About the character encoding parameter in the jdbc connection url

Test your database connection

Step 7: Database configuration

Step 8: Restarting Keycloak server

Checking Keycloak log messages to see that MySQL connectivity is working as expected

About the log message - Deploying non-JDBC-compliant driver class com.mysql.cj.jdbc.Driver

Wrapping up

Happy Keycloak-ing! :)

Spring Boot 2 + Thymeleaf - Versioning static assets for client side cache busting

Purpose of this blog post

What is used to build the example in this blog post?

Step 1: Adding entries to your application.properties (or application.yml) file

File: application.properties

Step 2: Define a ResourceUrlEncodingFilter bean

File: CacheBusterMVCConfig.java

Results

Resources

Adding tenants without application restart in SaaS style multi-tenant web app with Spring Boot 2 and Spring Security 5

Update 4th Sep 2018

Purpose of this blog post

Structure of the application

Datasources - One for the master database and one each for every tenant

Order of setting up datasources and entity managers

File: MasterDatabaseConfig.java

File: TenantDatabaseConfig.java

File: DataSourceBasedMultiTenantConnectionProviderImpl.java

Resources

In conclusion

Update - 10 July 2018

Spring Boot 2 generic JPA converter to serialize and deserialize an entity attribute as JSON

Purpose of this blog post

Java and JSON

Java and Jackson

JPA and Converter

Writing the generic converter

The generic JSON JPA converter code

Example for using the converter

JPA Entity - Student

Course Java POJO

Using the JSON JPA Converter

Resources

Spring Boot 2 generic JPA converter to encrypt and decrypt an entity attribute

Purpose of this blog post

Java and Cryptography

How does cryptography work?

JPA and Converter

Writing the generic attribute converter

Step 1 - Write the encryption and decryption code

Step 2 - Write the base attribute converter

Step 3 - Implementing the concrete String encryption/descryption JPA attribute converter

Step 4 - Using the String encryption/descryption JPA attribute converter

Bonus - Converter to encrypt / decrypt LocalDate

Resources

Building SaaS style multi-tenant web app with Spring Boot 2 and Spring Security 5 - Part 1

Purpose of this blog post

What is used to build the example in this blog post?

What is Multi-Tenancy?

A more technical explanation of multi-tenancy

Which multi-tenancy approach is better?

Multi-tenancy using database per tenant approach

How does the SaaS application work?

Why use `mysql_native_password` when creating a user?

What did this `module add` command do?