Spring Boot has a lot of starters that are already a part of the Spring Boot family. This chapter will provide you with an overview of http://start.spring.io/, available components provided by Spring Boot, and will also show you how to make a project Bootiful, as Josh Long likes to call it.
In this chapter, we will learn about the following topics:
Using a Spring Boot template and starter
Creating a simple application
Launching an application using Gradle
Using the command-line runners
Setting up a database connection
Setting up a data repository service
Scheduling executors
In a fast-paced world of today's software development, the speed of an application creation and the need for rapid prototyping are becoming more and more important. If you are developing a software using a JVM language, Spring Boot is exactly the kind of framework that will give you the power combined with the flexibility that will enable you to produce high-quality software at a rapid pace. So, let's take a look at how Spring Boot can help you to make your application Bootiful.
Spring Boot comes with over 40 different starter modules, which provide ready-to-use integration libraries for many different frameworks, such as database connections that are both relational and NoSQL, web services, social network integration, monitoring libraries, logging, template rendering, and the list just keeps going. While it is not practically feasible to cover every single one of these components, we will go over the important and popular ones in order to get an idea of the realm of possibilities and the ease of application development that Spring Boot provides us with.
We will start with creating a basic simple project skeleton and Spring Boot will help us in this:
Let's head over to http://start.spring.io.
Fill out a simple form with the details about our project.
Clicking on Generate Project will download a premade project skeleton for us to start with.
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:
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:
Now that we have a basic idea of the starters that are available to us, let's go ahead and create our application template at http://start.spring.io.
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:
Use the default proposed Group name:
org.test
.Enter
bookpub
for an Artifact field.Provide
BookPub
as a Name for the application.Specify
org.test.bookpub
as our Package Name.Choose Gradle Project.
Select
Jar
as Packaging.Use Java Version as
1.8
.Use Spring Boot Version as
1.2.5
.Select the H2, JDBC, and JPA starters from the Project Dependencies selection so that we can get the needed artifacts in our build file in order to connect to an H2 database
Click Generate Project to download the project archive.
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:
org.springframework.boot
:spring-boot-starter-data-jpa
pulls in the JPA dependencyorg.springframework.boot
:spring-boot-starter-jdbc
pulls in the JDBC supporting librariescom.h2database
:h2
is a particular type of database implementation, namely H2
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:
@Configuration
tells Spring (and not just Spring Boot, as it is a Spring Framework core annotation) that the annotated class contains Spring configuration definitions such as the@Bean
,@Component
, and@Service
declarations, and others.@ComponentScan
tells Spring that we want to scan our application packages—starting from the package of our annotated class as a default package root—for the other classes that might be annotated with@Configuration
,@Controller
, and other applicable annotations, which Spring will automatically include as part of the context configuration.@EnableAutoConfiguration
is a part of the Spring Boot annotation, which is a meta-annotation on its own (you will find that Spring libraries rely very heavily on the meta-annotations in order to group and compose configurations together). It imports theEnableAutoConfigurationImportSelector
andAutoConfigurationPackages.Registrar
classes that effectively instruct Spring to automatically configure the conditional beans depending on the classes available in the classpath. (We will cover the inner workings of autoconfiguration in detail in Chapter 4, Writing Custom Spring Boot Starters).
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.
Typically, the very first step of creating any application is to have a basic skeleton, which can be immediately launched as is. As the Spring Boot starter has created the application template for us already, all we have to do is extract the code, build, and execute it. Now let's go to the console and launch the app with Gradle.
Change in the directory where the
bookpub.zip
archive was extracted from and execute the following command from the command line:$ ./gradlew clean bootRun
Tip
If you don't have
gradlew
in the directory, then download a version of Gradle from https://gradle.org/downloads or install it via homebrew by executing brew install gradle
. After Gradle is installed, run gradle wrapper
to get the Gradle wrapper files generated. Another way is to invoke gradle clean bootRun
in order to achieve the same results.
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.
Tip
Downloading the example code
You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
With our basic application skeleton ready, let's add some meat to the bones by making our application do something.
Let's start by first creating a class named StartupRunner
. This will implement the CommandLineRunner
interface, which basically provides just one method—public void run(String… args)
—that will get called by Spring Boot only once after the application has started.
Create the file named
StartupRunner.java
under thesrc/main/java/org/test/bookpub/
directory from the root of our project with the following content:package org.test.bookpub; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import org.springframework.boot.CommandLineRunner; public class StartupRunner implements CommandLineRunner { protected final Log logger = LogFactory.getLog(getClass()); @Override public void run(String... args) throws Exception { logger.info("Hello"); } }
After we have defined the class, let's proceed by defining it as
@Bean
in theBookPubApplication.java
application configuration, which is located in the same folder as our newly createdStartupRunner.java
, shown as follows:@Bean public StartupRunner schedulerRunner() { return new StartupRunner(); }
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 every application, there is a need to access some data and conduct some operations on it. Most frequently, this source of data is a data store of some kind, namely a database. Spring Boot makes it very easy to get started in order to connect to the database and start consuming the data via the Java Persistence API among others.
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.
Tip
In the case of an embedded database such as H2, HSQL, or Derby, no actual configuration is required besides including the dependency on one of these in the build file. When one of these databases is detected in the classpath and a DataSource
bean dependency is declared in the code, Spring Boot will automatically create one for you.
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.
Open the file named
application.properties
under thesrc/main/resources
directory from the root of our project and add the following content:spring.datasource.url = jdbc:h2:~/test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE spring.datasource.username = sa spring.datasource.password =
Start the application by executing
./gradlew clean bootRun
from the command line.Check your home directory and you should see the following file in there:
test.mv.db
.
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.
Note
By looking at various blogs and examples, you might notice that some places use dashes in property names such as driver-class-name
while others use camel-cased variants such as driverClassName
. In Spring Boot, these are actually two equally supported ways of naming the same property and they get translated into the same thing internally.
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
Note
Don't do this in the production environment, otherwise on startup, all the table schemas and data will be deleted! Use the update
or validate
values instead, where needed.
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.
Connecting to a database and then executing good old SQL—while simplistic and straightforward—is not the most convenient way to operate on the data, map it in a set of domain objects, and manipulate the relational content. This is why multiple frameworks emerged in order to aid you with mapping the data from tables into objects, better known as Object Relational Mapping. The most notable example of such a framework is Hibernate.
In the previous example, we covered how to set up a connection to a database and configure the settings for the username, password, which driver to use, and so on. In this recipe, we will enhance our application by adding a few entity objects that define the structure of the data in the database and a CrudRepository
interface to access the data.
As our application is a book tracking catalogue, the obvious domain objects would be the Book
, Author
, Reviewers
, and Publisher
.
Create a new package folder named
entity
under thesrc/main/java/org/test/bookpub
directory from the root of our project.In this newly created package, create a new class named
Book
with the following content:@Entity public class Book { @Id @GeneratedValue private Long id; private String isbn; private String title; private String description; @ManyToOne private Author author; @ManyToOne private Publisher publisher; @ManyToMany private List<Reviewers> reviewers; protected Book() {} public Book(String isbn, String title, Author author, Publisher publisher) { this.isbn= isbn; this.title = title; this.author= author; this.publisher= publisher; } //Skipping getters and setters to save space, but we do need them }
As any book should have an author and a publisher, and ideally some reviewers, we need to create these entity objects as well. Let's start by creating an
Author
entity class under the same directory as ourBook
on, as follows:@Entity public class Author { @Id @GeneratedValue private Long id; private String firstName; private String lastName; @OneToMany(mappedBy = "author") private List<Book> books; protected Author() {} public Author(String firstName, String lastName) {...} //Skipping implementation to save space, but we do need it all }
Similarly, we will create the
Publisher
andReviewer
classes, as shown in the following code:@Entity public class Publisher { @Id @GeneratedValue private Long id; private String name; @OneToMany(mappedBy = "publisher") private List<Book> books; protected Publisher() {} public Publisher(String name) {...} } @Entity public class Reviewer { @Id @GeneratedValue private Long id; private String firstName; private String lastName; protected Reviewer() {} public Reviewer(String firstName, String lastName) { //Skipping implementation to save space } }
Now, we will create our
BookRepository
interface by extending Spring'sCrudRepository
under thesrc/main/java/org/test/bookpub/repository
package, as follows:@Repository public interface BookRepository extends CrudRepository<Book, Long> { public Book findBookByIsbn(String isbn); }
Finally, let's modify our
StartupRunner
in order to print the number of books in our collection instead of some random DataSource string by auto-wiring a newly createdBookRepository
and printing the result of a.count()
call to the log, as follows:public class StartupRunner implements CommandLineRunner { @Autowired private BookRepository bookRepository; public void run(String... args) throws Exception { logger.info("Number of books: " + bookRepository.count()); } }
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:
@Entity
indicates that the annotated class should be mapped to a database table. The name of the table will be derived from the name of the class but it can be configured, if needed. It is important to note that every entity class should have a defaultprotected
constructor, which is needed for automated instantiation and Hibernate interactions.@Repository
indicates that the interface is intended to provide you with the access and manipulation of data for a database. It also serves as an indication to Spring during the component scan that this instance should be created as a bean that will be available for use and injection into other beans in the application.The
CrudRepository
interface defines the basic common methods to read, create, update, and delete data from a data repository. The extra methods that we will define in ourBookRepository
extension,public Book findBookByIsbn(String isbn)
, indicate that Spring JPA should automatically translate the call to this method to a SQL finder query selecting a Book by its ISBN field. This is a convention-named mapping that translates the method name into a SQL query. It can be a very powerful ally, allowing you to build queries such asfindByNameIgnoringCase(String name)
and others.The
@Id
and@GeneratedValue
annotations provide you with an indication that an annotated field should be mapped to a primary key column in the database and the value for this field should be generated, instead of being explicitly entered.The
@ManyToOne
and@ManyToMany
annotations define the relational field associations that refer to the data stored in the other tables. In our case, multipleBooks
belong to oneAuthor
and manyReviewers
review multipleBooks
. ThemappedBy
attribute in@OneToMany
annotation declaration defines a reverse association mapping. It indicates to Hibernate that the mapping source of truth is defined in theBook
class, in theauthor
orpublisher
fields. TheBooks
references from withinAuthor
andPublisher
classes are merely reverse associations.Tip
For more information about all the vast capabilities of Spring Data, visit http://docs.spring.io/spring-data/data-commons/docs/current/reference/html/.
Earlier in this chapter, we discussed how the command-line runners can be used as a place to start the scheduled executor thread pools in order to run the worker threads in intervals. While that is certainly a possibility, Spring provides you with a more concise configuration to achieve the same goal: @EnableScheduling
.
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.
Let's add an
@EnableScheduling
annotation to theBookPubApplication
class, as follows:@SpringBootApplication @EnableScheduling public class BookPubApplication {…}
As an
@Scheduled
annotation can be placed only on methods without arguments, let's add a newrun()
method to theStartupRunner
class and annotate it with the@Scheduled
annotation, as shown in the following line:@Scheduled(initialDelay = 1000, fixedRate = 10000) public void run() { logger.info("Number of books: " + bookRepository.count()); }
Start the application by executing
./gradlew clean bootRun
from the command line so as to observe theNumber of books: 0
message that shows in the logs every 10 seconds.
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.