We will start with creating a basic simple project skeleton and Spring Boot will help us in this:

You will see the Project Dependencies section, where we can choose the kind of functionalities that our application will perform: will it connect to a database, will it have a web interface, do we plan to integrate with any of the social networks, provide runtime operational support capabilities, and so on. By selecting the desired technologies, the appropriate starter libraries will be added automatically to the dependency list of our pregenerated project template.

Before we proceed with the generation of our project, let's go over exactly what a Spring Boot starter is and the benefits it provides us with.

Spring Boot aims to simplify the process of getting started with an application creation. Spring Boot starters are bootstrap libraries that contain a collection of all the relevant transitive dependencies that are needed to start a particular functionality. Each starter has a special file, which contains the list of all the provided dependencies—spring.provides. Let's take a look at the following link for a spring-boot-starter-test definition as an example:

https://github.com/spring-projects/spring-boot/blob/master/spring-boot-starters/spring-boot-starter-test/src/main/resources/META-INF/spring.provides

Here we will see the following:

provides: spring-test, spring-boot, junit, mockito, hamcrest-library

This tells us that by including spring-boot-starter-test in our build as a dependency, we will automatically get spring-test, spring-boot, junit, mockito, and hamcrest-library. These libraries will provide us with all the necessary things in order to start writing application tests for the software that we will develop, without needing to manually add these dependencies to the build file individually.

With more than 40 starters provided and with the ongoing community additions increasing the list, it is very likely that in case we find ourselves with the need to integrate with a fairly common or popular framework, there is already a starter out there that we can use.

The following table shows you the most notable ones so as to give you an idea of what is available:

The application that we are going to create is a book catalog management system. It will keep a record of books that were published, who were the authors, the reviewers, publishing houses, and so forth. We will name our project BookPub, and apply the following steps:

Clicking on the Generate Project button will download the bookpub.zip archive, which we will extract in our working directory. In the newly created bookpub directory, we will see a build.gradle file that defines our build. It already comes preconfigured with the right version of a Spring Boot plugin and libraries and even includes the extra starters, which we have chosen.

The following is the code of the build.gradle file:

dependencies {
  compile("org.springframework.boot:spring-boot-starter-data-jpa")
  compile("org.springframework.boot:spring-boot-starter-jdbc")
  runtime("com.h2database:h2")
  testCompile("org.springframework.boot:spring-boot-starter-test") 
}

We have selected the following starters:

As you can see, the runtime("com.h2database:h2") dependency is a runtime one. This is because we don't really need, and probably don't even want, to know the exact kind of a database to which we will connect at the compile time. Spring Boot will autoconfigure the needed settings and create appropriate beans once it detects the presence of the org.h2.Driver class in the classpath when the application is launched. We will look into the inner workings of how and where this happens later in this chapter.

The data-jpa and jdbc are Spring Boot starter artifacts. If we look inside these dependency jars once they are downloaded locally by Gradle, or using Maven Central online file repository, we will find that they don't contain any actual classes, only the various metadata. The two containing files that are of particular interest to us are pom.xml and spring.provides. Let's first look at the spring.provides file in the spring-boot-starter-jdbc.jar artifact, with the following content:

provides: spring-jdbc,spring-tx,tomcat-jdbc

This tells us that by having this starter as our dependency, we will transitively get the spring-jdbc, spring-tx, and tomcat-jdbc dependency libraries in our build. The pom.xml file contains the proper dependency declarations that will be used by Gradle or Maven to resolve the needed dependencies during the build time. This also applies to our second starter: spring-boot-starter-data-jpa. This starter will transitively provide us with the spring-orm, hibernate-entity-manager, and spring-data-jpa libraries.

At this point, we have enough libraries/classes in our application classpath so as to give Spring Boot an idea of what kind of application we are trying to run and what are the kind of facilities and frameworks that need to be configured automatically by Spring Boot in order to stitch things together.


Earlier, we mentioned that the presence of the org.h2.Driver class in the classpath will trigger Spring Boot to automatically configure the H2 database connection for our application. To see exactly how this will happen, let's start by looking at our newly created application template, specifically at BookPubApplication.java located in the src/main/java/org/test/bookpub directory in the root of the project, as follows:

package org.test.bookpub;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class BookPubApplication {

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

This is effectively our entire and fully runnable application. There's not a whole lot of code here and definitely no mention about configuration or databases anywhere. The key to making magic is the @SpringBootApplication meta-annotation. In order to understand what actually happens, we can take a look inside the code definition for this annotation, where we will find the real annotations that will direct Spring Boot to set things up automatically:

@Configuration
@EnableAutoConfiguration
@ComponentScan
public @interface SpringBootApplication {…}

Let's go through the following list of annotations:

The SpringApplication.run(BookPubApplication.class, args); line in the main method basically creates a Spring application context that reads the annotations in BookPubApplication.class and instantiates a context, which is similar to how it would have been done if instead of using Spring Boot we would have stuck with the regular Spring Framework.

The output of the preceding command will be as follows:

…
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v1.2.3.BUILD-SNAPSHOT)

2015-03-09 23:18:53.721 : Starting BookPubApplication on mbp with PID 43850 
2015-03-09 23:18:53.781 : Refreshing org.springframework.context.annotation.Annotatio
2015-03-09 23:18:55.544 : Building JPA container EntityManagerFactory for persistence 
2015-03-09 23:18:55.565 : HHH000204: Processing PersistenceUnitInfo [name: default	
2015-03-09 23:18:55.624 : Hibernate Core {4.3.8.Final}
2015-03-09 23:18:55.625 : HHH000206: hibernate.properties not found
2015-03-09 23:18:55.627 : HHH000021: Bytecode provider name : javassist
2015-03-09 23:18:55.774 : HCANN000001: Hibernate Commons Annotations {4.0.5.Final
2015-03-09 23:18:55.850 : HHH000400: Using dialect: org.hibernate.dialect.H2Dialect
2015-03-09 23:18:55.902 : HHH000397: Using ASTQueryTranslatorFactory
2015-03-09 23:18:56.094 : HHH000227: Running hbm2ddl schema export
2015-03-09 23:18:56.096 : HHH000230: Schema export complete
2015-03-09 23:18:56.337 : Registering beans for JMX exposure on startup
2015-03-09 23:18:56.345 : Started BookPubApplication in 3.024 seconds (JVM running...
2015-03-09 23:18:56.346 : Closing org.springframework.context.annotation.AnnotationC..
2015-03-09 23:18:56.347 : Unregistering JMX-exposed beans on shutdown
2015-03-09 23:18:56.349 : Closing JPA EntityManagerFactory for persistence unit 'def…
2015-03-09 23:18:56.349 : HHH000227: Running hbm2ddl schema export
2015-03-09 23:18:56.350 : HHH000230: Schema export complete
BUILD SUCCESSFUL
Total time: 52.323 secs

As we can see, the application started just fine, but as we didn't add any functionality or configure any services, it terminated right away. From the startup log, however, we do see that the autoconfiguration did take place. Let's take a look at the following lines:

Building JPA container EntityManagerFactory for persistence unit 'default'
HHH000412: Hibernate Core {4.3.8.Final}
HHH000400: Using dialect: org.hibernate.dialect.H2Dialect

This information tells us that because we added the jdbc and data-jpa starters, the JPA container was created and will use Hibernate 4.3.8.Final to manage the persistence using H2Dialect. This was possible because we had the right classes in the classpath.

If we run our application again by executing $ ./gradlew clean bootRun, we will get an output that is similar to our previous application startup. However, we will see our Hello message in the logs as well, which will look as follows:

2015-03-10 21:57:51.048  INFO --- org.test.bookpub.StartupRunner         : Hello

Even though the program will get terminated on execution, at least we made it do something!

Command line runners are a useful functionality to execute the various types of code that only have to be run once, right after application startup. Some may also use this as a place to start various executor threads but Spring Boot provides a better solution for this task, which will be discussed at the end of this chapter. The CommandLineRunner interface is used by Spring Boot to scan all of its implementations and invoke each instance's run method with the startup arguments. We can also use an @Order annotation or implement an Ordered interface so as to define the exact order in which we want Spring Boot to execute them. For example, Spring Batch relies on the runners in order to trigger the execution of the jobs.

As command-line runners are instantiated and executed after the application has started, we can use the dependency injection to our advantage in order to wire in whatever dependencies that we need, such as data sources, services, and other components. These can be utilized later while implementing run(String... args) method..

In our previous example, we created the basic application that will execute a command-line runner by printing a message in the logs. Let's enhance this application by adding a connection to a database.

Earlier, we already added the necessary jdbc and data-jpa starters as well as an H2 database dependency to our build file. Now, we will configure an in-memory instance of the H2 database.

To demonstrate the fact that just by including the H2 dependency in the classpath, we will automatically get a default database, let's modify our StartupRunner.java to look as follows:

public class StartupRunner implements CommandLineRunner {
  protected final Log logger = LogFactory.getLog(getClass());
  @Autowired
  private DataSourceds;
  @Override
  public void run(String... args) throws Exception {
    logger.info("DataSource: "+ds.toString());
  }
}

Now, if we proceed with the running of our application, we will see the name of the DataSource printed in the log, as follows:

2015-03-11 21:46:22.067 org.test.bookpub.StartupRunner :DataSource: org.apache.tomcat.jdbc.pool.DataSource@4…{…driverClassName=org.h2.Driver; … }

So, under the hood, Spring Boot recognized that we've autowired a DataSource dependency and automatically created one initializing the in-memory H2 datastore. It is all good and well, but probably not all too useful beyond an early prototyping phase or for the purpose of testing. Who would want a database that goes away with all the data as soon as your application shuts down and you have to start with a clean slate every time you restart the app?

Let's change the defaults in order to create an embedded H2 database that will not store data in-memory, but rather use a file to persist the data in between application restarts.

Even though, by default, Spring Boot makes certain assumptions about the database configuration by examining the classpath for the presence of supported database drivers, it provides you with easy configuration options in order to tweak the database access via a set of exposed properties grouped under spring.datasource.

The things that we can configure are the url, username, password, driver-class-name, and so on. If you want to consume the datasource from a JNDI location, where an actual instance of a DataSource is being created outside the application, for example by a container, like JBoss or Tomcat, and shared via JNDI, you can configure this using the spring.datasource.jndi-name property. The complete set of possible properties is fairly large, so we will not go into all of them. However, we will cover more options in Chapter 5, Application Testing, where we will talk about mocking data for application tests using a database.

If you want to connect to a regular (non-embedded) database, besides just having the appropriate driver library in the classpath, we need to specify the driver of our choice in the configuration. The following snippet is what the configuration to connect to MySQL would resemble:

spring.datasource.driver-class-name: com.mysql.jdbc.Driver
spring.datasource.url: jdbc:mysql://localhost:3306/springbootcookbook
spring.datasource.username: root
spring.datasource.password:

If we wanted Hibernate to create the schema automatically, based on our entity classes, we will need to add the following line to the configuration:

spring.jpa.hibernate.ddl-auto=create-drop

One can go even further in the abstraction layer and instead of auto-wiring a DataSource object, you could go straight for a JdbcTemplate. This would instruct Spring Boot to automatically create a DataSource and then create a JdbcTemplate wrapping the DataSource, thus providing you with a more convenient way of interacting with a database in a safe way. The code for JdbcTemplate is as follows:

@Autowired
private JdbcTemplate jdbcTemplate;

For the extra curious minds, one can look in the spring-boot-autoconfigure source at an org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration class so as to see the code behind the DataSource creation magic.

As you have probably noticed, we didn't write a single line of SQL or even mentioned anything about database connections, building queries, or things like that. The only hint that we are dealing with the database-backed data that we have in our code are the class and field annotations: @Entity, @Repository, @Id, @GeneratedValue, and @ManyToOne along with @ManyToMany and @OneToMany. These annotations, which are a part of the Java Persistance API, along with the extension of the CrudRepository interface are our ways of communicating with Spring about the need to map our objects to the appropriate tables and fields in the database and provide us with the programmatic ability to interact with this data.

Let's go through the following annotations:

We will enhance our application so that it will print a count of books in our repository every 10 seconds. To achieve this, we will make the necessary modifications to the BookPubApplication and StartupRunner classes.

Like some other annotations that we discussed in this chapter and will further discuss in the book, @EnableScheduling is not a Spring Boot annotation, but instead is a Spring Context module annotation. Similar to the @SpringBootApplication and @EnableAutoConfiguration annotations, this is a meta-annotation and internally imports the SchedulingConfiguration via the @Import(SchedulingConfiguration.class) instruction, which can be seen if looked found inside the code for the @EnableScheduling annotation class.

ScheduledAnnotationBeanPostProcessor that will be created by the imported configuration will scan the declared Spring Beans for the presence of the @Scheduled annotations. For every annotated method without arguments, the appropriate executor thread pool will be created. It will manage the scheduled invocation of the annotated method.