Monday, December 10, 2012

Spring Social with JavaConfig (Part 1)

In this tutorial, we will create an application that can post messages and retrieve profile information from Facebook and Twitter. We will use Spring Social to implement these features. To secure our application we will use Spring Security, and to manage our views, we will use Thymeleaf.

Table of Contents

Click on a link to jump to that section:
  1. Functional Specs
  2. Generate OAuth keys
    • Facebook
    • Twitter
  3. Spring Social configuration
  4. Spring Security configuration
  5. JavaConfig
    • ApplicationInitializer.java
    • ApplicationContext.java
    • DataConfig.java
    • ThymeleafConfig.java
    • spring.properties
  6. View with Thymeleaf
  7. Layers
    • Domain
    • Repository
    • Service
    • Controller
  8. Running the application
    • Clone from GitHub
    • Create the Database
    • Run with Maven and Tomcat 7
    • Run with Maven and Jetty 8
    • Import to Eclipse
    • Validate with W3C

Dependencies

These are the main Maven dependencies:
  • Spring 3.2.0.RELEASE
  • Spring Data JPA 1.2.0.RELEASE
  • Spring Security 3.1.3.RELEASE
  • Thymeleaf 2.0.14
  • Hibernate 3.6.3.Final
  • See pom.xml for full details

Required Tools

These are the minimum required tools:
  • Git
  • Maven 3.0.4
  • MySQL
  • Eclipse IDE or SpringSource Tool Suite (STS)

GitHub Repository

There are two versions of the application: a JavaConfig-based and an XML config-based app. Both versions are identical in their feature set.

Functional Specs


Our application's requirements are the following:
  • Post to Facebook and Twitter
  • Retrieve profile information from Facebook and Twitter
  • Secure the application
  • Allow login and creation of new users
  • Create a page for managing users

Here's our Use Case diagrams:


[User]-(Post to Facebook)
[User]-(Post to Twitter)
[User]-(Retrieve info from Facebook)
[User]-(Retrieve info from Twitter)
[User]-(Sign in)
[User]-(Sign up)

//http://yuml.me/



[Admin]-(Edit users)
[Admin]-(Delete users)
[Admin]-(Add users)

//http://yuml.me/

Screenshots


Before we proceed, let's preview some screenshots of our application:

Sign in page


Sign up


Facebook Profile


Twitter Profile


Manage Users


Post to Facebook


Tweet to Tweeter


Connect to Social Site


Connected to Social Site



Next

In the next section, we will show how to generate the OAuth secret keys for Facebook and Twitter. Click here to proceed.

StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring Social with JavaConfig (Part 1) ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring Social with JavaConfig (Part 2)

Review

In the previous section, we have discussed the functional requirements of our application. In this section we will study how to generate OAuth keys for Facebook and Twitter. These are required so that Spring Social can communicate with these social media sites.

Table of Contents

Click on a link to jump to that section:
  1. Functional Specs
  2. Generate OAuth keys
    • Facebook
    • Twitter
  3. Spring Social configuration
  4. Spring Security configuration
  5. JavaConfig
    • ApplicationInitializer.java
    • ApplicationContext.java
    • DataConfig.java
    • ThymeleafConfig.java
    • spring.properties
  6. View with Thymeleaf
  7. Layers
    • Domain
    • Repository
    • Service
    • Controller
  8. Running the application
    • Clone from GitHub
    • Create the Database
    • Run with Maven and Tomcat 7
    • Run with Maven and Jetty 8
    • Import to Eclipse
    • Validate with W3C

Generate OAuth keys

Facebook

To generate a Facebook secret key, you need to sign-up for a Facebook account first. Once you have an account, follow these steps:
  1. Open a browser
  2. Visit https://developers.facebook.com/apps
  3. Click on Create New App
  4. Fill-in the App Name
  5. You will be redirected to the Basic settings page
  6. Now copy the App ID value. This is your client ID
  7. Then copy the App Secret value. This is your client secret

Note: The values need to be stored in the spring.properties file (see Part 5).

On my sample app, here's the Basic settings page. I've purposely changed the App ID and App Secret values:


Twitter

To generate a Twitter secret key, you need to sign-up for a Twitter account first. Once you have an account, follow these steps:
  1. Open a browser
  2. Visit https://dev.twitter.com/
  3. Visit the My applications page at https://dev.twitter.com/apps
  4. Click on Create a new application
  5. Fill-in the Name
  6. Fill-in the Description
  7. Fill-in the Website (You will need to invent a fictitious URL)
  8. You will be redirected to the Details tab of your new application
  9. Now copy the Consumer key value. This is your client ID
  10. Then copy the Consumer secret value. This is your client secret

Note: The values need to be stored in the spring.properties file (see Part 5).

On my sample app, here's the Details tab. I've purposely changed the Consumer key and Consumer secret values:



Next

In the next section, we will setup the Spring Social-related configuration through JavaConfig. Click here to proceed.
StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring Social with JavaConfig (Part 2) ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring Social with JavaConfig (Part 3)

Review

In the previous section, we have shown the steps on how to generate and retrieve the OAuth secret keys from Facebook and Twitter. In this section we will setup the Spring Social configuration settings through JavaConfig.

Table of Contents

Click on a link to jump to that section:
  1. Functional Specs
  2. Generate OAuth keys
    • Facebook
    • Twitter
  3. Spring Social configuration
  4. Spring Security configuration
  5. JavaConfig
    • ApplicationInitializer.java
    • ApplicationContext.java
    • DataConfig.java
    • ThymeleafConfig.java
    • spring.properties
  6. View with Thymeleaf
  7. Layers
    • Domain
    • Repository
    • Service
    • Controller
  8. Running the application
    • Clone from GitHub
    • Create the Database
    • Run with Maven and Tomcat 7
    • Run with Maven and Jetty 8
    • Import to Eclipse
    • Validate with W3C

Spring Social configuration


What is Spring Social?

