Skip to content

S
spring-boot
Commit d580ce53 authored by Phillip Webb's avatar Phillip Webb
Browse files
Options

Merge reference documentation branch 

Fixed gh-295
parents 22e397cd a1a62785
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 10712 additions and 5 deletions
spring-boot-docs/pom.xml
View file @ d580ce53
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
......@@ -41,7 +42,6 @@
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<executions>
<execution>
......@@ -65,9 +65,183 @@
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>0.1.4</version>
<executions>
<execution>
<id>generate-docbook</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDocumentName>index.adoc</sourceDocumentName>
<backend>docbook5</backend>
<doctype>book</doctype>
<attributes>
<docinfo>true</docinfo>
<spring-boot-version>${project.version}</spring-boot-version>
<spring-boot-docs-version>${project.version}</spring-boot-docs-version>
<spring-boot-repo>${spring-boot-repo}</spring-boot-repo>
<github-tag>${github-tag}</github-tag>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>2.0.15</version>
<configuration>
<sourceDirectory>${basedir}/target/generated-docs</sourceDirectory>
<includes>index.xml</includes>
<xincludeSupported>true</xincludeSupported>
<chunkedOutput>false</chunkedOutput>
<foCustomization>${basedir}/src/main/docbook/xsl/pdf.xsl</foCustomization>
<useExtensions>1</useExtensions>
<highlightSource>1</highlightSource>
<highlightXslthlConfig>${basedir}/src/main/docbook/xsl/xslthl-config.xml</highlightXslthlConfig>
</configuration>
<dependencies>
<dependency>
<groupId>net.sf.xslthl</groupId>
<artifactId>xslthl</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>net.sf.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>5.0-all</version>
<classifier>resources</classifier>
<type>zip</type>
<scope>runtime</scope>
</dependency>
</dependencies>
<executions>
<execution>
<id>html-single</id>
<goals>
<goal>generate-html</goal>
</goals>
<phase>generate-resources</phase>
<configuration>
<htmlCustomization>${basedir}/src/main/docbook/xsl/html-singlepage.xsl</htmlCustomization>
<targetDirectory>${basedir}/target/docbook/htmlsingle</targetDirectory>
<postProcess>
<copy todir="${basedir}/target/contents/reference/htmlsingle">
<fileset dir="${basedir}/target/docbook/htmlsingle">
<include name="**/*.html" />
</fileset>
</copy>
<copy todir="${basedir}/target/contents/reference/htmlsingle">
<fileset dir="${basedir}/src/main/docbook">
<include name="**/*.css" />
<include name="**/*.png" />
<include name="**/*.gif" />
<include name="**/*.jpg" />
</fileset>
</copy>
</postProcess>
</configuration>
</execution>
<execution>
<id>html</id>
<goals>
<goal>generate-html</goal>
</goals>
<phase>generate-resources</phase>
<configuration>
<htmlCustomization>${basedir}/src/main/docbook/xsl/html-multipage.xsl</htmlCustomization>
<targetDirectory>${basedir}/target/docbook/html</targetDirectory>
<chunkedOutput>true</chunkedOutput>
<postProcess>
<copy todir="${basedir}/target/contents/reference/html">
<fileset dir="${basedir}/target/docbook/html">
<include name="**/*.html" />
</fileset>
</copy>
<copy todir="${basedir}/target/contents/reference/html">
<fileset dir="${basedir}/src/main/docbook">
<include name="**/*.css" />
<include name="**/*.png" />
<include name="**/*.gif" />
<include name="**/*.jpg" />
</fileset>
</copy>
</postProcess>
</configuration>
</execution>
<execution>
<id>pdf</id>
<goals>
<goal>generate-pdf</goal>
</goals>
<phase>generate-resources</phase>
<configuration>
<foCustomization>${basedir}/src/main/docbook/xsl/pdf.xsl</foCustomization>
<targetDirectory>${basedir}/target/docbook/pdf</targetDirectory>
<postProcess>
<copy todir="${basedir}/target/contents/reference">
<fileset dir="${basedir}/target/docbook">
<include name="**/*.pdf" />
</fileset>
</copy>
<move file="${basedir}/target/contents/reference/pdf/index.pdf"
tofile="${basedir}/target/contents/reference/pdf/spring-boot-reference.pdf" />
</postProcess>
</configuration>
</execution>
<execution>
<id>epub</id>
<goals>
<goal>generate-epub3</goal>
</goals>
<phase>generate-resources</phase>
<configuration>
<epubCustomization>${basedir}/src/main/docbook/xsl/epub.xsl</epubCustomization>
<targetDirectory>${basedir}/target/docbook/epub</targetDirectory>
<postProcess>
<copy todir="${basedir}/target/contents/reference/epub">
<fileset dir="${basedir}/target/docbook">
<include name="**/*.epub" />
</fileset>
</copy>
<move file="${basedir}/target/contents/reference/epub/index.epub"
tofile="${basedir}/target/contents/reference/epub/spring-boot-reference.epub" />
</postProcess>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
<dependencies>
<dependency>
<groupId>ant-contrib</groupId>
<artifactId>ant-contrib</artifactId>
<version>1.0b3</version>
<exclusions>
<exclusion>
<groupId>ant</groupId>
<artifactId>ant</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.apache.ant</groupId>
<artifactId>ant-nodeps</artifactId>
<version>1.8.1</version>
</dependency>
<dependency>
<groupId>org.tigris.antelope</groupId>
<artifactId>antelopetasks</artifactId>
<version>3.2.10</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>package-and-attach-docs-zip</id>
......@@ -77,10 +251,42 @@
</goals>
<configuration>
<target>
<zip destfile="${project.build.directory}/${project.name}-${project.version}.zip">
<zipfileset src="${project.build.directory}/${project.name}-${project.version}-javadoc.jar" prefix="api" />
<zip
destfile="${project.build.directory}/${project.name}-${project.version}.zip">
<zipfileset
src="${project.build.directory}/${project.name}-${project.version}-javadoc.jar"
prefix="api" />
<fileset dir="${project.build.directory}/contents" />
</zip>
</target>
</configuration>
</execution>
<execution>
<id>setup-maven-properties</id>
<phase>validate</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<exportAntProperties>true</exportAntProperties>
<target>
<taskdef resource="net/sf/antcontrib/antcontrib.properties" />
<taskdef name="stringutil" classname="ise.antelope.tasks.StringUtilTask" />
<var name="version-type" value="${project.version}" />
<propertyregex property="version-type" override="true"
input="${version-type}" regexp=".*\.(.*)" replace="\1" />
<propertyregex property="version-type" override="true"
input="${version-type}" regexp="(M)\d+" replace="MILESTONE" />
<propertyregex property="version-type" override="true"
input="${version-type}" regexp="(RC)\d+" replace="MILESTONE" />
<propertyregex property="version-type" override="true"
input="${version-type}" regexp="BUILD-(.*)" replace="SNAPSHOT" />
<stringutil string="${version-type}" property="spring-boot-repo">
<lowercase />
</stringutil>
<var name="github-tag" value="v1.0.0.RELEASE" />
<propertyregex property="github-tag" override="true"
input="${github-tag}" regexp=".*SNAPSHOT" replace="master" />
</target>
</configuration>
</execution>
......
spring-boot-docs/src/main/asciidoc/Guardfile 0 → 100644
View file @ d580ce53
require 'asciidoctor'
require 'erb'
guard 'shell' do
watch(/.*\.adoc$/) {|m|
Asciidoctor.render_file('index.adoc', \
:in_place => true, \
:safe => Asciidoctor::SafeMode::UNSAFE, \
:attributes=> { \
'source-highlighter' => 'prettify', \
'icons' => 'font', \
'linkcss'=> 'true', \
'copycss' => 'true', \
'doctype' => 'book'})
}
end
guard 'livereload' do
watch(%r{^.+\.(css|js|html)$})
end
spring-boot-docs/src/main/asciidoc/appendix-application-properties.adoc 0 → 100644
View file @ d580ce53
:numbered!:
[appendix]
[[common-application-properties]]
== Common application properties
Various properties can be specified inside your `application.properties`/`application.yml`
file or as command line switches. This section provides a list common Spring Boot
properties and references to the underlying classes that consume them.
NOTE: Property contributions can come from additional jar files on your classpath so
you should not consider this an exhaustive list. It is also perfectly legal to define
your own properties.
WARNING: This sample file is meant as a guide only. Do **not** copy/paste the entire
content into your application; rather pick only the properties that you need.
[source,properties,indent=0,subs="verbatim,attributes"]
----
# ===================================================================
# COMMON SPRING BOOT PROPERTIES
#
# This sample file is provided as a guideline. Do NOT copy it in its
# entirety to your own application. ^^^
# ===================================================================
# ----------------------------------------
# CORE PROPERTIES
# ----------------------------------------
# SPRING CONFIG (ConfigFileApplicationListner)
spring.config.name= # config file name (default to 'application')
spring.config.location= # location of config file
# PROFILES
spring.profiles= # comma list of active profiles
# APPLICATION SETTINGS (SpringApplication_
spring.main.sources=
spring.main.web-environment= # detect by default
spring.main.show-bannder=true
spring.main.... # see class for all properties
# LOGGING
logging.path=/var/logs
logging.file=myapp.log
logging.config=
# IDENTITY (ContextIdApplicationContextInitializer)
spring.application.name=
vcap.application.name=
# EMBEDDED SERVER CONFIGURATION (ServerProperties)
server.port=8080
server.address= # bind to a specific NIC
server.session-timeout= # session timeout in sections
server.context-path= # the context path, defaults to '/'
server.servlet-path= # the servlet path, defaults to '/'
server.tomcat.access-log-pattern= # log pattern of the access log
server.tomcat.access-log-enabled=false # is access logging enabled
server.tomcat.protocol-header="x-forwarded-proto" # ssl forward headers
server.tomcat.remote-ip-header="x-forwarded-for"
server.tomcat.basedir="/tmp" # base dir (usually not needed, defaults to tmp)
server.tomcat.background-processor-delay=30; # in seconds
server.tomcat.max-threads = 0 # number of threads in protocol handler
# SPRING MVC (HttpMapperProperties)
http.mappers.json-pretty-print=false # pretty print JSON
spring.view.prefix= # MVC view prefix
spring.view.suffix= # ... and suffix
spring.resources.cache-period # cache timeouts in headers sent to browser
# THYMELEAF (ThymeleafAutoConfiguration)
spring.thymeleaf.prefix="classpath:/templates/"
spring.thymeleaf.suffix=".html"
spring.thymeleaf.mode="HTML5"
spring.thymeleaf.encoding="UTF-8"
spring.thymeleaf.cache=true # set to false for hot refresh
# INTERNATIONALIZATION (MessageSourceAutoConfiguration)
spring.messages.basename="messages"
spring.messages.encoding="UTF-8"
# SECURITY (SecurityProperties)
security.user.name="user" # login username
security.user.password= # login password
security.user.role="USER" # role assigned to the user
security.require-ssl=false # advanced settings ...
security.enable-csrf=false
security.basic.enabled=true
security.basic.realm="Spring"
security.basic.path="/**"
security.headers.xss=false
security.headers.cache=false
security.headers.frame=false
security.headers.contentType=false
security.headers.hsts=all # none / domain / all
security.sessions=stateless # always / never / if_required / stateless
security.ignored=false
# DATASOURCE (DataSourceAutoConfiguration & AbstractDataSourceConfiguration)
spring.datasource.name= # name of the data source
spring.datasource.intialize=true # populate using data.sql
spring.datasource.schema= # a schema resource reference
spring.datasource.continueOnError=false # continue even if can't be initialized
spring.datasource.driverClassName= # JDBC Settings...
spring.datasource.url=
spring.datasource.username=
spring.datasource.password=
spring.datasource.max-active=100 # Advanced configuration...
spring.datasource.max-idle=8
spring.datasource.min-idle=8
spring.datasource.initial-size=10
spring.datasource.validation-query
spring.datasource.test-on-borrow=false
spring.datasource.test-on-return=false
# MONGODB (MongoProperties)
spring.data.mongodb.host= # the db host
spring.data.mongodb.port=27017 # the connection port (defaults to 27107)
spring.data.mongodb.uri=mongodb://localhost/test # connection URL
# JPA (JpaBaseConfiguration, HibernateJpaAutoConfiguration)
spring.jpa.properties.*= # properties to set on the JPA connection
spring.jpa.openInView=true
spring.jpa.show-sql=true
spring.jpa.database-platform=
spring.jpa.database=
spring.jpa.generate-ddl=
spring.jpa.hibernate.naming-strategy= # naming classname
spring.jpa.hibernate.ddl-auto= # defaults to create-drop for embedded dbs
# JMX
spring.jmx.enabled=true # Expose MBeans from Spring
# RABBIT (RabbitProperties)
spring.rabbitmq.host= # connection host
spring.rabbitmq.port= # connection port
spring.rabbitmq.username= # login user
spring.rabbitmq.password= # login password
spring.rabbitmq.virtualhost=
spring.rabbitmq.dynamic=
# REDIS (RedisProperties)
spring.redis.host="localhost" # server host
spring.redis.password= # server password
spring.redis.port=6379 # connection port
spring.redis.pool.max-idle=8 # pool settings ...
spring.redis.pool.min-idle=0
spring.redis.pool.max-active=8
spring.redis.pool.max-wait=-1
# ACTIVEMQ (ActiveMQProperties)
spring.activemq.broker-url="tcp://localhost:61616" # connection URL
spring.activemq.in-memory=true
spring.activemq.pooled=false
# JMS (JmsTemplateProperties)
spring.jms.pub-sub-domain=
# SPRING BATCH (BatchDatabaseInitializer)
spring.batch.job.names="job1,job2"
spring.batch.job.enabled=true
spring.batch.initializer.enabled=true
spring.batch.schema= # batch schema to load
# AOP
spring.aop.auto=
spring.aop.proxyTargetClass=
# FILE ENCODING (FileEncodingApplicationListener)
spring.mandatory-file-encoding=false
# ----------------------------------------
# ACTUATOR PROPERTIES
# ----------------------------------------
# MANAGEMENT HTTP SERVER (ManagementServerProperties)
management.port= # defaults to 'server.port'
management.address= # bind to a specific NIC
management.contextPath= # default to '/'
# ENDPOINTS (AbstractEndpoint subclasses)
endpoints.autoconfig.id="autoconfig"
endpoints.autoconfig.sensitive=true
endpoints.autoconfig.enabled=true
endpoints.beans.id="beans"
endpoints.beans.sensitive=true
endpoints.beans.enabled=true
endpoints.configprops.id="configprops"
endpoints.configprops.sensitive=true
endpoints.configprops.enabled=true
endpoints.configprops.keys-to-sanitize="password,secret"
endpoints.dump.id="dump"
endpoints.dump.sensitive=true
endpoints.dump.enabled=true
endpoints.env.id="env"
endpoints.env.sensitive=true
endpoints.env.enabled=true
endpoints.health.id="health"
endpoints.health.sensitive=false
endpoints.health.enabled=true
endpoints.info.id="info"
endpoints.info.sensitive=false
endpoints.info.enabled=true
endpoints.metrics.id="metrics"
endpoints.metrics.sensitive=true
endpoints.metrics.enabled=true
endpoints.shutdown.id="shutdown"
endpoints.shutdown.sensitive=true
endpoints.shutdown.enabled=false
endpoints.trace.id="trace"
endpoints.trace.sensitive=true
endpoints.trace.enabled=true
# MVC ONLY ENDPOINTS
endpoints.jolokia.path="jolokia"
endpoints.jolokia.sensitive=true
endpoints.jolokia.enabled=true # when using Jolokia
endpoints.error.path="/error"
# JMX ENDPOINT (EndpointMBeanExportProperties)
endpoints.jmx.enabled=true
endpoints.jmx.domain= # the JMX domain, defaults to 'org.springboot'
endpoints.jmx.unique-names=false
endpoints.jmx.enabled=true
endpoints.jmx.staticNames=
# JOLOKIA (JolokiaProperties)
jolokia.config.*= # See Jolokia manual
# REMOTE SHELL
shell.auth=simple # jaas, key, simple, spring
shell.command-refresh-interval=-1
shell.command-path-pattern="classpath*:/commands/**, classpath*:/crash/commands/**"
shell.config-path-patterns="classpath*:/crash/*"
shell.disabled-plugins=false # don't expose plugins
shell.ssh.enabled= # ssh settings ...
shell.ssh.keyPath=
shell.ssh.port=
shell.telnet.enabled= # telnet settings ...
shell.telnet.port=
shell.auth.jaas.domain= # authentication settings ...
shell.auth.key.path=
shell.auth.simple.user.name=
shell.auth.simple.user.password=
shell.auth.spring.roles=
# GIT INFO
spring.git.properties= # resource ref to generated git info properties file
----
spring-boot-docs/src/main/asciidoc/appendix-auto-configuration-classes.adoc 0 → 100644
View file @ d580ce53
[appendix]
[[auto-configuration-classes]]
== Auto-configuration classes
Here is a list of all auto configuration classes provided by Spring Boot with links to
documentation and source code. Remember to also look at the autoconfig report in your
application for more details of which features are switched on.
(start the app with `--debug` or `-Ddebug`, or in an Actuator application use the
`autoconfig` endpoint).
[[auto-configuration-classes-from-autoconfigure-module]]
=== From the ``spring-boot-autoconfigure'' module
The following auto-configuration classes are from the `spring-boot-autoconfigure` module:
[cols="4,1"]
|===
|Configuration Class | Links
|{sc-spring-boot-autoconfigure}/MessageSourceAutoConfiguration.{sc-ext}[MessageSourceAutoConfiguration]
|{dc-spring-boot-autoconfigure}/MessageSourceAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/PropertyPlaceholderAutoConfiguration.{sc-ext}[PropertyPlaceholderAutoConfiguration]
|{dc-spring-boot-autoconfigure}/PropertyPlaceholderAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/amqp/RabbitAutoConfiguration.{sc-ext}[RabbitAutoConfiguration]
|{dc-spring-boot-autoconfigure}/amqp/RabbitAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/aop/AopAutoConfiguration.{sc-ext}[AopAutoConfiguration]
|{dc-spring-boot-autoconfigure}/aop/AopAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/batch/BatchAutoConfiguration.{sc-ext}[BatchAutoConfiguration]
|{dc-spring-boot-autoconfigure}/batch/BatchAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/data/JpaRepositoriesAutoConfiguration.{sc-ext}[JpaRepositoriesAutoConfiguration]
|{dc-spring-boot-autoconfigure}/data/JpaRepositoriesAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/data/MongoRepositoriesAutoConfiguration.{sc-ext}[MongoRepositoriesAutoConfiguration]
|{dc-spring-boot-autoconfigure}/data/MongoRepositoriesAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/data/MongoTemplateAutoConfiguration.{sc-ext}[MongoTemplateAutoConfiguration]
|{dc-spring-boot-autoconfigure}/data/MongoTemplateAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/jdbc/DataSourceAutoConfiguration.{sc-ext}[DataSourceAutoConfiguration]
|{dc-spring-boot-autoconfigure}/jdbc/DataSourceAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/jdbc/DataSourceTransactionManagerAutoConfiguration.{sc-ext}[DataSourceTransactionManagerAutoConfiguration]
|{dc-spring-boot-autoconfigure}/jdbc/DataSourceTransactionManagerAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/jms/JmsTemplateAutoConfiguration.{sc-ext}[JmsTemplateAutoConfiguration]
|{dc-spring-boot-autoconfigure}/jms/JmsTemplateAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/jmx/JmxAutoConfiguration.{sc-ext}[JmxAutoConfiguration]
|{dc-spring-boot-autoconfigure}/jmx/JmxAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/mobile/DeviceResolverAutoConfiguration.{sc-ext}[DeviceResolverAutoConfiguration]
|{dc-spring-boot-autoconfigure}/mobile/DeviceResolverAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/mongo/MongoAutoConfiguration.{sc-ext}[MongoAutoConfiguration]
|{dc-spring-boot-autoconfigure}/mongo/MongoAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/orm/jpa/HibernateJpaAutoConfiguration.{sc-ext}[HibernateJpaAutoConfiguration]
|{dc-spring-boot-autoconfigure}/orm/jpa/HibernateJpaAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/reactor/ReactorAutoConfiguration.{sc-ext}[ReactorAutoConfiguration]
|{dc-spring-boot-autoconfigure}/reactor/ReactorAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/redis/RedisAutoConfiguration.{sc-ext}[RedisAutoConfiguration]
|{dc-spring-boot-autoconfigure}/redis/RedisAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/security/SecurityAutoConfiguration.{sc-ext}[SecurityAutoConfiguration]
|{dc-spring-boot-autoconfigure}/security/SecurityAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/thymeleaf/ThymeleafAutoConfiguration.{sc-ext}[ThymeleafAutoConfiguration]
|{dc-spring-boot-autoconfigure}/thymeleaf/ThymeleafAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/web/DispatcherServletAutoConfiguration.{sc-ext}[DispatcherServletAutoConfiguration]
|{dc-spring-boot-autoconfigure}/web/DispatcherServletAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/web/EmbeddedServletContainerAutoConfiguration.{sc-ext}[EmbeddedServletContainerAutoConfiguration]
|{dc-spring-boot-autoconfigure}/web/EmbeddedServletContainerAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/web/HttpMessageConvertersAutoConfiguration.{sc-ext}[HttpMessageConvertersAutoConfiguration]
|{dc-spring-boot-autoconfigure}/web/HttpMessageConvertersAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/web/MultipartAutoConfiguration.{sc-ext}[MultipartAutoConfiguration]
|{dc-spring-boot-autoconfigure}/web/MultipartAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/web/ServerPropertiesAutoConfiguration.{sc-ext}[ServerPropertiesAutoConfiguration]
|{dc-spring-boot-autoconfigure}/web/ServerPropertiesAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/web/WebMvcAutoConfiguration.{sc-ext}[WebMvcAutoConfiguration]
|{dc-spring-boot-autoconfigure}/web/WebMvcAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/websocket/WebSocketAutoConfiguration.{sc-ext}[WebSocketAutoConfiguration]
|{dc-spring-boot-autoconfigure}/websocket/WebSocketAutoConfiguration.{dc-ext}[javadoc]
|===
[[auto-configuration-classes-from-actuator]]
=== From the ``spring-boot-actuator'' module
The following auto-configuration classes are from the `spring-boot-actuator` module:
[cols="4,1"]
|===
|Configuration Class |Links
|{sc-spring-boot-actuator}/autoconfigure/AuditAutoConfiguration.{sc-ext}[AuditAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/AuditAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/CrshAutoConfiguration.{sc-ext}[CrshAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/CrshAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/EndpointAutoConfiguration.{sc-ext}[EndpointAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/EndpointAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/EndpointMBeanExportAutoConfiguration.{sc-ext}[EndpointMBeanExportAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/EndpointMBeanExportAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/EndpointWebMvcAutoConfiguration.{sc-ext}[EndpointWebMvcAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/EndpointWebMvcAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/ErrorMvcAutoConfiguration.{sc-ext}[ErrorMvcAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/ErrorMvcAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/JolokiaAutoConfiguration.{sc-ext}[JolokiaAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/JolokiaAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/ManagementSecurityAutoConfiguration.{sc-ext}[ManagementSecurityAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/ManagementSecurityAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/ManagementServerPropertiesAutoConfiguration.{sc-ext}[ManagementServerPropertiesAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/ManagementServerPropertiesAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/MetricFilterAutoConfiguration.{sc-ext}[MetricFilterAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/MetricFilterAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/MetricRepositoryAutoConfiguration.{sc-ext}[MetricRepositoryAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/MetricRepositoryAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/TraceRepositoryAutoConfiguration.{sc-ext}[TraceRepositoryAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/TraceRepositoryAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/TraceWebFilterAutoConfiguration.{sc-ext}[TraceWebFilterAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/TraceWebFilterAutoConfiguration.{dc-ext}[javadoc]
|===
spring-boot-docs/src/main/asciidoc/appendix-executable-jar-format.adoc 0 → 100644
View file @ d580ce53
[appendix]
[[executable-jar]]
== The executable jar format
The `spring-boot-loader` modules allows Spring Boot to support executable jar and
war files. If you're using the Maven or Gradle plugin, executable jars are
automatically generated and you generally won't need to know the details of how
they work.
If you need to create executable jars from a different build system, or if you are just
curious about the underlying technology, this section provides some background.
[[executable-jar-nested-jars]]
=== Nested JARs
Java does not provide any standard way to load nested jar files (i.e. jar files that
are themselves contained within a jar). This can be problematic if you are looking
to distribute a self contained application that you can just run from the command line
without unpacking.
To solve this problem, many developers use ``shaded'' jars. A shaded jar simply packages
all classes, from all jars, into a single 'uber jar'. The problem with shaded jars is
that it becomes hard to see which libraries you are actually using in your application.
It can also be problematic if the the same filename is used (but with different content)
in multiple jars. Spring Boot takes a different approach and allows you to actually nest
jars directly.
[[executable-jar-jar-file-structure]]
==== The executable jar file structure
Spring Boot Loader compatible jar files should be structured in the following way:
[indent=0]
----
example.jar
|
+-META-INF
| +-MANIFEST.MF
+-org
| +-springframework
| +-boot
| +-loader
| +-<spring boot loader classes>
+-com
| +-mycompany
| + project
| +-YouClasses.class
+-lib
+-dependency1.jar
+-dependency2.jar
----
Dependencies should be placed in a nested `lib` directory.
[[executable-jar-war-file-structure]]
==== The executable war file structure
Spring Boot Loader compatible war files should be structured in the following way:
[indent=0]
----
example.jar
|
+-META-INF
| +-MANIFEST.MF
+-org
| +-springframework
| +-boot
| +-loader
| +-<spring boot loader classes>
+-WEB-INF
+-classes
| +-com
| +-mycompany
| +-project
| +-YouClasses.class
+-lib
| +-dependency1.jar
| +-dependency2.jar
+-lib-provided
+-servlet-api.jar
+-dependency3.jar
----
Dependencies should be placed in a nested `WEB-INF/lib` directory. Any dependencies
that are required when running embedded but are not required when deploying to
a traditional web container should be placed in `WEB-INF/lib-provided`.
[[executable-jar-jarfile]]
=== Spring Boot's ``JarFile'' class
The core class used to support loading nested jars is
`org.springframework.boot.loader.jar.JarFile`. It allows you load jar
content from a standard jar file, or from nested child jar data. When first loaded, the
location of each `JarEntry` is mapped to a physical file offset of the outer jar:
[indent=0]
----
myapp.jar
+---------+---------------------+
| | /lib/mylib.jar |
| A.class |+---------+---------+|
| || B.class | B.class ||
| |+---------+---------+|
+---------+---------------------+
^ ^ ^
0063 3452 3980
----
The example above shows how `A.class` can be found in `myapp.jar` position `0063`.
`B.class` from the nested jar can actually be found in `myapp.jar` position `3452`
and `B.class` is at position `3980`.
Armed with this information, we can load specific nested entries by simply seeking to
appropriate part if the outer jar. We don't need to unpack the archive and we don't
need to read all entry data into memory.
[[executable-jar-jarfile-compatibility]]
==== Compatibility with the standard Java ``JarFile''
Spring Boot Loader strives to remain compatible with existing code and libraries.
`org.springframework.boot.loader.jar.JarFile` extends from `java.util.jar.JarFile` and
should work as a drop-in replacement. The `RandomAccessJarFile.getURL()` method will
return a `URL` that opens a `java.net.JarURLConnection` compatible connection.
`RandomAccessJarFile` URLs can be used with Java's `URLClassLoader`.
[[executable-jar-launching]]
=== Launching executable jars
The `org.springframework.boot.loader.Launcher` class is a special bootstrap class that
is used as an executable jars main entry point. It is the actual `Main-Class` in your jar
file and it's used to setup an appropriate `URLClassLoader` and ultimately call your
`main()` method.
There are 3 launcher subclasses (`JarLauncher`, `WarLauncher` and `PropertiesLauncher`).
Their purpose is to load resources (`.class` files etc.) from nested jar files or war
files in directories (as opposed to explicitly on the classpath). In the case of the
`[Jar|War]Launcher` the nested paths are fixed `(lib/*.jar` and `lib-provided/*.jar` for
the war case) so you just add extra jars in those locations if you want more. The
`PropertiesLauncher` looks in `lib/` by default, but you can add additional locations by
setting an environment variable `LOADER_PATH` or `loader.path` in `application.properties`
(colon-separated list of directories or archives).
[[executable-jar-launcher-manifest]]
==== Launcher manifest
You need specify an appropriate `Launcher` as the `Main-Class` attribute of
`META-INF/MANIFEST.MF`. The actual class that you want to launch (i.e. the class that
you wrote that contains a `main` method) should be specified in the `Start-Class`
attribute.
For example, here is a typical `MANIFEST.MF` for a executable jar file:
[indent=0]
----
Main-Class: org.springframework.boot.loader.JarLauncher
Start-Class: com.mycompany.project.MyApplication
----
For a war file, it would be:
[indent=0]
----
Main-Class: org.springframework.boot.loader.WarLauncher
Start-Class: com.mycompany.project.MyApplication
----
NOTE: You do not need to specify `Class-Path` entries in your manifest file, the classpath
will be deduced from the nested jars.
[[executable-jar-exploded-archives]]
==== Exploded archives
Certain PaaS implementations may choose to unpack archives before they run. For example,
Cloud Foundry operates in this way. You can run an unpacked archive by simply starting
the appropriate launcher:
[indent=0]
----
$ unzip -q myapp.jar
$ java org.springframework.boot.loader.JarLauncher
----
[[executable-jar-property-launcher-features]]
=== PropertiesLauncher Features
`PropertiesLauncher` has a few special features that can be enabled with external
properties (System properties, environment variables, manifest entries or
`application.properties`).
[cols="2,4"]
|===
|Key |Purpose
|`loader.path`
|Colon-separated Classpath, e.g. `lib:${HOME}/app/lib`.
|`loader.home`
|Location of additional properties file, e.g. `file:///opt/app`
(defaults to `${user.dir}`)
|`loader.args`
|Default arguments for the main method (space separated)
|`loader.main`
|Name of main class to launch, e.g. `com.app.Application`.
|`loader.config.name`
|Name of properties file, e.g. `loader` (defaults to `application`).
|`loader.config.location`
|Path to properties file, e.g. `classpath:loader.properties` (defaults to
`application/.properties`).
|`loader.system`
|Boolean flag to indicate that all properties should be added to System properties
(defaults to `false`)
|===
Manifest entry keys are formed by capitalizing initial letters of words and changing the
separator to "`-`" from "`.`" (e.g. `Loader-Path`). The exception is `loader.main` which
is looked up as `Start-Class` in the manifest for compatibility with `JarLauncher`).
Environment variables can be capitalized with underscore separators instead of periods.
* `loader.home` is the directory location of an additional properties file (overriding
the default) as long as `loader.config.location` is not specified.
* `loader.path` can contain directories (scanned recursively for jar and zip files),
archive paths, or wildcard patterns (for the default JVM behavior).
* Placeholder replacement is done from System and environment variables plus the
properties file itself on all values before use.
[[executable-jar-restrictions]]
=== Executable jar restrictions
There are a number of restrictions that you need to consider when working with a Spring
Boot Loader packaged application.
[[executable-jar-zip-entry-compression]]
==== Zip entry compression
The `ZipEntry` for a nested jar must be saved using the `ZipEntry.STORED` method. This
is required so that we can seek directly to individual content within the nested jar.
The content of the nested jar file itself can still be compressed, as can any other
entries in the outer jar.
[[executable-jar-system-classloader]]
==== System ClassLoader
Launched applications should use `Thread.getContextClassLoader()` when loading classes
(most libraries and frameworks will do this by default). Trying to load nested jar
classes via `ClassLoader.getSystemClassLoader()` will fail. Please be aware that
`java.util.Logging` always uses the system classloader, for this reason you should
consider a different logging implementation.
[[executable-jar-alternatives]]
=== Alternative single jar solutions
If the above restrictions mean that you cannot use Spring Boot Loader the following
alternatives could be considered:
* http://maven.apache.org/plugins/maven-shade-plugin/[Maven Shade Plugin]
* http://www.jdotsoft.com/JarClassLoader.php[JarClassLoader]
* http://one-jar.sourceforge.net[OneJar]
spring-boot-docs/src/main/asciidoc/appendix.adoc 0 → 100644
View file @ d580ce53
[[appendix]]
= Appendices
include::appendix-application-properties.adoc[]
include::appendix-auto-configuration-classes.adoc[]
include::appendix-executable-jar-format.adoc[]
spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc 0 → 100644
View file @ d580ce53
[[cloud-deployment]]
= Deploying to the cloud
[partintro]
--
Spring Boot's executable jars are ready-made for most popular cloud PaaS
(platform-as-a-service) providers. These providers tend to require that you
_`bring your own container'_; they manage application processes (not Java applications
specifically), so they need some intermediary layer that adapts _your_ application to the
_cloud's_ notion of a running process.
Two popular cloud providers, Heroku and Cloud Foundry, employ a ``buildpack'' approach.
The buildpack wraps your deployed code in whatever is needed to _start_ your
application: it might be a JDK and a call to `java`, it might be an embedded webserver,
or it might be a full fledged application server. A buildpack is pluggable, but ideally
you should be able to get by with as few customizations to it as possible.
This reduces the footprint of functionality that is not under your control. It minimizes
divergence between deployment and production environments.
Ideally, your application, like a Spring Boot executable jar, has everything that it needs
to run packaged within it.
In this section we'll look at what it takes to get the
<<getting-started.adoc#getting-started-first-application, simple application that we
developed>> in the ``Getting Started'' section up and running in the Cloud.
--
[[cloud-deployment-cloud-foundry]]
== Cloud Foundry
Cloud Foundry provides default buildpacks that come into play if no other buildpack is
specified. The Cloud Foundry buildpack has excellent support for Spring applications,
including Spring Boot. You can deploy stand-alone executable jar applications, as well as
traditional `war` packaged applications.
Once you've built your application (using, for example, `mvn clean install`) and
http://docs.cloudfoundry.org/devguide/installcf/[installed the `cf` command line tool],
simply answer the `cf push` command's prompts as follows:
[indent=0,subs="verbatim,quotes,attributes"]
----
$ cf push --path target/demo-0.0.1-SNAPSHOT.jar
Name> *_$YOURAPP_*
Instances> *1*
Memory Limit> *256M*
Creating _$YOURAPP_... *OK*
1: _$YOURAPP_
2: none
Subdomain> *_$YOURAPP_*
1: cfapps.io
2: none
Domain> *cfapps.io*
Creating route _$YOURAPP_.cfapps.io... OK
Binding _$YOURAPP_.cfapps.io to _$YOURAPP_... OK
Create services for application?> *n*
Bind other services to application?> *n*
Save configuration?> *y*
----
At this point `cf` will start uploading your application:
[indent=0,subs="verbatim,quotes,attributes"]
----
Saving to manifest.yml... *OK*
Uploading $YOURAPP... *OK*
Preparing to start _$YOURAPP_... *OK*
-----> Downloaded app package (8.7M)
-----> Java Buildpack source: system
-----> Downloading Open JDK 1.7.0_51 from .../openjdk-1.7.0_51.tar.gz (*1.4s*)
Expanding Open JDK to .java-buildpack/open_jdk (*1.3s*)
-----> Downloading Spring Auto Reconfiguration 0.8.7 from .../auto-reconfiguration-0.8.7.jar (*0.0s*)
-----> Uploading droplet (*43M*)
Checking status of app '_$YOURAPP_'...
0 of 1 instances running (1 starting)
0 of 1 instances running (1 starting)
1 of 1 instances running (1 running)
Push successful! App '_$YOURAPP_' available at http://_$YOURAPP_.cfapps.io
----
NOTE: Here we are substituting `$YOURAPP` for whatever value you give `cf` when it asks
for the `name` of your application.
Once Cloud Foundry acknowledges that your application has been deployed, you should be
able to hit the application at the URI provided:
`http://$YOURAPP.cfapps.io/`.
[[cloud-deployment-cloud-foundry-services]]
=== Binding to services
By default, meta-data about the running application as well as service connection
information is exposed to the application as environment variables (for example:
`$VCAP_SERVICES`). This architecture decision is due to Cloud Foundry's polyglot
(any language and platform can be supported as a buildpack) nature; process-scoped
environment variables are language agnostic.
Environment variables don't always make for the easiest API so Spring Boot automatically
extracts then and flattens the data into properties that can be accessed through
Spring's `Environment` abstraction:
[source,java,indent=0]
----
@Component
class MyBean implements EnvironmentAware {
private String instanceId;
@Override
public void setEnvironment(Environment environment) {
this.instanceId = environment.getProperty("vcap.application.instance_id");
}
// ...
}
----
All Cloud Foundry properties are prefixed with `vcap`. You can use vcap properties to
access application information (such as the public URL of the application) and service
information (such as database credentials). See `VcapApplicationListener` Javdoc for
complete details.
TIP: The http://spring.io/projects/spring-cloud[Spring Cloud] project is a better fit
for tasks such as configuring a DataSource; and you can also use Spring Cloud with
Heroku too!
[[cloud-deployment-heroku]]
== Heroku
Heroku is another popular PaaS platform. To customize Heroku builds, you provide a
`Procfile`, which provides the incantation required to deploy an application. Heroku
assigns a `port` for the Java application to use and then ensures that routing to the
external URI works.
You must configure your application to listen on the correct port. This is a breeze with
Spring Boot. Here's the `Procfile` for our starter REST application:
[indent=0]
----
web: java -Dserver.port=$PORT -jar target/demo-0.0.1-SNAPSHOT.jar
----
Spring Boot makes `-D` arguments available as properties accessible from a Spring
`Environment` instance. The `server.port` configuration property is fed to the embedded
Tomcat or Jetty instance which then uses it when it starts up. The `$PORT` environment
variable is assigned to us by the Heroku PaaS.
Heroku by default will use Java 1.6. This is fine as long as your Maven or Gradle build
is set to use the same version (Maven users can use the `java.version` property). If you
want to use JDK 1.7, create a new file adjacent to your `pom.xml` and `Procfile`,
called `system.properties`. In this file add the following:
[source,java]
----
java.runtime.version=1.7
----
This should be everything you need. The most common workflow for Heroku deployments is to
`git push` the code to production.
[indent=0,subs="verbatim,quotes,attributes"]
----
$ git push heroku master
Initializing repository, *done*.
Counting objects: 95, *done*.
Delta compression using up to 8 threads.
Compressing objects: 100% (78/78), *done*.
Writing objects: 100% (95/95), 8.66 MiB | 606.00 KiB/s, *done*.
Total 95 (delta 31), reused 0 (delta 0)
-----> Java app detected
-----> Installing OpenJDK 1.7... *done*
-----> Installing Maven 3.0.3... *done*
-----> Installing settings.xml... *done*
-----> executing /app/tmp/cache/.maven/bin/mvn -B
-Duser.home=/tmp/build_0c35a5d2-a067-4abc-a232-14b1fb7a8229
-Dmaven.repo.local=/app/tmp/cache/.m2/repository
-s /app/tmp/cache/.m2/settings.xml -DskipTests=true clean install
[INFO] Scanning for projects...
Downloading: http://repo.spring.io/...
Downloaded: http://repo.spring.io/... (818 B at 1.8 KB/sec)
....
Downloaded: http://s3pository.heroku.com/jvm/... (152 KB at 595.3 KB/sec)
[INFO] Installing /tmp/build_0c35a5d2-a067-4abc-a232-14b1fb7a8229/target/...
[INFO] Installing /tmp/build_0c35a5d2-a067-4abc-a232-14b1fb7a8229/pom.xml ...
[INFO] ------------------------------------------------------------------------
[INFO] *BUILD SUCCESS*
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 59.358s
[INFO] Finished at: Fri Mar 07 07:28:25 UTC 2014
[INFO] Final Memory: 20M/493M
[INFO] ------------------------------------------------------------------------
-----> Discovering process types
Procfile declares types -> *web*
-----> Compressing... *done*, 70.4MB
-----> Launching... *done*, v6
http://agile-sierra-1405.herokuapp.com/ *deployed to Heroku*
To git@heroku.com:agile-sierra-1405.git
* [new branch] master -> master
----
That should be it! Your application should be up and running on Heroku.
[[cloud-deployment-cloudbees]]
== CloudBees
CloudBees provides cloud-based ``continuous integration'' and ``continuous delevery''
services as well as Java PaaS hosting. https://github.com/msgilligan[Sean Gilligan]
has contributed an excellent
https://github.com/CloudBees-community/springboot-gradle-cloudbees-sample[Spring Boot
sample application] to the CloudBees community GitHub repository. The project includes
an extensive https://github.com/CloudBees-community/springboot-gradle-cloudbees-sample/blob/master/README.asciidoc[README]
that covers the steps that you need to follow when deploying to CloudBees.
[[cloud-deployment-whats-next]]
== What to read next
Check out the http://www.cloudfoundry.com/[Cloud Foundry], https://www.heroku.com/[Heroku]
and http://www.cloudbees.com[CloudBees] web sites for more information about the kinds of
features that a PaaS can offer. These are just three of the more popular Java PaaS
providers, since Spring Boot is so amenable to cloud-based deployment you free to
consider other providers as well.
The next section goes on to cover the <<spring-boot-cli.adoc#cli, ``Spring Boot CLI''>>;
or you can jump ahead to read about
<<build-tool-plugins.adoc#build-tool-plugins, ``build tool plugins''>>.
spring-boot-docs/src/main/asciidoc/documentation-overview.adoc 0 → 100644
View file @ d580ce53
[[boot-documentation]]
= Spring Boot Documentation
[partintro]
--
This section provides a brief overview of Spring Boot reference documentation. Think of
it as map for the rest of the document. You can read this reference guide in a linear
fashion, or you can skip sections if something doesn't interest you.
--
[[boot-documentation-getting-help]]
== Getting help
Having trouble with Spring Boot, We'd like to help!
* Try the <<howto.adoc#howto, How-to's>> -- they provide solutions to the most common
questions
* Learn the Spring basics -- Spring Boot is builds on many other Spring projects, check
the http://spring.io[spring.io] web-site for a wealth of reference documentation. If
you are just starting out with Spring, try one of the http://spring.io/guides[guides]
* Ask a questions - we monitor http://stackoverflow.com[stackoverflow.com] for questions
tagged with http://stackoverflow.com/tags/spring-boot[`spring-boot`]
* Report bugs with Spring Boot at https://github.com/spring-projects/spring-boot/issues
NOTE: All of Spring Boot is open source, including the documentation! If you find problems
with the docs; or if you just want to improve them, please <<github-code, get involved>>.
[[boot-documentation-first-steps]]
== First steps
If your just getting started with Spring Boot, or 'Spring' in general,
<<getting-started.adoc#getting-started, this is the place to start!>>
* *From scratch:*
<<getting-started.adoc#getting-started-introducing-spring-boot, Overview>> |
<<getting-started.adoc#getting-started-installing-spring-boot, Installation>>
* *Tutorial:*
<<getting-started.adoc#getting-started-first-application, Part 1>> |
<<getting-started.adoc#getting-started-first-application-code, Part 2>>
* *Running your example:*
<<getting-started.adoc#getting-started-first-application-run, Part 1>> |
<<getting-started.adoc#getting-started-first-application-executable-jar, Part 2>>
== Working with Spring Boot
Ready to actually start using Spring Boot? <<using-spring-boot.adoc#using-boot, We've
got you covered>>.
* *Build systems:*
<<using-spring-boot.adoc#using-boot-maven, Maven>> |
<<using-spring-boot.adoc#using-boot-gradle, Gradle>> |
<<using-spring-boot.adoc#using-boot-ant, Ant>> |
<<using-spring-boot.adoc#using-boot-starter-poms, Starter POMs>>
* *Best practices:*
<<using-spring-boot.adoc#using-boot-structuring-your-code, Code Structure>> |
<<using-spring-boot.adoc#using-boot-configuration-classes, @Configuration>> |
<<using-spring-boot.adoc#using-boot-auto-configuration, @EnableAutoConfiguration>> |
<<using-spring-boot.adoc#using-boot-spring-beans-and-dependency-injection, Beans and Dependency Injection>>
* *Running your code*
<<using-spring-boot.adoc#using-boot-running-from-an-ide, IDE>> |
<<using-spring-boot.adoc#using-boot-running-as-a-packaged-application, Packaged>> |
<<using-spring-boot.adoc#using-boot-running-with-the-maven-plugin, Maven>> |
<<using-spring-boot.adoc#using-boot-running-with-the-gradle-plugin, Gradle>>
* *Packaging your app:*
<<using-spring-boot.adoc#using-boot-packaging-for-production, Production jars>>
* *Spring Boot CLI:*
<<using-spring-boot-cli.adoc#cli, Using the CLI>>
== Learning about Spring Boot features
Need more details about Spring Boot's core features?
<<spring-boot-features.adoc#boot-features, This is for you>>!
* *Core Features:*
<<spring-boot-features.adoc#boot-features-spring-application, SpringApplication>> |
<<spring-boot-features.adoc#boot-features-external-config, External Configuration>> |
<<spring-boot-features.adoc#boot-features-profiles, Profiles>> |
<<spring-boot-features.adoc#boot-features-logging, Logging>>
* *Web Applications:*
<<spring-boot-features.adoc#boot-features-spring-mvc, MVC>> |
<<spring-boot-features.adoc#boot-features-embedded-container, Embedded Containers>>
* *Working with data:*
<<spring-boot-features.adoc#boot-features-sql, SQL>> |
<<spring-boot-features.adoc#boot-features-nosql, NO-SQL>>
* *Testing:*
<<spring-boot-features.adoc#boot-features-testing, Overview>> |
<<spring-boot-features.adoc#boot-features-testing-spring-boot-applications, Boot Applications>> |
<<spring-boot-features.adoc#boot-features-test-utilities, Utils>>
* *Extending:*
<<spring-boot-features.adoc#boot-features-developing-auto-configuration, Auto-configuration>> |
<<spring-boot-features.adoc#boot-features-condition-annotations, @Conditions>>
== Moving to production
When your ready to push your Spring Boot application to production, we've got
<<production-ready-features.adoc#production-ready, some tricks that you might like>>!
* *Management endpoints:*
<<production-ready-features.adoc#production-ready-endpoints, Overview>> |
<<production-ready-features.adoc#production-ready-customizing-endpoints, Customization>>
* *Connection options:*
<<production-ready-features.adoc#production-ready-monitoring, HTTP>> |
<<production-ready-features.adoc#production-ready-jmx, JMX>> |
<<production-ready-features.adoc#production-ready-remote-shell, SSH>>
* *Monitoring:*
<<production-ready-features.adoc#production-ready-metrics, Metrics>> |
<<production-ready-features.adoc#production-ready-auditing, Auditing>> |
<<production-ready-features.adoc#production-ready-tracing, Tracing>>
== Advanced topics
Lastly, we have a few topics for the more advanced user.
* *Deploy to the cloud:*
<<cloud-deployment.adoc#cloud-deployment-cloud-foundry, Cloud Foundry>> |
<<cloud-deployment.adoc#cloud-deployment-heroku, Heroku>> |
<<cloud-deployment.adoc#cloud-deployment-cloudbees, CloudBees>>
* *Build tool plugins:*
<<build-tool-plugins.adoc#build-tool-plugins-maven-plugin, Maven>> |
<<build-tool-plugins.adoc#build-tool-plugins-gradle-plugin, Gradle>>
* *Appendix:*
<<appendix-application-properties.adoc#common-application-properties, Application Properties>> |
<<appendix-auto-configuration-classes.adoc#auto-configuration-classes, Auto-configuration classes>> |
<<appendix-executable-jar-format.adoc#executable-jar, Executable Jars>>
spring-boot-docs/src/main/asciidoc/getting-started.adoc 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/asciidoc/howto.adoc 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/asciidoc/index-docinfo.xml 0 → 100644
View file @ d580ce53
<productname>Spring Boot</productname>
<releaseinfo>{spring-boot-version}</releaseinfo>
<copyright>
<year>2013-2014</year>
</copyright>
<legalnotice>
<para>
Copies of this document may be made for your own use and for distribution to
others, provided that you do not charge any fee for such copies and further
provided that each copy contains this Copyright Notice, whether distributed in
print or electronically.
</para>
</legalnotice>
spring-boot-docs/src/main/asciidoc/index.adoc 0 → 100644
View file @ d580ce53
= Spring Boot Reference Guide
Phillip Webb; Dave Syer; Josh Long;
:doctype: book
:toc:
:toclevels: 4
:source-highlighter: prettify
:numbered:
:icons: font
:spring-boot-repo: snapshot
:github-tag: master
:spring-boot-docs-version: current
:github-repo: spring-projects/spring-boot
:github-raw: http://raw.github.com/{github-repo}/{github-tag}
:github-code: http://github.com/{github-repo}/tree/{github-tag}
:sc-ext: java
:sc-spring-boot: {github-code}/spring-boot/src/main/java/org/springframework/boot
:sc-spring-boot-autoconfigure: {github-code}/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure
:sc-spring-boot-actuator: {github-code}/spring-boot-actuator/src/main/java/org/springframework/boot/actuate
:sc-spring-boot-cli: {github-code}/spring-boot-cli/src/main/java/org/springframework/boot/cli
:dc-ext: html
:dc-root: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/api
:dc-spring-boot: {dc-root}/org/springframework/boot
:dc-spring-boot-autoconfigure: {dc-root}/org/springframework/boot/autoconfigure
:dc-spring-boot-actuator: {dc-root}/org/springframework/boot/actuate
:spring-reference: http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle
:spring-data-javadoc: http://docs.spring.io/spring-data/jpa/docs/current/api/org/springframework/data/jpa
:spring-data-commons-javadoc: http://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data
:spring-data-mongo-javadoc: http://docs.spring.io/spring-data/mongodb/docs/current/api/org/springframework/data/mongodb
// ======================================================================================
include::documentation-overview.adoc[]
include::getting-started.adoc[]
include::using-spring-boot.adoc[]
include::spring-boot-features.adoc[]
include::production-ready-features.adoc[]
include::cloud-deployment.adoc[]
include::spring-boot-cli.adoc[]
include::build-tool-plugins.adoc[]
include::howto.adoc[]
include::appendix.adoc[]
// ======================================================================================
spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc 0 → 100644
View file @ d580ce53
[[cli]]
= Spring Boot CLI
[partintro]
--
The Spring Boot CLI is a command line tool that can be used if you want to quickly
prototype with Spring. It allows you to run Groovy scripts, which means that you have a
familiar Java-like syntax, without so much boilerplate code.
--
[[cli-installation]]
== Installing the CLI
The Spring Boot CLI can be installed manually; using GVM (the Groovy Environment
Manually) or using Homebrew if you are an OSX user. See
``<<getting-started.adoc#getting-started-installing-the-cli>>''
in the ``Getting started'' section for comprehensive installation instructions.
[[cli-using-the-cli]]
== Using the CLI
Once you have installed the CLI you can run it by typing `spring`. If you run `spring`
without any arguments, a simple help screen is displayed:
[indent=0,subs="verbatim,quotes,attributes"]
----
$ spring
usage: spring [--help] [--version]
<command> [<args>]
Available commands are:
run [options] <files> [--] [args]
Run a spring groovy script
_... more command help is shown here_
----
You can use `help` to get more details about any of the supported commands. For example:
[indent=0]
----
$ spring help run
spring run - Run a spring groovy script
usage: spring run [options] <files> [--] [args]
Option Description
------ -----------
--autoconfigure [Boolean] Add autoconfigure compiler
transformations (default: true)
--classpath, -cp Additional classpath entries
-e, --edit Open the file with the default system
editor
--no-guess-dependencies Do not attempt to guess dependencies
--no-guess-imports Do not attempt to guess imports
-q, --quiet Quiet logging
-v, --verbose Verbose logging of dependency
resolution
--watch Watch the specified file for changes
----
The `version` command provides a quick way to check which version of Spring Boot you are
using.
[indent=0,subs="verbatim,quotes,attributes"]
----
$ spring version
Spring CLI v{spring-boot-version}
----
[[cli-run]]
=== Running applications using the CLI
You can compile and run Groovy source code using the `run` command. The Spring Boot CLI
is completely self contained so you don't need any external Groovy installation.
Here is an example ``hello world'' web application written in Groovy:
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
----
@Controller
class WebApplication {
@RequestMapping("/")
@ResponseBody
String home() {
return "Hello World!"
}
}
----
[[cli-deduced-grab-annotations]]
==== Deduced ``grab'' dependencies
Standard Groovy includes a `@Grab` annotation which allows you to declare dependencies
on a third-party libraries. This useful technique allows Groovy to download jars in the
same way as Maven or Gradle would; but without requiring you to use a build tool.
Spring Boot extends this technique further, and will attempt to deduce which libraries
to ``grab'' based on your code. For example, since the `WebApplication` code above uses
`@Controller` annotations, ``Tomcat'' and ``Spring MVC'' will be grabbed.
The following items are used as ``grab hints'':
|===
| Items | Grabs
|`JdbcTemplate`, `NamedParameterJdbcTemplate`, `DataSource`
|JDBC Application.
|`@EnableJmsMessaging`
|JMS Application.
|`@Test`
|JUnit.
|`@EnableRabbitMessaging`
|RabbitMQ.
|`@EnableReactor`
|Project Reactor.
|extends `Specification`
|Spock test.
|`@EnableBatchProcessing`
|Spring Batch.
|`@MessageEndpoint` `@EnableIntegrationPatterns`
|Spring Integration.
|`@EnableDeviceResolver`
|Spring Mobile.
|`@Controller` `@RestController` `@EnableWebMvc`
|Spring MVC + Embedded Tomcat.
|`@EnableWebSecurity`
|Spring Security.
|`@EnableTransactionManagement`
|Spring Transaction Management.
|===
TIP: See subclasses of
{sc-spring-boot-cli}/compiler/CompilerAutoConfiguration.{sc-ext}[`CompilerAutoConfiguration`]
in the Spring Boot CLI source code to understand exactly how customizations are applied.
[[cli-default-import-statements]]
==== Default import statements
To help reduce the size of your Groovy code, several `import` statements are
automatically included. Notice how the example above refers to `@Component`,
`@Controller`, `@RequestMapping` and `@ResponseBody` without needing to use
fully-qualified names or `import` statements.
TIP: Many Spring annotations will work without using `import` statements. Try running
your application to see what fails before adding imports.
[[cli-automatic-main-method]]
==== Automatic main method
Unlike the equilvement Java application, you do not need to include a
`public static void main(String[] args)` method with your `Groovy` scripts. A
`SpringApplication` is automatically created, with your compiled code acting as the
`source`.
[[cli-testing]]
=== Testing your code
The `test` command allows you to compile and run tests for your application. Typical
usage looks like this:
[indent=0]
----
$ spring test app.groovy tests.groovy
Total: 1, Success: 1, : Failures: 0
Passed? true
----
In this example, `tests.groovy` contains JUnit `@Test` methods or Spock `Specification`
classes. All the common framework annotations and static methods should be available to
you without having to `import` them.
Here is the `test.groovy` file that we used above:
[source,groovy,indent=0]
----
class ApplicationTests {
@Test
void homeSaysHello() {
assertEquals("Hello World", new WebApplication().home())
}
}
----
TIP: If you have more than one test source files, you might prefer to organize them
into a `test` directory.
[[cli-multiple-source-files]]
=== Applications with multiple source files
You can use ``shell globbing'' with all commands that accept file input. This allows you
to easily use multiple files from a single directory, e.g.
[indent=0]
----
$ spring run *.groovy
----
This technique can also be useful if you want to segregate your ``test'' or ``spec'' code
from the main application code:
[indent=0]
----
$ spring test app/*.groovy test/*.groovy
----
[[cli-jar]]
=== Packaging your application
You can use the `jar` command to package your application into a self-contained
executable jar file. For example:
[indent=0]
----
$ spring jar my-app.jar *.groovy
----
The resulting jar will contain the classes produced by compiling the application and all
of the application's dependencies so that it can then be run using `java -jar`. The jar
file will also contain entries from the application's classpath.
See the output of `spring help jar` for more information.
[[cli-shell]]
=== Using the embedded shell
Spring Boot includes command-line completion scripts for BASH and zsh shells. If you
don't use either of these shells (perhaps you are a Windows user) then you can use the
`shell` command to launch an integrated shell.
[indent=0,subs="verbatim,quotes,attributes"]
----
$ spring shell
*Spring Boot* (v{spring-boot-version})
Hit TAB to complete. Type \'help' and hit RETURN for help, and \'exit' to quit.
----
From inside the embedded shell you can run other commands directly:
[indent=0,subs="verbatim,quotes,attributes"]
----
$ version
Spring CLI v{spring-boot-version}
----
The embedded shell supports ANSI color output as well as `tab` completion. If you need
to run a native command you can use the `$` prefix. Hitting `ctrl-c` will exit the
embedded shell.
[[cli-groovy-beans-dsl]]
== Developing application with the Groovy beans DSL
Spring Framework 4.0 has native support for a `beans{}` ``DSL'' (borrowed from
http://grails.org/[Grails]), and you can embed bean definitions in your Groovy
application scripts using the same format. This is sometimes a good way to include
external features like middleware declarations. For example:
[source,groovy,indent=0]
----
@Configuration
class Application implements CommandLineRunner {
@Autowired
SharedService service
@Override
void run(String... args) {
println service.message
}
}
import my.company.SharedService
beans {
service(SharedService) {
message "Hello World"
}
}
----
You can mix class declarations with `beans{}` in the same file as long as they stay at
the top level, or you can put the beans DSL in a separate file if you prefer.
[[cli-whats-next]]
== What to read next
There are some {github-code}/spring-boot-cli/samples[sample groovy
scripts] available from the GitHub repository that you can use to try out the
Spring Boot CLI. There is also extensive javadoc throughout the
{sc-spring-boot-cli}[source code].
If you find that you reach the limit of the CLI tool, you will probably want to look
at converting your application to full Gradle or Maven built ``groovy project''. The
next section covers Spring Boot's
``<<build-tool-plugins.adoc#build-tool-plugins, Build tool plugins>>'' that you can
use with Gradle or Maven.
spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/css/highlight.css 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/css/manual-multipage.css 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/css/manual-singlepage.css 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/css/manual.css 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/images/note.png 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/images/tip.png 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/images/warning.png 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/common.xsl 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/epub.xsl 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/html-multipage.xsl 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/html-singlepage.xsl 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/html.xsl 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/pdf.xsl 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl-config.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/asciidoc-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/bourne-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/c-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/cpp-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/csharp-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/css-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/html-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/ini-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/java-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/javascript-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/perl-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/php-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/python-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/ruby-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
spring-boot-docs/src/main/docbook/xsl/xslthl/sql2003-hl.xml 0 → 100644
View file @ d580ce53
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment