spring-boot/spring-boot-starters/README.md

Spring Boot - Starters

Starters are a set of convenient dependency descriptors that you can include in your application. You get a one-stop-shop for all the Spring and related technology that you need without having to hunt through sample code and copy paste loads of dependency descriptors. For example, if you want to get started using Spring and JPA for database access just include the spring-boot-starter-data-jpa dependency in your project, and you are good to go. The starters contain a lot of the dependencies that you need to get a project up and running quickly and with a consistent, supported set of managed transitive dependencies.

Building a Spring Boot Project with Maven

The quickest way to get started with a new project is to use the spring-boot-starter-parent, e.g.

	<!-- Inherit defaults from Spring Boot -->
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>1.0.0.RC3</version>
	</parent>

The parent pom adds two main fetaures to your project:

• dependency management configuration, so you don't have to specify versions or excludes with your own dependencies, as long as they are part of the Spring Boot stack

• plugin configuration, so you don't have to configure some common settings in the main Maven plugins used to get a project off the ground (e.g. the Spring Boot Maven plugin)

As an example, if you want to build a simple RESTful web service with embedded Tomcat, you only need one dependency:

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
	</dependencies>

And if you want to use the Spring Boot plugin to package the project as an executable JAR (or run it from source code), you only need to add the plugin (not configure it, unless you want to change the settings in the parent):

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

If you need to access milestone or snapshot builds from Spring projects, you can optionallyt add repositories, as follows:

	<repositories>
		<repository>
			<id>spring-snapshots</id>
			<url>http://repo.spring.io/snapshot</url>
			<snapshots><enabled>true</enabled></snapshots>
		</repository>
		<repository>
			<id>spring-milestones</id>
			<url>http://repo.spring.io/milestone</url>
			<snapshots><enabled>true</enabled></snapshots>
		</repository>
	</repositories>
	<pluginRepositories>
		<pluginRepository>
			<id>spring-snapshots</id>
			<url>http://repo.spring.io/snapshot</url>
		</pluginRepository>
		<pluginRepository>
			<id>spring-milestones</id>
			<url>http://repo.spring.io/milestone</url>
		</pluginRepository>
	</pluginRepositories>

The repositories cannot all be defined in the parent (at least one will be required to resolve the parent itself).

Using Your Own Parent POM

If you don't want to use the Spring Boot starter parent, you can use your own and still keep the benefit of the dependency management (but not the plugin management) using "scope=import". Example:

<dependencyManagement>
  <dependencies>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>1.0.0.RC3</version>
        <scope>import</scope>
	</dependency>
  </dependencies>
</dependencyManagement>

(It actually doesn't matter if you use "spring-boot-starter-parent" or "spring-boot-dependencies".)

Samples

All the Spring Boot Samples come with a pom.xml, but they use a different parent to spring-boot-starter-parent (although that pom is one of their ancestors). Other useful places to get clean projects with a pom.xml that works as quickly as possible:

• The Getting Started Guides on spring.io are all available in github, or you can copy paste from the guides themselves (all the code is on the web page).

• The same guides are available as working projects in Spring Tool Suite(STS) (an Eclipse plugin feature set), and so is a starter project template generator (via File->New->Spring Starter Project).

• The Spring Starter Project feature in STS is backed by a web application at start.spring.io, which you can also use yourself to download ZIP files of the starter projects.

Building With Gradle

If you prefer to build your project with Gradle then similar features are available to you as to Maven users. The starter projects work in exactly the same way, for instance, so a typical project might have a build.gradle like this:

buildscript {

    ext {
		springBootVersion = '1.0.0.RC3'
	}

    repositories {
	    mavenCentral()
		maven { url "http://repo.springsource.org/libs-milestone" }
	}
	dependencies {
		classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
	}
}


apply plugin: 'java'
apply plugin: 'spring-boot'

jar {
	baseName = 'spring-boot-sample-simple'
	version =  '0.5.0'
}

repositories {
	mavenCentral()
	maven { url "http://repo.springsource.org/libs-milestone" }
}

dependencies {
	compile("org.springframework.boot:spring-boot-starter-web")
	testCompile("org.springframework.boot:spring-boot-starter-test")
}

task wrapper(type: Wrapper) { gradleVersion = '1.6' }

This build is for a simple RESTful web service (with embedded Tomcat). Notice that the dependencies do not have explicit version numbers. This works for Spring Boot dependencies, but also anything else that is explicitly managed by the Spring Boot Starter parent.

Versionless dependency resolution is a feature of the Spring Boot Gradle Plugin, which also gives you a "run from source" feature ("gradle bootRun") and an enhanced JAR/WAR packaging feature for executable archives ("gradle build").

Samples

Most of the samples mentioned above for Maven users are also buildable using Gradle. Only some of the Spring Boot Samples come with a build.gradle. The Spring Starter Project feature in STS produces a Maven project. But web application at start.spring.io can generate Gradle build files for the same projects (just download it with a browser or command line).