Spring Social is an extension of the Spring Framework that allows you to connect your applications with Software-as-a-Service (SaaS) providers such as Facebook and Twitter.

Features:
  • An extensible service provider framework that greatly simplifies the process of connecting local user accounts to hosted provider accounts.
  • A connect controller that handles the authorization flow between your Java/Spring web application, a service provider, and your users.
  • Java bindings to popular service provider APIs such as Facebook, Twitter, LinkedIn, TripIt, and GitHub.
  • A sign-in controller that enables users to authenticate with your application by signing in through a service provider.
Source: http://www.springsource.org/spring-social

Here's our Spring Social configuration:

SocialConfig.java


Let me explain the contents of this configuration:

  • We have autowired the environment properties and the datasource
  • We have declared a ConnectionFactoryLocator which allows us to register connections to Facebook and Twitter. Notice how we passed the OAuth secret IDs and secret keys to the locator
  • We've declared a TextEncryptor for encrypting strings. This is required by Spring Social's JdbcUsersConnectionRepository
  • JdbcUsersConnectionRepository is used for persisting connections to a database through JDBC
  • ConnectionRepository allows a specific user to save and retrieve connections. We need to use this in conjunction with Spring Security because it provides us ready-made authenticated users. Notice how we assigned the current authenticated user
  • ConnectController is a controller for managing the connection flow to social media sites
  • HiddenHttpMethodFilter is required by Spring Social so that users can disconnect from social media sites. The filter needs to be declared in the web.xml or ApplicationInitializer

Note: If you need an in-depth explanation of each classes, please see the official Spring Social docs

Next

In the next section, we will focus on Spring Security-related configuration. Click here to proceed.
StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring Social with JavaConfig (Part 3) ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring Social with JavaConfig (Part 4)

Review

In the previous section, we have discussed the Spring Social-related configuration. In this section we will focus on Spring Security for securing our application.

Table of Contents

Click on a link to jump to that section:
  1. Functional Specs
  2. Generate OAuth keys
    • Facebook
    • Twitter
  3. Spring Social configuration
  4. Spring Security configuration
  5. JavaConfig
    • ApplicationInitializer.java
    • ApplicationContext.java
    • DataConfig.java
    • ThymeleafConfig.java
    • spring.properties
  6. View with Thymeleaf
  7. Layers
    • Domain
    • Repository
    • Service
    • Controller
  8. Running the application
    • Clone from GitHub
    • Create the Database
    • Run with Maven and Tomcat 7
    • Run with Maven and Jetty 8
    • Import to Eclipse
    • Validate with W3C

Spring Security


What is Spring Security?

Spring Security is a powerful and highly customizable authentication and access-control framework. It is the de-facto standard for securing Spring-based applications.

Spring Security is one of the most mature and widely used Spring projects. Founded in 2003 and actively maintained by SpringSource since, today it is used to secure numerous demanding environments including government agencies, military applications and central banks. It is released under an Apache 2.0 license so you can confidently use it in your projects.

Source: http://www.springsource.org/spring-security

Here's our Spring Security configuration:

SecurityConfig.java

First, we declare a DelegatingFilterProxy bean using JavaConfig. This allows Spring Security to intercept requests to our application and verify if the required authentication and authorization are met. This bean needs to be registered in the web.xml (or ApplicationInitializer) as a filter (see next section).

Second, we declare the usual XML-based configuration. This allows us to define the intercept-url patterns. Why are we not using JavaConfig here? Because the XML-based configuration is simpler, less-verbose, and easier:

spring-security.xml


For an in-depth explanation of this configuration, please see my tutorial on Spring Security 3.1 - Implement UserDetailsService with Spring Data JPA

Next

In the next section, we will study the remaining JavaConfig-based configuration. Click here to proceed.
StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring Social with JavaConfig (Part 4) ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring Social with JavaConfig (Part 5)

Review

In the previous section, we have discussed the Spring Security-related configurations. In this section we will discuss the remaining configuration of our application.

Table of Contents

Click on a link to jump to that section:
  1. Functional Specs
  2. Generate OAuth keys
    • Facebook
    • Twitter
  3. Spring Social configuration
  4. Spring Security configuration
  5. JavaConfig
    • ApplicationInitializer.java
    • ApplicationContext.java
    • DataConfig.java
    • ThymeleafConfig.java
    • spring.properties
  6. View with Thymeleaf
  7. Layers
    • Domain
    • Repository
    • Service
    • Controller
  8. Running the application
    • Clone from GitHub
    • Create the Database
    • Run with Maven and Tomcat 7
    • Run with Maven and Jetty 8
    • Import to Eclipse
    • Validate with W3C

JavaConfig

As stated in the introduction, we will be using JavaConfig-based configuration instead of the usual XML config. However, I don't want to alienate our readers who are used to XML. As a result, I've decided to provide both implementations. However, our focus here is still on JavaConfig.

Note: With JavaConfig, we can now omit the ubiquitous web.xml. But in order to that, we need to run a Servlet 3.0 web container. For this tutorial, I have tested the application with Tomcat 7.0.30 (Maven plugin), 7.0.33 (standalone Tomcat), and Jetty 8.1.5.v20120716 (Maven plugin).

ApplicationInitializer.java

The ApplicationInitializer.java is the equivalent of web.xml. Here's where we declare the DispatcherServlet and also we've registered two filters: one for Spring Security and another for Spring Social.



Here's the equivalent XML configuration:



ApplicationContext.java

The ApplicationContext.java contains our main configuration. It's responsible for loading other configurations, either as JavaConfig or XML config.



Let's describe each annotation:
  • @Configuration
    - Marks a class as a JavaConfig
  • @ComponentScan(basePackages = {"org.krams"})
    - Configures scanning of Spring components

    This is equivalent in XML as:

  • @EnableWebMvc

    - Activates Spring's MVC support

    This is equivalent in XML as:

  • @Import({DataConfig.class, ThymeleafConfig.class, SocialConfig.class, SecurityConfig.class})
    - This allows us to import JavaConfig-based config. Notice we have imported four configuration classes
  • @ImportResource("classpath:trace-context.xml")
    - This allows us to import XML-based config files. (As a side note why can't we just declare this as a JavaConfig? It turns out there's no direct translation for the trace-context.xml, so we'll have to import it as XML).

    This is equivalent in XML as:

  • @PropertySource("classpath:spring.properties")
    - This allows us to import property files
  • @Bean
    - Declares a Spring bean

Here's the equivalent XML configuration:



DataConfig.java

The DataConfig.java contains our Spring Data configuration. This is where we declare our data source, transaction manager, and JPA entity manager.



Here's the equivalent XML configuration:



ThymeleafConfig.java

The ThymeleafConfig.java contains our Thymeleaf configuration. This is where we declare our Thymeleaf view resolver.


We've declared some special settings on our Thymeleaf configuration:
// Declare virtual paths
resolver.addTemplateAlias("connect/facebookConnect","facebook/connect");
resolver.addTemplateAlias("connect/twitterConnect","twitter/connect");
resolver.addTemplateAlias("connect/facebookConnected","facebook/connected");
resolver.addTemplateAlias("connect/twitterConnected","facebook/connected");

// Disable cache for testing purposes
resolver.setCacheable(false);

These allows to redirect virtual path requests to specific templates within our application. We need to do this because the ConnectController from Spring Social has its own built-in controller path requests. And we need to redirect the resulting views that matches our template path.

For example, when connecting to Facebook, ConnectController will use the connect/facebookConnect path and you are required to provide a view. Using the addTemplateAlias() method, we can provide a custom view, in this case, the view points to the directory in the WEB-INF/templates/facebook/connect.

Also, we've disabled the caching feature so that we can easily update and test our html pages.

Here's the equivalent XML configuration:


SecurityConfig.java

The SecurityConfig.java contains a single bean DelegatingFilterProxy. This is required for Spring Security.



spring.properties

spring.properties contains the property settings of our application. You need to declare your Facebook and Twitter OAuth settings here. Here's also where you declare your database.


messages_en.properties

This is for internationalization of messages. The default language is English. If you need to provide custom language, create a new properties file and replace the values according to the language you've chosen. Please see the Spring documentation for more info on internationalization.



Next

In the next section, we will discuss the Domain, Service, Controller, and View layers. Click here to proceed.
StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring Social with JavaConfig (Part 5) ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring Social with JavaConfig (Part 6)

Review

In the previous section, we have discussed the remaining JavaConfig configurations. In this section, we will discuss the View layer along with Thymeleaf.

Table of Contents

Click on a link to jump to that section:
  1. Functional Specs
  2. Generate OAuth keys
    • Facebook
    • Twitter
  3. Spring Social configuration
  4. Spring Security configuration
  5. JavaConfig
    • ApplicationInitializer.java
    • ApplicationContext.java
    • DataConfig.java
    • ThymeleafConfig.java
    • spring.properties
  6. View with Thymeleaf
  7. Layers
    • Domain
    • Repository
    • Service
    • Controller
  8. Running the application
    • Clone from GitHub
    • Create the Database
    • Run with Maven and Tomcat 7
    • Run with Maven and Jetty 8
    • Import to Eclipse
    • Validate with W3C

View with Thymeleaf


The goal of this section is not to teach you everything about Thymeleaf but to point out the important sections. If you need a full Thymeleaf documentation, please see the official docs.

What is Thymeleaf?

Thymeleaf is a Java library. It is an XML / XHTML / HTML5 template engine (extensible to other formats) that can work both in web and non-web environments. It is better suited for serving XHTML/HTML5 at the view layer of web applications, but it can process any XML file even in offline environments.

It provides an optional module for integration with Spring MVC, so that you can use it as a complete substitute of JSP in your applications made with this technology, even with HTML5.

The main goal of Thymeleaf is to provide an elegant and well-formed way of creating templates. Its Standard and SpringStandard dialects allow you to create powerful natural templates, that can be correctly displayed by browsers and therefore work also as static prototypes. You can also extend Thymeleaf by developing your own dialects.

Source: Thymeleaf.org

Since we have numerous html pages with duplicate setup, I will focus on the ones that are most instructive.

Facebook profile.html
This displays our Facebook profile information.



Let's discuss the important attributes
  • The # means to resolve the attribute from the messages bundle
  • The $ means to resolve the attribute from the model
  • The # and $ can be combined together so that messages can be dynamically generated from the model and internationalized from the messages bundle
  • th:href attribute
    <link rel="stylesheet" href="../../../resources/css/style.css"  th:href="@{/resources/css/style.css}" />
    
    Declares a resource relative to the context of the app. When testing the html mockup, the th:href attribute is ignored by the browser. When running the app, Thymeleaf's preprocessor will ignore the value of the href attribute and use the value in the th:ref attribute.
  • th:text attribute
    <title th:text="#{'profile.title.' + ${source}}">Title</title>
    
    Declares the usual title element. When testing the html mockup, the th:text attribute is ignored by the browser. When running the app, Thymeleaf's preprocessor will ignore the value of the title and use the value in the th:text attribute.

    This is a common attribute. So pay attention to this one.
  • th:include attribute
    <div th:include="include :: menu"></div>
    
    Includes an html fragment. The fragment is declared in the include.html
  • th:src attribute
    <img src="#" th:src="@{'http://graph.facebook.com/' +  ${profileInfo.id}} + '/picture'" alt="profile image"/>    
    
    Declares an image element. The attribute th:src is similar with the th:href behavior.

    The value of th:src contains two parts: 'http://graph.facebook.com/' which is a literal string and ${profileInfo.id} is a model attribute. The value is sent by our Spring controller (see below):


  • th:if attribute
    <dd th:if="${#strings.isEmpty(profileInfo.email)}" th:text="'no email listed'">john@email.com</dd>     
    
    A conditional expression. This states "if the profileInfo.email attribute is empty, print out 'no email listed', but if it's not empty, then print out the value.

Note: To see the remaining html pages, please visit the Github repository. I've omitted them here because most of the Thymeleaf tags we've discussed here are also the same ones we've used on those pages.

login.html
This is the login page. We've shown it here because this is used by Spring Security for rendering the login page.



For more info, please see Spring Security 3.1 - Implement UserDetailsService with Spring Data JPA tutorial.

Next

In the next section, we will focus on the Domain, Repository, Service, and Controller classes Click here to proceed.
StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring Social with JavaConfig (Part 6) ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring Social with JavaConfig (Part 7)

Review

In the previous section, we have discussed the View layer along with Thymeleaf. In this section, we will focus on the Domain, Repository, Service, and Controller classes.

Table of Contents

Click on a link to jump to that section:
  1. Functional Specs
  2. Generate OAuth keys
    • Facebook
    • Twitter
  3. Spring Social configuration
  4. Spring Security configuration
  5. JavaConfig
    • ApplicationInitializer.java
    • ApplicationContext.java
    • DataConfig.java
    • ThymeleafConfig.java
    • spring.properties
  6. View with Thymeleaf
  7. Layers
    • Domain
    • Repository
    • Service
    • Controller
  8. Running the application
    • Clone from GitHub
    • Create the Database
    • Run with Maven and Tomcat 7
    • Run with Maven and Jetty 8
    • Import to Eclipse
    • Validate with W3C

Layers

Domain


Our domain layer consists of two simple classes: User.java and Role.java. By annotating these classes with @Entity we're declaring these classes as JPA entities and consequently will be persisted to a database.

The User class contains the following properties: first name, last name, username, role, and password. For the Role class, we only have two values: an admin and a regular user.





Although this is not part of the domain layer, we've included the UserDto here. This DTO is used for transferring user information to the view layer.



Controller


We have five controllers:
  • AccessController is responsible for managing login and signup requests
  • FacebookController is responsible for handling Facebook requests
  • TwitterController is responsible for handling Twitter requests
  • UserController is responsible for handling User CRUD operations
  • MediatorController simply handles call to the root page

AccessController.java


FacebookController.java


MediatorController.java


TwitterController.java


UserController.java


Repository


We have a simple repository. There's nothing much to explain here.

UserRepository.java


Service


We have two services:
  • UserService is used for handling user-related CRUD operations
  • RepositoryBasedUserDetailsService is used for retrieving user details for authentication purposes

UserService.java


RepositoryBasedUserDetailsService.java

Next

In the next section, we will study how to build and run our application. We will use Maven, Tomcat, and Jetty to run the app. We'll also study how to import the project in Eclipse. Click here to proceed.
StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring Social with JavaConfig (Part 7) ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring Social with JavaConfig (Part 8)

Review


In the previous section, we have discussed the Domain, Repository, Service, Controller layers. In this section, we will build and run our sample application. We will verify if our application is able to communicate with Facebook and Twitter. We will also show how to import the project in Eclipse.


Table of Contents

Click on a link to jump to that section:
  1. Functional Specs
  2. Generate OAuth keys
    • Facebook
    • Twitter
  3. Spring Social configuration
  4. Spring Security configuration
  5. JavaConfig
    • ApplicationInitializer.java
    • ApplicationContext.java
    • DataConfig.java
    • ThymeleafConfig.java
    • spring.properties
  6. View with Thymeleaf
  7. Layers
    • Domain
    • Repository
    • Service
    • Controller
  8. Running the application
    • Clone from GitHub
    • Create the Database
    • Run with Maven and Tomcat 7
    • Run with Maven and Jetty 8
    • Import to Eclipse
    • Validate with W3C

Running the Application


Clone from GitHub

To clone from GitHub, follow these instructions:
  1. Open a Git terminal
  2. Enter the following command:
    git clone https://github.com/krams915/spring-social-javaconfig.git
    This will clone the JavaConfig-based application.

    If you prefer the XML-based version,
    git clone https://github.com/krams915/spring-social-xmlconfig.git

    Remember:

    There are two versions of our application: a JavaConfig-based and an XML config-based app. Both versions are identical in their feature set.

Create the Database

  1. Run MySQL
  2. Create a new database:
    spring_social_tutorial
  3. Import the following SQL files:
    spring_social_tutorial.sql
    JdbcUsersConnectionRepository.sql
    

    These files can be found at the src/main/resources path

Run with Maven and Tomcat 7

Ensure Maven is installed first, and you have created the MySQL database
  1. Open a terminal
  2. Browse to the directory where you've cloned the project
  3. Enter the following command:
    mvn tomcat7:run
  4. You should see the following output:
    [INFO] Scanning for projects...
    [INFO]                                                                         
    [INFO] -------------------------------------------------------------
    [INFO] Building spring-social-tutorial Maven Webapp 0.0.1-SNAPSHOT
    [INFO] -------------------------------------------------------------
    [INFO] 
    [INFO] >>> tomcat7-maven-plugin:2.0:run (default-cli) @ spring-social-tutorial >>>
    ...
    ...
    ...
    Dec 10, 2012 9:50:56 AM org.apache.coyote.AbstractProtocol init
    INFO: Initializing ProtocolHandler ["http-bio-8080"]
    Dec 10, 2012 9:50:56 AM org.apache.catalina.core.StandardService startInternal
    INFO: Starting service Tomcat
    Dec 10, 2012 9:50:56 AM org.apache.catalina.core.StandardEngine startInternal
    INFO: Starting Servlet Engine: Apache Tomcat/7.0.30
    Dec 10, 2012 9:51:07 AM org.apache.catalina.core.ApplicationContext log
    INFO: Spring WebApplicationInitializers detected on classpath: [org.krams.config.ApplicationInitializer@73b8cdd5]
    Dec 10, 2012 9:51:08 AM org.apache.catalina.core.ApplicationContext log
    INFO: Initializing Spring root WebApplicationContext
    Dec 10, 2012 9:51:18 AM org.apache.catalina.core.ApplicationContext log
    INFO: Initializing Spring FrameworkServlet 'dispatcher'
    Dec 10, 2012 9:51:18 AM org.apache.coyote.AbstractProtocol start
    INFO: Starting ProtocolHandler ["http-bio-8080"]
    
  5. Open a browser
  6. Visit the entry page:
    http://localhost:8080/spring-social-tutorial
  7. The primary admin credentials are the following:
    username: john
    password: admin

    You can create a new account but by default it doesn't have any admin powers.

Run with Maven and Jetty 8

Ensure Maven is installed first, and you have created the MySQL database.
  1. Open a terminal
  2. Browse to the directory where you've cloned the project
  3. Enter the following command:
    mvn jetty:run
  4. You should see the following output:
    [INFO] Scanning for projects...
    [INFO]                                                                         
    [INFO] -------------------------------------------------------------
    [INFO] Building spring-social-tutorial Maven Webapp 0.0.1-SNAPSHOT
    [INFO] -------------------------------------------------------------
    [INFO] 
    [INFO] >>> jetty-maven-plugin:8.1.5.v20120716:run (default-cli) @ spring-social-tutorial >>>
    ...
    ...
    ...
    2012-12-10 09:53:55.980:INFO:/spring-social-tutorial:Initializing Spring FrameworkServlet 'dispatcher'
    2012-12-10 09:53:56.140:INFO:oejs.AbstractConnector:Started SelectChannelConnector@0.0.0.0:8080
    [INFO] Started Jetty Server
    
  5. Open a browser
  6. Visit the entry page:
    http://localhost:8080/spring-social-tutorial
  7. The primary admin credentials are the following:
    username: john
    password: admin

    You can create a new account but by default it doesn't have any admin powers.

Import to Eclipse

Ensure Maven is installed first
  1. Open a terminal
  2. Enter the following command:
    mvn eclipse:eclipse -Dwtpversion=2.0
  3. You should see the following output:
    [INFO] Scanning for projects...
    [INFO]                                                                         
    [INFO] -------------------------------------------------------------
    [INFO] Building spring-social-tutorial Maven Webapp 0.0.1-SNAPSHOT
    [INFO] -------------------------------------------------------------
    [INFO] 
    [INFO] >>> maven-eclipse-plugin:2.9:eclipse (default-cli) @ spring-social-tutorial >>>
    ...
    ...
    ... 
    [INFO] -------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] -------------------------------------------------------------
    [INFO] Total time: 9.532s
    [INFO] Finished at: Mon Dec 10 09:55:31 PHT 2012
    [INFO] Final Memory: 17M/81M
    [INFO] -------------------------------------------------------------
    

    This command will add the following files to your project:
    .classpath
    .project
    .settings
    target
    You may have to enable "show hidden files" in your file explorer to view them.
  4. Run Eclipse and import the application as Maven project

Validate with W3C Markup Validation Service

One of the promises of using Thymeleaf is it produces valid HTML pages. Let's test that out using W3C validation service.
  1. Run the application
  2. Open a browser
  3. Visit the following URLs and validate them all:
    http://localhost:8080/spring-social-tutorial/
    http://localhost:8080/spring-social-tutorial/login
    http://localhost:8080/spring-social-tutorial/users
    http://localhost:8080/spring-social-tutorial/fb/profile
    http://localhost:8080/spring-social-tutorial/tw/profile
    http://localhost:8080/spring-social-tutorial/fb/post
    http://localhost:8080/spring-social-tutorial/tw/post
  4. View the HTML source (right-click or go to menu)
  5. Copy the HTML source
  6. Open W3C Markup Validation Service at http://validator.w3.org/#validate_by_input
  7. Paste the HTML source and wait for the validation result

    You should see a similar output:

Conclusion


We've have completed our Spring Social-based application using JavaConfig. We're able to post and retrieve profile information from Facebook and Twitter. To provide authentication and security we've added Spring Security. For managing the view layer, we've integrated Thymeleaf as our template engine. As a bonus, we've also provided an XML-based application.

I hope you've enjoyed this tutorial. Don't forget to check my other tutorials at the Tutorials section.

Revision History

Revision Date Description
1 Dec 10 2012 Uploaded tutorial and GitHub repositories
2 Dec 21 2012 Update to Spring 3.2.0.RELEASE

StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring Social with JavaConfig (Part 8) ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Sunday, December 2, 2012

Spring and Thymeleaf with JavaConfig (Part 1)

In this tutorial, we will create a CRUD application based on Spring MVC 3.x and Spring Data JPA. We will utilize JavaConfig instead of XML to configure our application. For the view layer, we will use Thymeleaf as our template engine instead of JSP to process our html pages.

Table of Contents

Click on a link to jump to that section:
  1. Functional Specs
  2. Creating the View
    • HTML Mockup
    • Thymeleaf Integration
  3. JavaConfig
    • ApplicationContext.java
    • SpringDataConfig.java
    • ThymeleafConfig.java
    • ApplicationInitializer.java
  4. Layers
    • Domain
    • Service
    • Controller
  5. Running the application
    • Clone from GitHub
    • Create the Database
    • Run with Maven and Tomcat 7
    • Run with Maven and Jetty 8
    • Import to Eclipse
    • Validate with W3C

Dependencies

These are the main Maven dependencies:
  • Spring 3.2.0.RC1
  • Spring Data JPA 1.2.0.RELEASE
  • Thymeleaf 2.0.14
  • Hibernate 3.6.3.Final
  • See pom.xml for full details

Required Tools

These are the minimum required tools:
  • Git
  • Maven 3.0.4
  • MySQL
  • Eclipse IDE or SpringSource Tool Suite (STS)

GitHub Repository

There are two versions of the application: a JavaConfig-based and an XML config-based app. Both versions are identical in their feature set.

Functional Specs


Our application's requirements are quite straightforward:
  • Create a simple form to manage user information
  • Provide the following fields: first name, last name, username, role
  • Username must be unique
  • Provide CRUD operations
  • Provide table to view all users

Here's our Use Case diagram:


[User]-(Add)
[User]-(View)
[User]-(Update)
[User]-(Delete)

//http://yuml.me/

Here's a screenshot of our working application:


Next

In the next section, we will focus on the view layer. We'll start writing the HTML mockup template; then we'll integrate it with Thymeleaf. Click here to proceed.
StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring and Thymeleaf with JavaConfig (Part 1) ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring and Thymeleaf with JavaConfig (Part 2)

Review


In the previous section, we have read the functional specs of the application. In this section, we will focus on the view layer, create an HTML mockup, and integrate our mockup with Thymeleaf.

Table of Contents

Click on a link to jump to that section:
  1. Functional Specs
  2. Creating the View
    • HTML Mockup
    • Thymeleaf Integration
  3. JavaConfig
    • ApplicationContext.java
    • SpringDataConfig.java
    • ThymeleafConfig.java
    • ApplicationInitializer.java
  4. Layers
    • Domain
    • Service
    • Controller
  5. Running the application
    • Clone from GitHub
    • Create the Database
    • Run with Maven and Tomcat 7
    • Run with Maven and Jetty 8
    • Import to Eclipse
    • Validate with W3C

Creating the View


In designing our application we'll start with the view layer because we can. Thanks to Thymeleaf creating HTML mockups is easy. Thymeleaf allows us to use these mockups as our HTML templates without any aesthetic changes. In addition, it passes W3C Markup Validation Service with flying colors.

What is Thymeleaf?

Thymeleaf is a Java library. It is an XML / XHTML / HTML5 template engine (extensible to other formats) that can work both in web and non-web environments. It is better suited for serving XHTML/HTML5 at the view layer of web applications, but it can process any XML file even in offline environments.

It provides an optional module for integration with Spring MVC, so that you can use it as a complete substitute of JSP in your applications made with this technology, even with HTML5.

The main goal of Thymeleaf is to provide an elegant and well-formed way of creating templates. Its Standard and SpringStandard dialects allow you to create powerful natural templates, that can be correctly displayed by browsers and therefore work also as static prototypes. You can also extend Thymeleaf by developing your own dialects.

Source: Thymeleaf.org

HTML Mockup


Let's create our HTML mockup. You can see the final mockup below:


First, we create a new HTML page. Note that this is a very simple HTML document that validates with W3C Markup Validation Service.



Next, we create an external CSS file. Because I'm not really a designer, I have scoured the web for a simple but elegant table style. I found one from Top 10 CSS Table Designs.



Then, open a browser and test the HTML mockup. You should see something similar to the following image:



Thymeleaf Integration


It's time to integrate Thymeleaf with our HTML mockup template. To integrate Thymeleaf we'll use its attribute-based template engine. Browsers will normally ignore unknown HTML attributes, so it won't affect our mockups.

Before we proceed, let me provide you a short description of the specific Thymeleaf attributes we'll be using:

The important attributes
  • The # means to resolve the attribute from the messages bundle
  • The $ means to resolve the attribute from the model
  • The # and $ can be combined together so that messages can be dynamically generated from the model and internationalized from the messages bundle
  • th:fragment="header"

    This allows us to include template fragments from other templates. For example, we can reuse them in footers, headers, and menus. For this tutorial, we won't be reusing the header, but I've added it anyway for future tutorials.
  • th:each="u : ${users}

    This allows us to loop a list of records. This is equivalent to Java's for-loop construct.
  • th:text="${u.id}"

    This allows to dynamically set the label of an element.
  • th:href="@{/users/delete(id=${u.id})}">

    This allows us to define a dynamic URL.
  • th:field="*{id}"

    This allows us to define the field where an input's field will be attached to.
  • th:remove="all"

    This allows us to setup mockup data. Thymeleaf will automatically remove any element contained within this attribute.

Let's now apply these attributes. Here's our updated HTML mockup template:

users.html

Internationalization


The th:text attribute allows us to externalize text and with the support of Spring's MessageSource, we are able to parameterize and provide internationalization support.

What is MessageSource?

Strategy interface for resolving messages, with support for the parameterization and internationalization of such messages.

Spring provides two out-of-the-box implementations for production:
  • ResourceBundleMessageSource, built on top of the standard ResourceBundle
  • ReloadableResourceBundleMessageSource, being able to reload message definitions without restarting the VM

Source: Spring 3 Docs: MessageSource

Notice the th:text attributes. Some of them refer to a dot notation object. Where does Thymeleaf retrieve this information?

The information is retrieved from the messages_en.properties resource bundle:


We've declared that in the ApplicationContext.java configuration (see next section):



The Data transfer object (DTO)


In order for our html page to display data from the Controller, we need to pass a Model attribute. The model attribute is represented by the UserDto.



The fields we declared on the users.html form is based from the fields of the UserDto:



Notice the form has a form-backing object declared named commanduser. Using Thymeleaf's attribute th:object, we're able to declare this form-backing object.

This object passed from the UserController.



Next

In the next section, we will focus on the configuration layer. We'll study how to declare a JavaConfig-based configuration. We'll also provide an XML-based configuration for comparison purposes. Click here to proceed.
StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring and Thymeleaf with JavaConfig (Part 2) ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring and Thymeleaf with JavaConfig (Part 3)

Review


In the previous section, we focused on the view layer and created an HTML mockup template. In this section, we will focus on configuration and declare them using JavaConfig. We will also provide an XML-based config.

Table of Contents

Click on a link to jump to that section:
  1. Functional Specs
  2. Creating the View
    • HTML Mockup
    • Thymeleaf Integration
  3. JavaConfig
    • ApplicationContext.java
    • SpringDataConfig.java
    • ThymeleafConfig.java
    • ApplicationInitializer.java
  4. Layers
    • Domain
    • Service
    • Controller
  5. Running the application
    • Clone from GitHub
    • Create the Database
    • Run with Maven and Tomcat 7
    • Run with Maven and Jetty 8
    • Import to Eclipse
    • Validate with W3C

JavaConfig


As stated in the introduction, we will be using JavaConfig-based configuration instead of the usual XML config. However, I don't want to alienate our readers who are used to XML. As a result, I've decided to provide both implementations. However, our focus here is still on JavaConfig.

Note: With JavaConfig, we can now omit the ubiquitous web.xml. But in order to that, we need to run a Servlet 3.0 web container. For this tutorial, I have tested the application with Tomcat 7.0.30 (Maven plugin), 7.0.33 (standalone Tomcat), and Jetty 8.1.5.v20120716 (Maven plugin).

ApplicationContext.java


The ApplicationContext.java contains our main configuration. It's responsible for loading other configurations, either as JavaConfig or XML config.



Let's describe each annotation:
  • @Configuration
    - Marks a class as a JavaConfig
  • @ComponentScan(basePackages = {"org.krams"})
    - Configures scanning of Spring components

    This is equivalent in XML as:

  • @EnableWebMvc

    - Activates Spring's MVC support

    This is equivalent in XML as:

  • @Import({SpringDataConfig.class, ThymeleafConfig.class})
    - This allows us to import JavaConfig-based config. Notice we are importing two external configuration classes: SpringDataConfig and ThymeleafConfig
  • @ImportResource("classpath:trace-context.xml")
    - This allows us to import XML-based config files. (As a side note why can't we just declare this as a JavaConfig? It turns out there's no direct translation for the trace-context.xml, so we'll have to import it as XML).

    This is equivalent in XML as:

  • @PropertySource("classpath:spring.properties")
    - This allows us to import property files
  • @Bean
    - Declares a Spring bean

Here's the equivalent XML configuration:



SpringDataConfig.java


The SpringDataConfig.java contains our Spring Data configuration. This is where we declare our data source, transaction manager, and JPA entity manager.



Here's the equivalent XML configuration:



ThymeleafConfig.java


The ThymeleafConfig.java contains our Thymeleaf configuration. This is where we declare our Thymeleaf view resolver.



Here's the equivalent XML configuration:



ApplicationInitializer.java


The ApplicationInitializer.java is the equivalent of web.xml. Here's where we declare the DispatcherServlet.



Here's the equivalent XML configuration:



Next

In the next section, we will focus on the remaining layers of our Java application. We'll study the Domain, Repository, Service, and Controller layers. Click here to proceed.
StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring and Thymeleaf with JavaConfig (Part 3) ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring and Thymeleaf with JavaConfig (Part 4)

Review


In the previous section, we declared our configuration using JavaConfig and compared it side-by-side with an XML-based configuration. In this section, we will discuss the remaining layers of our application.

Table of Contents

Click on a link to jump to that section:
  1. Functional Specs
  2. Creating the View
    • HTML Mockup
    • Thymeleaf Integration
  3. JavaConfig
    • ApplicationContext.java
    • SpringDataConfig.java
    • ThymeleafConfig.java
    • ApplicationInitializer.java
  4. Layers
    • Domain
    • Service
    • Controller
  5. Running the application
    • Clone from GitHub
    • Create the Database
    • Run with Maven and Tomcat 7
    • Run with Maven and Jetty 8
    • Import to Eclipse
    • Validate with W3C

Layers


Here we'll discuss the Domain, Repository, Service and Controller layers.

Domain

Our domain layer consists of two simple classes: User.java and Role.java. If you'd been following my previous tutorials, you will notice that these are the same domain classes we'd been using before. Both classes had been annotated with @Entity which means these are JPA entities and will be persisted to a database.

These classes represent a user with the following properties: first name, last name, username, role, and password (we're not actively using the password field).

For role, we only have two values: an admin or a regular user.

User.java


Role.java


Controller

Our controller is a standard controller providing CRUD requests. The most important lines here are the following:

// Create
model.addAttribute("users", UserMapper.map(users));
model.addAttribute("commanduser", new UserDto());
model.addAttribute("usertype", "new");

// Update
model.addAttribute("users", UserMapper.map(users));
model.addAttribute("commanduser", UserMapper.map(repository.findOne(id)));
model.addAttribute("usertype", "update");

These lines adds three attributes to the model:
  • users - contains all users
  • commanduser - the form backing object or the command object of the form
  • usertype - an attribute to determine if the request is a new user or existing user
UserController.java

Repository

We have created two repositories: UserRepository and RoleRepository(not shown). We will be using UserRepository as our primary data access object. Notice we have declared a custom method findByUsername but beyond that, this repository is pretty much standard. UserRepository.java

Service

Our service layer basically delegates to the repository. It provides an extra logic to filter out duplicate usernames. UserService.java

Next

In the next section, we will study how to build and run our application. We will be using Maven, Tomcat, and Jetty to run the app. We'll also study how to import the project in Eclipse. Click here to proceed.
StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring and Thymeleaf with JavaConfig (Part 4) ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring and Thymeleaf with JavaConfig (Part 5)

Review


In the previous section, we have discussed the Domain, Repository, Service, and Controller classes. In this section, we will build and run our app. We will also study how to import the project in Eclipse.

Table of Contents

Click on a link to jump to that section:
  1. Functional Specs
  2. Creating the View
    • HTML Mockup
    • Thymeleaf Integration
  3. JavaConfig
    • ApplicationContext.java
    • SpringDataConfig.java
    • ThymeleafConfig.java
    • ApplicationInitializer.java
  4. Layers
    • Domain
    • Service
    • Controller
  5. Running the application
    • Clone from GitHub
    • Create the Database
    • Run with Maven and Tomcat 7
    • Run with Maven and Jetty 8
    • Import to Eclipse
    • Validate with W3C

Running the Application


Clone from GitHub

To clone from GitHub, follow these instructions:
  1. Open a Git terminal
  2. Enter the following command:
    git clone https://github.com/krams915/spring-thymeleaf-javaconfig.git
    This will clone the JavaConfig-based application.

    If you prefer the XML-based version,
    git clone https://github.com/krams915/spring-thymeleaf-xmlconfig.git

    Remember:

    There are two versions of the application: a JavaConfig-based and an XML config-based app. Both versions are identical in their feature set.

Create the Database

  1. Run MySQL
  2. Create a new database:
    spring_thymeleaf_tutorial
  3. Import the spring_thymeleaf_tutorial.sql from the src/main/resources path

Run with Maven and Tomcat 7

Ensure Maven is installed first, and you have created the MySQL database
  1. Open a terminal
  2. Browse to the directory where you've cloned the project
  3. Enter the following command:
    mvn tomcat7:run
  4. You should see the following output:
    [INFO] Scanning for projects...
    [INFO]                                                                         
    [INFO] -------------------------------------------------------------
    [INFO] Building spring-thymeleaf-tutorial Maven Webapp 0.0.1-SNAPSHOT
    [INFO] -------------------------------------------------------------
    [INFO] 
    [INFO] >>> tomcat7-maven-plugin:2.0:run (default-cli) @ spring-thymeleaf-tutorial >>>
    ...
    ...
    ...
    Dec 2, 2012 5:38:31 PM org.apache.coyote.AbstractProtocol init
    INFO: Initializing ProtocolHandler ["http-bio-8080"]
    Dec 2, 2012 5:38:31 PM org.apache.catalina.core.StandardService startInternal
    INFO: Starting service Tomcat
    Dec 2, 2012 5:38:31 PM org.apache.catalina.core.StandardEngine startInternal
    INFO: Starting Servlet Engine: Apache Tomcat/7.0.30
    Dec 2, 2012 5:38:42 PM org.apache.catalina.core.ApplicationContext log
    INFO: Spring WebApplicationInitializers detected on classpath: [org.krams.config.ApplicationInitializer@1cc33893]
    Dec 2, 2012 5:38:43 PM org.apache.catalina.core.ApplicationContext log
    INFO: Initializing Spring root WebApplicationContext
    Dec 2, 2012 5:38:52 PM org.apache.catalina.core.ApplicationContext log
    INFO: Initializing Spring FrameworkServlet 'dispatcher'
    Dec 2, 2012 5:38:52 PM org.apache.coyote.AbstractProtocol start
    INFO: Starting ProtocolHandler ["http-bio-8080"]
    
  5. Open a browser
  6. Visit the following URL:
    http://localhost:8080/spring-thymeleaf-tutorial/users

Run with Maven and Jetty 8

Ensure Maven is installed first, and you have created the MySQL database.
  1. Open a terminal
  2. Browse to the directory where you've cloned the project
  3. Enter the following command:
    mvn jetty:run
  4. You should see the following output:
    [INFO] Scanning for projects...
    [INFO]                                                                         
    [INFO] -------------------------------------------------------------
    [INFO] Building spring-thymeleaf-tutorial Maven Webapp 0.0.1-SNAPSHOT
    [INFO] -------------------------------------------------------------
    [INFO] 
    [INFO] >>> jetty-maven-plugin:8.1.5.v20120716:run (default-cli) @ spring-thymeleaf-tutorial >>>
    ...
    ...
    ...
    2012-12-02 17:42:56.556:INFO:/spring-thymeleaf-tutorial:Initializing Spring FrameworkServlet 'dispatcher'
    2012-12-02 17:42:56.760:INFO:oejs.AbstractConnector:Started SelectChannelConnector@0.0.0.0:8080
    [INFO] Started Jetty Server
    
  5. Open a browser
  6. Visit the following URL:
    http://localhost:8080/spring-thymeleaf-tutorial/users

Import to Eclipse

Ensure Maven is installed first
  1. Open a terminal
  2. Enter the following command:
    mvn eclipse:eclipse -Dwtpversion=2.0
  3. You should see the following output:
    [INFO] Scanning for projects...
    [INFO]                                                                         
    [INFO] -------------------------------------------------------------
    [INFO] Building spring-thymeleaf-tutorial Maven Webapp 0.0.1-SNAPSHOT
    [INFO] -------------------------------------------------------------
    [INFO] 
    [INFO] >>> maven-eclipse-plugin:2.9:eclipse (default-cli) @ spring-thymeleaf-tutorial >>>
    ...
    ...
    ... 
    [INFO] -------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] -------------------------------------------------------------
    [INFO] Total time: 9.356s
    [INFO] Finished at: Sun Dec 02 17:46:43 PHT 2012
    [INFO] Final Memory: 15M/81M
    [INFO] -------------------------------------------------------------
    

    This command will add the following files to your project:
    .classpath
    .project
    .settings
    target
    You may have to enable "show hidden files" in your file explorer to view them.
  4. Run Eclipse and import the application as Maven project

Validate with W3C Markup Validation Service

One of the promises of Thymeleaf is it produces valid HTML pages. Let's test that out using W3C validation service.
  1. Run the application
  2. Open a browser
  3. Visit the following URL:
    http://localhost:8080/spring-thymeleaf-tutorial/users
  4. View the HTML source (right-click or go to menu)
  5. Copy the HTML source
  6. Open W3C Markup Validation Service at http://validator.w3.org/#validate_by_input
  7. Paste the HTML source and wait for the validation result

    You should see a similar output:

Conclusion


We've have completed our Spring MVC application with Thymeleaf as our template engine . We've studied how to convert our HTML mockup into a Thymeleaf template that validates with W3C validator service. We've also discussed how to create a JavaConfig-based application. As a bonus, we've also provided an XML-based application.

I hope you've enjoyed this tutorial. Don't forget to check my other tutorials at the Tutorials section.

Revision History

Revision Date Description
1 Dec 2 2012 Uploaded tutorial and GitHub repositories
2 Dec 3 2012 Updated table of contents
3 Dec 12 2012 Updated Part 2

StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring and Thymeleaf with JavaConfig (Part 5) ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share