diff --git a/spring-boot-docs/src/main/asciidoc/appendix-application-properties.adoc b/spring-boot-docs/src/main/asciidoc/appendix-application-properties.adoc new file mode 100644 index 0000000000..581411be4d --- /dev/null +++ b/spring-boot-docs/src/main/asciidoc/appendix-application-properties.adoc @@ -0,0 +1,249 @@ +: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 +---- diff --git a/spring-boot-docs/src/main/asciidoc/appendix-auto-configuration-classes.adoc b/spring-boot-docs/src/main/asciidoc/appendix-auto-configuration-classes.adoc new file mode 100644 index 0000000000..d1f612605f --- /dev/null +++ b/spring-boot-docs/src/main/asciidoc/appendix-auto-configuration-classes.adoc @@ -0,0 +1,147 @@ +[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] +|=== diff --git a/spring-boot-docs/src/main/asciidoc/appendix-executable-jar-format.adoc b/spring-boot-docs/src/main/asciidoc/appendix-executable-jar-format.adoc new file mode 100644 index 0000000000..3b6ec5cb0b --- /dev/null +++ b/spring-boot-docs/src/main/asciidoc/appendix-executable-jar-format.adoc @@ -0,0 +1,277 @@ +[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 + | +- + +-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 + | +- + +-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] diff --git a/spring-boot-docs/src/main/asciidoc/appendix.adoc b/spring-boot-docs/src/main/asciidoc/appendix.adoc new file mode 100644 index 0000000000..6acfbf84d7 --- /dev/null +++ b/spring-boot-docs/src/main/asciidoc/appendix.adoc @@ -0,0 +1,7 @@ +[[appendix]] += Appendices + +include::appendix-application-properties.adoc[] +include::appendix-auto-configuration-classes.adoc[] +include::appendix-executable-jar-format.adoc[] + diff --git a/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc b/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc new file mode 100644 index 0000000000..a5f84aa4dc --- /dev/null +++ b/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc @@ -0,0 +1,578 @@ +[[build-tool-plugins]] += Build tool plugins + +[partintro] +-- +Spring Boot provides build tool plugins for Maven and Gradle. The plugins offer a +variety of features, including the packaging of executable jars. The section provides +more details on both plugins, as well as some help should you need to extend an +unsupported build system. If you are just getting started, you might want to read +``<>'' from the +<> section first. +-- + + + +[[build-tool-plugins-maven-plugin]] +== Spring Boot Maven plugin +The Spring Boot Maven Plugin provides Spring Boot support in Maven, allowing you to +package executable jar or war archives and run an application ``in-place''. To use it you +must be using Maven 3 (or better). + + + +[[build-tool-plugins-include-maven-plugin]] +=== Including the plugin +To use the Spring Boot Maven Plugin simply include the appropriate XML in the `plugins` +section of your `pom.xml` + +[source,xml,indent=0,subs="verbatim,attributes"] +---- + + + 4.0.0 + + + + + org.springframework.boot + spring-boot-maven-plugin + {spring-boot-version} + + + + repackage + + + + + + + +---- + +This configuration will repackage a jar or war that is built during the `package` phase of +the Maven lifecycle. The following example shows both the repackaged jar, as well as the +original jar, in the `target` directory: + +[indent=0] +---- + $ mvn package + $ ls target/*.jar + target/myproject-1.0.0.jar target/myproject-1.0.0.jar.original +---- + + +If you don't include the `` configuration as above, you can run the plugin on +its own (but only if the package goal is used as well). For example: + +[indent=0] +---- + $ mvn package spring-boot:repackage + $ ls target/*.jar + target/myproject-1.0.0.jar target/myproject-1.0.0.jar.original +---- + +If you are using a milestone or snapshot release you will also need to add appropriate +`pluginRepository` elements: + +[source,xml,indent=0,subs="verbatim,attributes"] +---- + + + spring-snapshots + http://repo.spring.io/snapshot + + + spring-milestones + http://repo.spring.io/milestone + + +---- + + + +[[build-tool-plugins-maven-packaging]] +=== Packaging executable jar and war files +Once `spring-boot-maven-plugin` has been included in your `pom.xml` it will automatically +attempt to rewrite archives to make them executable using the `spring-boot:repackage` +goal. You should configure your project to build a jar or war (as appropriate) using the +usual `packaging` element: + +[source,xml,indent=0,subs="verbatim,attributes"] +---- + + + + jar + + +---- + +Your existing archive will be enhanced by Spring Boot during the `package` phase. The +main class that you want to launch can either be specified using a configuration option, +or by adding a `Main-Class` attribute to the manifest in the usual way. If you don't +specify a main class the plugin will search for a class with a +`public static void main(String[] args)` method. + +To build and run a project artifact, you can type the following: + +[indent=0] +---- + $ mvn package + $ java -jar target/mymodule-0.0.1-SNAPSHOT.jar +---- + + + +[[build-tool-plugins-maven-packaging-configuration]] +=== Repackage configuration +The following configuration options are available for the `spring-boot:repackage` goal: + + + +[[build-tool-plugins-maven-packaging-required-params]] +==== Required parameters +[cols="2,4"] +|=== +|Name |Description + +|`outputDirectory` +|Directory containing the generated archive (defaults to `${project.build.directory}`). + +|`finalName` +|Name of the generated archive (defaults to `${project.build.finalName}`). +|=== + +|== + +[[build-tool-plugins-maven-packaging-optional-params]] +==== Optional parameters +[cols="2,4"] +|=== +|Name |Description + +|`classifier` +|Classifier to add to the artifact generated. If given, the artifact will be attached. If + this is not given, it will merely be written to the output directory according to the + `finalName`. + +|`mainClass` +|The name of the main class. If not specified will search for a single compiled class + that contains a `main` method. + +|`layout` +|The type of archive (which corresponds to how the dependencies are laid out inside it). + Defaults to a guess based on the archive type. +|=== + +The plugin rewrites your manifest, and in particular it manages the `Main-Class` and +`Start-Class` entries, so if the defaults don't work you have to configure those there +(not in the jar plugin). The `Main-Class` in the manifest is actually controlled by the +`layout` property of the boot plugin, e.g. + +[source,xml,indent=0,subs="verbatim,attributes"] +---- + + org.springframework.boot + spring-boot-maven-plugin + {spring-boot-version} + + ${start-class} + ZIP + + + + + repackage + + + + +---- + +The layout property defaults to a guess based on the archive type (jar or war). For the +`PropertiesLauncher` the layout is ``ZIP'' (even though the output might be a jar file). + +TIP: The executable jar format is <>. + +[[build-tool-plugins-maven-running-applications]] +=== Running applications +The Spring Boot Maven Plugin includes a `run` goal which can be used to launch your +application from the command line. Type the following from the root of your Maven +project: + +[indent=0] +---- + $ mvn spring-boot:run +---- + +By default, any `src/main/resources` folder will be added to the application classpath +when you run via the maven plugin. This allows hot refreshing of resources which can be +very useful when developing web applications. For example, you can work on HTML, CSS or +JavaScipt files and see your changes immediately without recompiling your application. It +is also a helpful way of allowing your front end developers to work without needing to +download and install a Java IDE. + + + +[[build-tool-plugins-maven-run-configuration]] +=== Run configuration +The following configuration options are available for the `spring-boot:run` goal: + + + +[[build-tool-plugins-maven-run-configuration-required-params]] +=== Required parameters +[cols="2,4"] +|=== +|Name |Description + +|`classesDirectrory` +|Directory containing the classes and resource files that should be packaged into the + archive (defaults to `${project.build.outputDirectory}`). +|=== + + + +[[build-tool-plugins-maven-run-configuration-optional-params]] +=== Optional parameters +[cols="2,4"] +|=== +|Name |Description + +|`arguments` or `-Drun.arguments` +|Arguments that should be passed to the application. + +|`addResources` or `-Drun.addResources` +|Add Maven resources to the classpath directly, this allows live in-place editing or + resources. Since resources will be added directly, and via the target/classes folder + they will appear twice if `ClassLoader.getResources()` is called. In practice, however, + most applications call `ClassLoader.getResource()` which will always return the first + resource (defaults to `true`). + +|`mainClass` +|The name of the main class. If not specified the first compiled class found that + contains a 'main' method will be used. + +|`folders` +|Folders that should be added to the classpath (defaults to + `${project.build.outputDirectory}`). +|=== + + + +[[build-tool-plugins-gradle-plugin]] +== Spring Boot Gradle plugin +The Spring Boot Gradle Plugin provides Spring Boot support in Gradle, allowing you to +package executable jar or war archives, run Spring Boot applications and omit version +information from your `build.gradle` file for ``blessed'' dependencies. + + + +[[build-tool-plugins-including-the-gradle-plugin]] +=== Including the plugin +To use the Spring Boot Gradle Plugin simply include a `buildscript` dependency and apply +the `spring-boot` plugin: + +[source,groovy,indent=0,subs="verbatim,attributes"] +---- + buildscript { + dependencies { + classpath("org.springframework.boot:spring-boot-gradle-plugin:{spring-boot-version}") + } + } + apply plugin: 'spring-boot' +---- + +If you are using a milestone or snapshot release you will also need to add appropriate +`repositories` reference: + +[source,groovy,indent=0,subs="verbatim,attributes"] +---- + buildscript { + repositories { + maven.url "http://repo.spring.io/snapshot" + maven.url "http://repo.spring.io/milestone" + } + // ... + } +---- + + + +[[build-tool-plugins-gradle-dependencies-without-versions]] +=== Declaring dependencies without versions +The `spring-boot` plugin will register a custom Gradle `ResolutionStrategy` with your +build that allows you to omit version numbers when declaring dependencies to ``blessed'' +artifacts. All artifacts with a `org.springframework.boot` group ID, and any of the +artifacts declared in the `managementDependencies` section of the +{github-code}/spring-boot-dependencies/pom.xml[`spring-dependencies`] +POM can have their version number resolved automatically. + +Simply declare dependencies in the usual way, but leave the version number empty: + +[source,groovy,indent=0,subs="verbatim,attributes"] +---- + dependencies { + compile("org.springframework.boot:spring-boot-starter-web") + compile("org.thymeleaf:thymeleaf-spring4") + compile("nz.net.ultraq.thymeleaf:thymeleaf-layout-dialect") + } +---- + + + +[[build-tool-plugins-gradle-packaging]] +=== Packaging executable jar and war files +Once the `spring-boot` plugin has been applied to your project it will automatically +attempt to rewrite archives to make them executable using the `bootRepackage` task. You +should configure your project to build a jar or war (as appropriate) in the usual way. + +The main class that you want to launch can either be specified using a configuration +option, or by adding a `Main-Class` attribute to the manifest. If you don't specify a +main class the plugin will search for a class with a +`public static void main(String[] args)` method. + +To build and run a project artifact, you can type the following: + +[indent=0] +---- + $ gradle build + $ java -jar build/libs/mymodule-0.0.1-SNAPSHOT.jar +---- + + + +[[build-tool-plugins-gradle-running-applications]] +=== Running a project in-place +To run a project in place without building a jar first you can use the "bootRun" task: + +[indent=0] +---- + $ gradle bootRun +---- + +Running this way makes your static classpath resources (i.e. in `src/main/resources` by +default) reloadable in the live application, which can be helpful at development time. + +[[build-tool-plugins-gradle-repackage-configuration]] +=== Repackage configuration +The gradle plugin automatically extends your build script DSL with a `springBoot` element +for configuration. Simply set the appropriate properties as you would any other Gradle +extension (see below for a list of configuration options): + +[source,groovy,indent=0,subs="verbatim,attributes"] +---- + springBoot { + backupSource = false + } +---- + + + +[[build-tool-plugins-gradle-repackage-custom-configuration]] +=== Repackage with custom Gradle configuration +Sometimes it may be more appropriate to not package default dependencies resolved from +`compile`, `runtime` and `provided` scopes. If the created executable jar file +is intended to be run as it is, you need to have all dependencies nested inside it; +however, if the plan is to explode a jar file and run main class manually, you may already +have some of the libraries available via `CLASSPATH`. This is a situation where +you can repackage your jar with a different set of dependencies. + +Using a custom +configuration will automatically disable dependency resolving from +`compile`, `runtime` and `provided` scopes. Custom configuration can be either +defined globally (inside the `springBoot` section) or per task. + +[source,groovy,indent=0,subs="verbatim,attributes"] +---- + task clientJar(type: Jar) { + appendix = 'client' + from sourceSets.main.output + exclude('**/*Something*') + } + + task clientBoot(type: BootRepackage, dependsOn: clientJar) { + withJarTask = clientJar + customConfiguration = "mycustomconfiguration" + } +---- + +In above example, we created a new `clientJar` Jar task to package a customized +file set from your compiled sources. Then we created a new `clientBoot` +BootRepackage task and instructed it to work with only `clientJar` task and +`mycustomconfiguration`. + +[source,groovy,indent=0,subs="verbatim,attributes"] +---- + configurations { + mycustomconfiguration.exclude group: 'log4j' + } + + dependencies { + mycustomconfiguration configurations.runtime + } +---- + +The configuration that we are referring to in `BootRepackage` is a normal +http://www.gradle.org/docs/current/dsl/org.gradle.api.artifacts.Configuration.html[Gradle +configuration]. In the above example we created a new configuration named +`mycustomconfiguration` instructing it to derive from a `runtime` and exclude the `log4j` +group. If the `clientBoot` task is executed, the repackaged boot jar will have all +dependencies from `runtime` but no `log4j` jars. + + + +[[build-tool-plugins-gradle-configuration-options]] +==== Configuration options +The following configuration options are available: + +[cols="2,4"] +|=== +|Name |Description + +|`mainClass` +|The main class that should be run. If not specified the value from the manifest will be + used, or if no manifest entry is the archive will be searched for a suitable class. + +|`providedConfiguration` +|The name of the provided configuration (defaults to `providedRuntime`). + +|`backupSource` +|If the original source archive should be backed-up before being repackaged (defaults + to `true`). + +|`customConfiguration` +|The name of the custom configuration. + +|`layout` +|The type of archive, corresponding to how the dependencies are laid out inside + (defaults to a guess based on the archive type). +|=== + + + +[[build-tool-plugins-understanding-the-gradle-plugin]] +=== Understanding how the Gradle plugin works +When `spring-boot` is applied to your Gradle project a default task named `bootRepackage` +is created automatically. The `bootRepackage` task depends on Gradle `assemble` task, and +when executed, it tries to find all jar artifacts whose qualifier is empty (i.e. tests and +sources jars are automatically skipped). + +Due to the fact that `bootRepackage` finds 'all' created jar artifacts, the order of +Gradle task execution is important. Most projects only create a single jar file, so +usually this is not an issue; however, if you are planning to create a more complex +project setup, with custom `Jar` and `BootRepackage` tasks, there are few tweaks to +consider. + +If you are 'just' creating custom jar files from your project you can simply disables +default `jar` and `bootRepackage` tasks: + +[source,groovy,indent=0,subs="verbatim,attributes"] +---- + jar.enabled = false + bootRepackage.enabled = false +---- + +Another option is to instruct the default `bootRepackage` task to only work with a +default `jar` task. + +[source,groovy,indent=0,subs="verbatim,attributes"] +---- + bootRepackage.withJarTask = jar +---- + +If you have a default project setup where the main jar file is created and repackaged, +'and' you still want to create additional custom jars, you can combine your custom +repackage tasks together and use `dependsOn` so that the `bootJars` task will run after +the default `bootRepackage` task is executed: + +[source,groovy,indent=0,subs="verbatim,attributes"] +---- + task bootJars + bootJars.dependsOn = [clientBoot1,clientBoot2,clientBoot3] + build.dependsOn(bootJars) +---- + +All the above tweaks are usually used to avoid situations where an already created boot +jar is repackaged again. Repackaging an existing boot jar will not break anything, but +you may find that it includes unnecessary dependencies. + + + +[[build-tool-plugins-other-build-systems]] +== Supporting other build systems +If you want to use a build tool other than Maven or Gradle, you will likely need to develop +your own plugin. Executable jars need to follow a specific format and certain entries need +to be written in an uncompressed form (see the +``<>'' section +in the appendix for details). + +The Spring Boot Maven and Gradle plugins both make use of `spring-boot-loader-tools` to +actually generate jars. You are also free to use this library directly yourself if you +need to. + + + +[[build-tool-plugins-repackaging-archives]] +=== Repackaging archives +To repackage an existing archive so that it becomes a self-contained executable archive +use `org.springframework.boot.loader.tools.Repackager`. The `Repackager` class takes a +single constructor argument that refers to an existing jar or war archive. Use one of the +two available `repackage()` methods to either replace the original file or write to a new +destination. Various settings can also be configured on the repackager before it is +run. + + + +[[build-tool-plugins-nested-libraries]] +=== Nested libraries +When repackaging an archive you can include references to dependency files using the +`org.springframework.boot.loader.tools.Libraries` interface. We don't provide any +concrete implementations of `Libraries` here as they are usually build system specific. + +If your archive already includes libraries you can use `Libraries.NONE`. + + + +[[build-tool-plugins-find-a-main-class]] +=== Finding a main class +If you don't use `Repackager.setMainClass()` to specify a main class, the repackager will +use http://asm.ow2.org/[ASM] to read class files and attempt to find a suitable class +with a `public static void main(String[] args)` method. An exception is thrown if more +than one candidate is found. + + + +[[build-tool-plugins-repackage-implementation]] +=== Example repackage implementation +Here is a typical example repackage: + +[source,java,indent=0] +---- + Repackager repackager = new Repackager(sourceJarFile); + repackager.setBackupSource(false); + repackager.repackage(new Libraries() { + @Override + public void doWithLibraries(LibraryCallback callback) throws IOException { + // Build system specific implementation, callback for each dependency + // callback.library(nestedFile, LibraryScope.COMPILE); + } + }); +---- + + + +[[build-tool-plugins-whats-next]] +== What to read next +If your interested to looking at how the build tool plugins were developed you can +look at the {github-code}/spring-boot-tools[`spring-boot-tools`] module on GitHub. More +technical details of the <> are covered in the appendix. + +If you have specific build related questions, you can check out the +``<>'' guides. diff --git a/spring-boot-docs/src/main/asciidoc/documentation-overview.adoc b/spring-boot-docs/src/main/asciidoc/documentation-overview.adoc new file mode 100644 index 0000000000..3292b6788e --- /dev/null +++ b/spring-boot-docs/src/main/asciidoc/documentation-overview.adoc @@ -0,0 +1,123 @@ +[[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 <> -- 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 <>. + +[[boot-documentation-first-steps]] +== First steps +If your just getting started with Spring Boot, or 'Spring' in general, +<> + +* *From scratch:* + <> | + <> +* *Tutorial:* + <> | + <> +* *Running your example:* + <> | + <> + + + +== Working with Spring Boot +Ready to actually start using Spring Boot? <>. + +* *Build systems:* + <> | + <> | + <> | + <> +* *Best practices:* + <> | + <> | + <> | + <> +* *Running your code* + <> | + <> | + <> | + <> +* *Packaging your app:* + <> +* *Spring Boot CLI:* +<> + +== Learning about Spring Boot features +Need more details about Spring Boot's core features? +<>! + +* *Core Features:* + <> | + <> | + <> | + <> +* *Web Applications:* + <> | + <> +* *Working with data:* + <> | + <> +* *Testing:* + <> | + <> | + <> +* *Extending:* + <> | + <> + + +== Moving to production +When your ready to push your Spring Boot application to production, we've got +<>! + +* *Management endpoints:* +<> | +<> +* *Connection options:* +<> | +<> | +<> +* *Monitoring:* +<> | +<> | +<> + +== Advanced topics +Lastly, we have a few topics for the more advanced user. + +* *Build tool plugins:* +<> | +<> +* *Appendix:* +<> | +<> | +<> + + + + diff --git a/spring-boot-docs/src/main/asciidoc/getting-started.adoc b/spring-boot-docs/src/main/asciidoc/getting-started.adoc new file mode 100644 index 0000000000..f169dcf5a1 --- /dev/null +++ b/spring-boot-docs/src/main/asciidoc/getting-started.adoc @@ -0,0 +1,731 @@ +[[getting-started]] += Getting started + +[partintro] +-- +If your just getting started with Spring Boot, or 'Spring' in general, this is the section +for you! Here we answer the basic '``what?''', '``how?''' and '``why?''' questions. You'll +find a gentle introduction to Spring Boot along with installation instructions. +We'll then build our first Spring Boot application, discussing some core principles as +we go. +-- + + +[[getting-started-introducing-spring-boot]] +== Introducing Spring Boot +Spring Boot makes it easy to create stand-alone, production-grade Spring based +Applications that can you can ``just run''. We take an opinionated view of the Spring +platform and third-party libraries so you can get started with minimum fuss. Most Spring +Boot applications need very little Spring configuration. + +You can use Spring Boot to create Java applications that can be started using `java -jar` +or more traditional war deployments. We also provide a command line tool that runs +``spring scripts''. + +Our primary goals are: + +* Provide a radically faster and widely accessible getting started experience for all +Spring development. +* Be opinionated out of the box, but get out of the way quickly as requirements start to +diverge from the defaults. +* Provide a range of non-functional features that are common to large classes of projects +(e.g. embedded servers, security, metrics, health checks, externalized configuration). +* Absolutely no code generation and no requirement for XML configuration. + + + +[[getting-started-installing-spring-boot]] +== Installing Spring Boot +Spring Boot can be used with ``classic'' Java development tools or installed as a command +line tool. Regardless, you will need http://www.java.com[Java SDK v1.6] or higher. You +should check your current Java installation before you begin: + +[indent=0] +---- + $ java -version +---- + +If you are new to Java development, or if you just want to experiment with Spring Boot +you might want to try the <> first, +otherwise, read on for ``classic'' installation instructions. + +TIP: Although Spring Boot is compatible with Java 1.6, if possible, you should consider +using the latest version of Java. + +[[getting-started-installation-instructions-for-java]] +=== Installation instructions for the Java developer +You can use Spring Boot in the same way as any standard java library. Simply include the +appropriate `spring-boot-*.jar` files on your classpath. Spring Boot does not require +any special ``tools'' integration, so you can use any IDE or text editor; and there is +nothing special about a Spring Boot application, so you can run and debug as you would +any other Java program. + +Although you _could_ just copy Spring Boot jars, we generally recommend that you use a +build tool that supports dependency management (such as Maven or Gradle). + + + +[[getting-started-maven-installation]] +==== Maven installation +Spring Boot is compatible with Apache Maven 3.0 or above. If you don't already have Maven +installed you can follow the instructions at http://maven.apache.org. + +TIP: On many operating systems Maven can be installed via a package manager. If you're an +OSX Homebrew user try `brew install maven`. Ubuntu users can run +`sudo apt-get install maven`. + +Spring Boot dependencies use the `org.springframework.boot` `groupId`. Typically your +Maven POM file will inherit from the `spring-boot-starter-parent` project and declare +dependencies to one or more <>. Spring Boot also provides an optional +<> to create +executable jars. + +Here is a typical `pom.xml` file: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + 4.0.0 + + com.example + myproject + 0.0.1-SNAPSHOT + + + + org.springframework.boot + spring-boot-starter-parent + {spring-boot-version} + + + + + + org.springframework.boot + spring-boot-starter-web + + + + + + + + org.springframework.boot + spring-boot-maven-plugin + + + + +ifeval::["{spring-boot-repo}" != "release"] + + + + + spring-snapshots + http://repo.spring.io/snapshot + true + + + spring-milestones + http://repo.spring.io/milestone + + + + + spring-snapshots + http://repo.spring.io/snapshot + + + spring-milestones + http://repo.spring.io/milestone + + +endif::[] + +---- + + + +[[getting-started-gradle-installation]] +==== Gradle installation +Spring Boot is compatible with Gradle 1.6 or above. If you don't already have Gradle +installed you can follow the instructions at http://www.gradle.org/. + +Spring Boot dependencies can be declared using the `org.springframework.boot` `group`. +Typically your project will declare dependencies to one or more +<>. Spring Boot +provides a useful <> +that can be used to simplify dependency declarations and to create executable jars. + +.Gradle Wrapper +**** +The Gradle Wrapper provides a nice way of ``obtaining'' Gradle when you need to build a +project. It's a small script and library that you commit alongside your code to bootstrap +the build process. See http://www.gradle.org/docs/current/userguide/gradle_wrapper.html +for details. +**** + +Here is a typical `build.gradle` file: + +[source,groovy,indent=0,subs="verbatim,attributes"] +---- + buildscript { + repositories { + mavenCentral() +ifndef::release[] + maven { url "http://repo.spring.io/snapshot" } + maven { url "http://repo.spring.io/milestone" } +endif::release[] + } + dependencies { + classpath("org.springframework.boot:spring-boot-gradle-plugin:{spring-boot-version}") + } + } + + apply plugin: 'java' + apply plugin: 'spring-boot' + + jar { + baseName = 'myproject' + version = '0.0.1-SNAPSHOT' + } + + repositories { + mavenCentral() +ifndef::release[] + maven { url "http://repo.spring.io/snapshot" } + maven { url "http://repo.spring.io/milestone" } +endif::release[] + } + + dependencies { + compile("org.springframework.boot:spring-boot-starter-web") + testCompile("junit:junit") + } +---- + + + +[[getting-started-installing-the-cli]] +=== Installing the Spring Boot CLI +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 http://groovy.codehaus.org/[Groovy] scripts, +which means that you have a familiar Java-like syntax, without so much boilerplate code. + +You don't need to use the CLI to work with Spring Boot but it's definitely the quickest +way to get a Spring application off the ground. + + + +[[getting-started-manual-cli-installation]] +==== Manual installation +You can download the Spring CLI distribution from the Spring software repository: + +* http://repo.spring.io/{spring-boot-repo}/org/springframework/boot/spring-boot-cli/{spring-boot-version}/spring-boot-cli-{spring-boot-version}-bin.zip[spring-boot-cli-{spring-boot-version}-bin.zip] +* http://repo.spring.io/{spring-boot-repo}/org/springframework/boot/spring-boot-cli/{spring-boot-version}/spring-boot-cli-{spring-boot-version}-bin.tar.gz[spring-boot-cli-{spring-boot-version}-bin.tar.gz] + +Cutting edge http://repo.spring.io/snapshot/org/springframework/boot/spring-boot-cli/[snapshot distributions] +are also available. + +Once downloaded, follow the {github-raw}/spring-boot-cli/src/main/content/INSTALL.txt[INSTALL.txt] +instructions from the unpacked archive. In summary: there is a `spring` script +(`spring.bat` for Windows) in a `bin/` directory in the `.zip` file, or alternatively you +can use `java -jar` with the `.jar` file (the script helps you to be sure that the +classpath is set correctly). + + + +[[getting-started-gvm-cli-installation]] +==== Installation with GVM +GVM (the Groovy Environment Manager) can be used for managing multiple versions of +various Groovy and Java binary packages, including Groovy itself and the Spring Boot CLI. +Get `gvm` from http://gvmtool.net and install Spring Boot with + +[indent=0,subs="verbatim,quotes,attributes"] +---- + $ gvm install springboot + $ spring --version + Spring Boot v{spring-boot-version} +---- + +If you are developing features for the CLI and want easy access to the version you just +built, follow these extra instructions. + +[indent=0,subs="verbatim,quotes,attributes"] +---- + $ gvm install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-{spring-boot-version}-bin/spring-{spring-boot-version}/ + $ gvm use springboot dev + $ spring --version + Spring CLI v{spring-boot-version} +---- + +This will install a local instance of `spring` called the `dev` instance inside your gvm +repository. It points at your target build location, so every time you rebuild Spring +Boot, `spring` will be up-to-date. + +You can see it by doing this: + +[indent=0,subs="verbatim,quotes,attributes"] +---- + $ gvm ls springboot + + ================================================================================ + Available Springboot Versions + ================================================================================ + > + dev + * {spring-boot-version} + + ================================================================================ + + - local version + * - installed + > - currently in use + ================================================================================ +---- + + + +[[getting-started-homebrew-cli-installation]] +==== OSX Homebrew installation +If you are on a Mac and using http://brew.sh/[Homebrew], all you need to do to install +the Spring Boot CLI is: + +[indent=0] +---- + $ brew tap pivotal/tap + $ brew install springboot +---- + +Homebrew will install `spring` to `/usr/local/bin`. + +NOTE: If you don't see the formula, you're installation of brew might be out-of-date. +Just execute `brew update` and try again. + + + +[[getting-started-cli-command-line-completion]] +==== Command-line completion +Spring Boot CLI ships with scripts that provide command completion for +http://en.wikipedia.org/wiki/Bash_%28Unix_shell%29[BASH] and +http://en.wikipedia.org/wiki/Zsh[zsh] shells. You can `source` the script (also named +`spring`) in any shell, or put it in your personal or system-wide bash completion +initialization. On a Debian system the system-wide scripts are in `/etc/bash_completion.d` +and all scripts in that directory are executed when a new shell starts. To run the script +manually, e.g. if you have installed using `GVM` + +[indent=0] +---- + $ . ~/.gvm/springboot/current/bash_completion.d/spring + $ spring + grab help jar run test version +---- + +NOTE: If you install Spring Boot CLI using Homebrew, the command-line completion scripts +are automatically registered with your shell. + + + +[[getting-started-cli-example]] +==== Quick start Spring CLI example +Here's a really simple web application that you can use to test you installation. Create +a file called `app.groovy`: + +[source,groovy,indent=0,subs="verbatim,quotes,attributes"] +---- + @Controller + class ThisWillActuallyRun { + + @RequestMapping("/") + @ResponseBody + String home() { + return "Hello World!" + } + + } +---- + +Then simply run it from a shell: + +[indent=0] +---- + $ spring run app.groovy +---- + +NOTE: It will take some time when you first run the application as dependencies are +downloaded, subsequent runs will be much quicker. + +Open http://localhost:8080 in your favorite web browser and you should see the following +output: + +[indent=0] +---- + Hello World! +---- + + + +[[getting-started-first-application]] +== Developing your first Spring Boot application +Let's develop a simple ``Hello World!'' web application in Java that highlights some +of Spring Boot's key features. We'll use Maven to build this project since most IDEs +support it. + +TIP: The http://spring.io[spring.io] web site contains many ``Getting Started'' guides +that use Spring Boot. If you're looking to solve a specific problem; check there first. + +Before we begin, open a terminal to check that you have valid versions of Java and Maven +installed. + +[indent=0] +---- + $ java -version + java version "1.7.0_51" + Java(TM) SE Runtime Environment (build 1.7.0_51-b13) + Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode) +---- + +[indent=0] +---- + $ mvn -v + Apache Maven 3.1.1 (0728685237757ffbf44136acec0402957f723d9a; 2013-09-17 08:22:22-0700) + Maven home: /Users/user/tools/apache-maven-3.1.1 + Java version: 1.7.0_51, vendor: Oracle Corporation +---- + +NOTE: This sample needs to be created in its own folder. Subsequent instructions assume +that you have created a suitable folder and that it is your ``current directory''. + + + +[[getting-started-first-application-pom]] +=== Creating the POM +We need to start by creating a Maven `pom.xml` file. The `pom.xml` is the recipe that +will be used to build your project. Open you favorite text editor and add the following: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + 4.0.0 + + com.example + myproject + 0.0.1-SNAPSHOT + + + org.springframework.boot + spring-boot-starter-parent + {spring-boot-version} + + + + +ifeval::["{spring-boot-repo}" != "release"] + + + + spring-snapshots + http://repo.spring.io/snapshot + true + + + spring-milestones + http://repo.spring.io/milestone + + + + + spring-snapshots + http://repo.spring.io/snapshot + + + spring-milestones + http://repo.spring.io/milestone + + +endif::[] + +---- + +This should give you a working build, you can test it out by running `mvn package` (you +can ignore the '``jar will be empty - no content was marked for inclusion!''' warning for +now). + +NOTE: At this point you could import the project into an IDE (most modern Java IDE's +include built-in support for Maven). For simplicity, we will continue to use a plain +text editor for this example. + + + +[[getting-started-first-application-dependencies]] +=== Adding classpath dependencies +Spring Boot provides a number of ``Starter POMs'' that make easy to add jars to your +classpath. Our sample application has already used `spring-boot-starter-parent` in the +`parent` section of the POM. The `spring-boot-starter-parent` is a special starter +that provides useful Maven defaults. It also provides a `dependency-management` section +so that you can omit `version` tags for ``blessed'' dependencies. + +Other ``Starter POMs'' simply provide dependencies that you are likely to need when +developing a specific type of application. Since we are developing web application we will +add a `spring-boot-starter-web` dependency -- but before that, lets look at what we +currently have. + +[indent=0] +---- + $ mvn dependency:tree + + [INFO] com.example:myproject:jar:0.0.1-SNAPSHOT + [INFO] +- junit:junit:jar:4.11:test + [INFO] | \- org.hamcrest:hamcrest-core:jar:1.3:test + [INFO] +- org.mockito:mockito-core:jar:1.9.5:test + [INFO] | \- org.objenesis:objenesis:jar:1.0:test + [INFO] \- org.hamcrest:hamcrest-library:jar:1.3:test +---- + +The `mvn dependency:tree` command prints tree representation of your project dependencies. +You can see that `spring-boot-starter-parent` has already provides some useful test +dependencies. Lets edit our `pom.xml` and add the `spring-boot-starter-web` dependency +just below the `parent` section: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + org.springframework.boot + spring-boot-starter-web + + +---- + +If you run `mvn dependency:tree` again, you will see that there are now a number of +additional dependencies, including the Tomcat web server and Spring Boot itself. + + + +[[getting-started-first-application-code]] +=== Writing the code +To finish our application we need to create a single Java file. Maven will compile sources +from `src/main/java` so you need to create that folder structure, then add a file named +`src/main/java/Example.java`: + +[source,java,indent=0] +---- + import org.springframework.boot.*; + import org.springframework.boot.autoconfigure.*; + import org.springframework.stereotype.*; + import org.springframework.web.bind.annotation.*; + + @Controller + @EnableAutoConfiguration + public class Example { + + @RequestMapping("/") + @ResponseBody + String home() { + return "Hello World!"; + } + + public static void main(String[] args) throws Exception { + SpringApplication.run(Example.class, args); + } + + } +---- + +Although there isn't much code here, quite a lot is going on. Lets step though the +important parts. + + + +[[getting-started-first-application-annotations]] +==== The @Controller, @RequestMapping and @ResponseBody annotations +The first annotation on our `Example` class is `@Controller`. This is known as a +_stereotype_ annotation. It provides hints for people reading the code, and for Spring, +that the class plays a specific role. In this case, our class is a web `@Controller` so +Spring will consider it when handling incoming web requests. + +The `@RequestMapping` annotation provides ``routing'' information. It is telling Spring +that any HTTP request with the path "`/`" should be mapped to the `home` method. The +additional `@ResponseBody` annotation tells Spring to render the resulting string directly +back to the caller. + +TIP: The `@Controller`, `@RequestMapping` and `@ResponseBody` annotations are Spring MVC +annotations (they are not specific to Spring Boot). See the +<{spring-reference}/#mvc>[MVC section] in the Spring +Reference Documentation for more details. + + + +[[getting-started-first-application-auto-configuration]] +==== The @EnableAutoConfiguration annotation +The second class-level annotation is `@EnableAutoConfiguration`. This annotation tells +Spring Boot to ``guess'' how you will want to configure Spring, based on the jar +dependencies that you have added. Since `spring-boot-starter-web` added Tomcat and +Spring MVC, the auto-configuration will assume that you are developing a web application +and setup Spring accordingly. + +.Starter POMs and Auto-Configuration +**** +Auto-configuration is designed to work well with ``Starter POMs'', but the two concepts +are not directly tied. You are free to pick-and-choose jar dependencies outside of the +starter POMs and Spring Boot will still do its best to auto-configure your application. +**** + + + +[[getting-started-first-application-main-method]] +==== The ``main'' method +The final part of our application is the `main` method. This is just a standard method +that follows the Java convention for an application entry point. Our main method delegates +to Spring Boot's `SpringApplication` class by calling `run`. `SpringApplication` will +bootstrap our application, starting Spring which will in turn start the auto-configured +Tomcat web server. We need to pass `Example.class` as an argument to the `run` method to +tell `SpringApplication` which is the primary Spring component. The `args` array is also +passed though to expose any command-line arguments. + + + +[[getting-started-first-application-run]] +=== Running the example +At this point out application should work. Since we have used the +`spring-boot-starter-parent` POM we have a useful `run` goal that we can use to start +the application. Type `mvn spring-boot:run` from the root project directory to start the +application: + +[indent=0,subs="attributes"] +---- + $ mvn spring-boot:run + + . ____ _ __ _ _ + /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ + ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ + \\/ ___)| |_)| | | | | || (_| | ) ) ) ) + ' |____| .__|_| |_|_| |_\__, | / / / / + =========|_|==============|___/=/_/_/_/ + :: Spring Boot :: (v{spring-boot-version}) + ....... . . . + ....... . . . (log output here) + ....... . . . + ........ Started Example in 2.222 seconds (JVM running for 6.514) +---- + +If you open a web browser to http://localhost:8080 you should see the following output: + +[indent=0] +---- + Hello World! +---- + +To gracefully exit the application hit `ctrl-c`. + + + +[[getting-started-first-application-executable-jar]] +=== Creating an executable jar +Lets finish our example by creating a completely self-contained executable jar file that +we could run in production. Executable jars (sometimes called ``fat jars'') are archives +containing your compiled classes along with all of the jar dependencies that your code +needs to run. + +.Executable jars and Java +**** +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. + +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 <> and allows you to actually nest jars directly. +**** + +To create an executable jar we need to add the `spring-boot-maven-plugin` to our +`pom.xml`. Insert the following lines just below the `dependencies` section: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + org.springframework.boot + spring-boot-maven-plugin + + + +---- + +Save your `pom.xml` and run `mvn package` from the command line: + +[indent=0,subs="attributes"] +---- + $ mvn package + + [INFO] Scanning for projects... + [INFO] + [INFO] ------------------------------------------------------------------------ + [INFO] Building myproject 0.0.1-SNAPSHOT + [INFO] ------------------------------------------------------------------------ + [INFO] .... .. + [INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ myproject --- + [INFO] Building jar: /Users/developer/example/spring-boot-example/target/myproject-0.0.1-SNAPSHOT.jar + [INFO] + [INFO] --- spring-boot-maven-plugin:{spring-boot-version}:repackage (default) @ myproject --- + [INFO] ------------------------------------------------------------------------ + [INFO] BUILD SUCCESS + [INFO] ------------------------------------------------------------------------ +---- + +If you look in the `target` directory you should see `myproject-0.0.1-SNAPSHOT.jar`. The +file should be around 10 Mb in size. If you want to peek inside, you can use `jar tvf`: + +[indent=0] +---- + $ jar tvf target/myproject-0.0.1-SNAPSHOT.jar +---- + +You should also see a much smaller file named `myproject-0.0.1-SNAPSHOT.jar.original` +in the `target` directory. This is the original jar file that Maven created before it was +repackaged by Spring Boot. + +To run that application, use the `java -jar` command: + +[indent=0,subs="attributes"] +---- + $ java -jar target/myproject-0.0.1-SNAPSHOT.jar + + . ____ _ __ _ _ + /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ + ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ + \\/ ___)| |_)| | | | | || (_| | ) ) ) ) + ' |____| .__|_| |_|_| |_\__, | / / / / + =========|_|==============|___/=/_/_/_/ + :: Spring Boot :: (v{spring-boot-version}) + ....... . . . + ....... . . . (log output here) + ....... . . . + ........ Started Example in 3.236 seconds (JVM running for 3.764) +---- + +As before, to gracefully exit the application hit `ctrl-c`. + + + +[[getting-started-whats-next]] +== What to read next +Hopefully this section has provided you with some of the Spring Boot basics, and got you +on your way to writing your own applications. If your a ``task oriented'' type of +developer you might want to jump over to http://spring.io and check out some of the +http://spring.io/guides/[getting started] guides that solve specific +'``How do I do that with Spring''' problems; we also have a Spring Boot specific +``<>'' reference documentation. + +Otherwise, the next logical step is to read the ``<>'' +section. If you're really impatient, you could also jump ahead and read about +``<>''. diff --git a/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-docs/src/main/asciidoc/howto.adoc new file mode 100644 index 0000000000..81ac197393 --- /dev/null +++ b/spring-boot-docs/src/main/asciidoc/howto.adoc @@ -0,0 +1,17 @@ +[[howto]] += ``How-to'' guides + +[partintro] +-- +This section provides answers to some common '``how do I do that...''' type of questions +that often arise when using Spring Boot. This is by no means an exhaustive list, but it +does cover quite a lot. + +If you are having a specific problem that we don't cover here, you might want to check out +http://stackoverflow.com/tags/spring-boot[stackoverflow.com] to see if someone has +already provided an answer; this is also a great place to ask new questions (please use +the `spring-boot` tag). + +We're also more than happy to extend this section; If you want to add a ``how-to'' you +can send us a {github-code}[pull request]. +-- diff --git a/spring-boot-docs/src/main/asciidoc/index.adoc b/spring-boot-docs/src/main/asciidoc/index.adoc index 82f12e5539..607b2dd214 100644 --- a/spring-boot-docs/src/main/asciidoc/index.adoc +++ b/spring-boot-docs/src/main/asciidoc/index.adoc @@ -28,7 +28,14 @@ Phillip Webb; Dave Syer; :spring-data-mongo-javadoc: http://docs.spring.io/spring-data/mongodb/docs/current/api/org/springframework/data/mongodb // ====================================================================================== -= Spring Boot -== Reference Documentation +include::documentation-overview.adoc[] +include::getting-started.adoc[] +include::using-spring-boot.adoc[] +include::spring-boot-features.adoc[] +include::production-ready-features.adoc[] +include::spring-boot-cli.adoc[] +include::build-tool-plugins.adoc[] +include::howto.adoc[] +include::appendix.adoc[] // ====================================================================================== diff --git a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc new file mode 100644 index 0000000000..57545d6ea4 --- /dev/null +++ b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc @@ -0,0 +1,747 @@ +[[production-ready]] += Production-ready features + +[partintro] +-- +Spring Boot includes a number of additional features to help you monitor and manage your +application when it's pushed to production. You can choose to manage and monitor your +application using HTTP endpoints, with JMX or even by remote shell (SSH or Telnet). +Auditing, health and metrics gathering can be automatically applied to your application. +-- + + + +[[production-ready-enabling]] +== Enabling production-ready features. +The `spring-boot-actuator` project provides all of Spring Boot's production-ready +features. The simplist way to enable the features is to add a dependency to the +`spring-boot-starter-actuator` ``Starter POM''. + +.Definition of Actuator +**** +An actuator is a manufacturing term, referring to a mechanical device for moving or +controlling something. Actuators can generate a large amount of motion from a small +change. +**** + +To add the actuator to a Maven based project, add the following ``starter'' +dependency: + +[source,xml,indent=0] +---- + + + org.springframework.boot + spring-boot-starter-actuator + + +---- + +For Gradle, use the declaration: + +[source,groovy,indent=0] +---- + dependencies { + compile("org.springframework.boot:spring-boot-starter-actuator") + } +---- + + + +[[production-ready-endpoints]] +== Endpoints +Actuator endpoints allow you to monitor and interact with your application. Spring Boot +includes a number of built-in endpoints and you can also add your own. For example the +`health` endpoint provides basic application health information. + +The way that enpoints are exposed will depend on the type of technology that you choose. +Most applications choose HTTP monitoring, where the ID of the endpoint is mapped +to a URL. For example, by default, the `health` endpoint will be mapped to `/health`. + +The following endpoints are available: + +[cols="2,5,1"] +|=== +| ID | Description | Sensitive + +|`autoconfig` +|Displays an auto-configuration report showing all auto-configuration candidates and the + reason why they ``were'' or ``were not'' applied. +|true + +|`beans` +|Displays a complete list of all the Spring Beans in your application. +|true + +|`configprops` +|Displays a collated list of all `@ConfigurationProperties`. +|true + +|`dump` +|Performs a thread dump. +|true + +|`env` +|Exposes properties from Spring's `ConfigurableEnvironment`. +|true + +|`health` +|Shows application health information (defaulting to a simple ``OK'' message). +|false + +|`info` +|Displays arbitrary application info. +|false + +|`metrics` +|Shows ``metrics'' information for the current application. +|true + +|`mappings` +|Displays a collated list of all `@RequestMapping` paths. +|true + +|`shutdown` +|Allows the application to be gracefully shutdown (not enabled by default). +|true + +|`trace` +|Displays trace information (by default the last few HTTP requests). +|true +|=== + +NOTE: Depending on how an endpoint is exposed, the `sensitive` parameter may be used as +a security hint. For example, sensitive endpoints will require a username/password when +they are accessed over HTTP (or simply disabled if web security is not enabled). + + + +[[production-ready-customizing-endpoints]] +=== Customizing endpoints +Endpoints can be customized using Spring properties. You can change if an endpoint is +`enabled`, if it is considered `sensitive` and even its `id`. + +For example, here is an `application.properties` that changes the sensitivity and id +of the `beans` endpoint and also enables `shutdown`. + +[indent=0] +---- + endpoints.beans.id=springbeans + endpoints.beans.sensitive=false + endpoints.shutdown.enabled=true +---- + +NOTE: The prefix "`endpoints` + `.` + `name`" is used to uniquely identify the endpoint +that is being configured. + + + +[[production-ready-health]] +=== Custom health information +The default information exposed by the `health` endpoint is a simple ``OK'' message. It +is often useful to perform some additional health checks, for example you might check +that a database connection works, or that a remote REST endpoint is functioning. + +To provide custom health information you can register a Spring bean that implements the +{sc-spring-boot-actuator}/health/HealthIndicator.{sc-ext}[`HealthIndicator`] interface. + +[source,java,indent=0] +---- + import org.springframework.boot.actuate.health.HealthIndicator; + import org.springframework.stereotype.Component; + + @Component + public class MyHealth implements HealthIndicator { + + @Override + public String health() { + // perform some specific health check + return ... + } + + } +---- + +Spring Boot also provides a +{sc-spring-boot-actuator}/health/SimpleHealthIndicator/{sc-ext}[`SimpleHealthIndicator`] +implementation that attempts a simple database test. + + + +[[production-ready-application-info]] +=== Custom application info information +You can customize the data exposed by the `info` endpoint by settings `info.*` Spring +properties. All `Environment` properties under the info key will be automatically +exposed. For example, you could add the following to your `application.properties`: + +[indent=0] +---- + info.app.name: MyService + info.app.description: My awesome service + info.app.version: 1.0.0 +---- + +If you are using Maven, you can automatically expand info properties from the Maven +project using resource filtering. In your `pom.xml` you have (inside the `` +element): + +[source,xml,indent=0] +---- + + + src/main/resources + true + + +---- + +You can then refer to your Maven ``project properties'' via placeholders, e.g. + +[indent=0] +---- + project.artifactId: myproject + project.name: Demo + project.version: X.X.X.X + project.description: Demo project for info endpoint + info.build.artifact: ${project.artifactId} + info.build.name: ${project.name} + info.build.description: ${project.description} + info.build.version: ${project.version} +---- + +NOTE: In the above example we used `project.*` to set some values to be used as +fallbacks if the Maven resource filtering has not been switched on for some reason. + + + +[[production-ready-git-commit-information]] +==== Git commit information +Another useful feature of the `info` endpoint is its ability to publish information +about the state of your `git` source code repository when the project was built. If a +`git.properties` file is contained in your jar the `git.branch` and `git.commit` +properties will be loaded. + +For Maven users the `spring-boot-starter-parent` POM includes a pre-configured plugin to +generate a `git.properties` file. Simply add the following declaration to your POM: + +[source,xml,indent=0] +---- + + + + pl.project13.maven + git-commit-id-plugin + + + +---- + +A similar https://github.com/ajoberstar/gradle-git[`gradle-git`] plugin is also available +for Gradle users, although a little more work is required to generate the properties file. + + + +[[production-ready-monitoring]] +== Monitoring and management over HTTP +If you are developing a Spring MVC application, Spring Boot Actuator will auto-configure +all non-sensitive endpoints to be exposed over HTTP. The default convention it to use the +`id` of the endpoint as the URL path. For example, `health` is exposed as `/health`. + + + +[[production-ready-sensitive-endpoints]] +=== Exposing sensitive endpoints +If you use ``Spring Security'' sensitive endpoints will also be exposed over HTTP. By +default ``basic'' authentication will be used with the username `user` and a generated +password. + +TIP: Generated passwords are logged as the application starts. Search for ``Using default +password for application endpoints''. + +You can use Spring properties to change the username and passsword and to change the +security role required to access the endpoints. For example, you might set the following +in your `application.properties`: + +[indent=0] +---- + security.user.name=admin + security.user.password=secret + management.security.role=SUPERUSER +---- + + + +[[production-ready-customizing-management-server-context-path]] +=== Customizing the management server context path +Sometimes it is useful to group all management endpoints under a single path. For example, +your application might already use `/info` for another purpose. You can use the +`management.contextPath` property to set a prefix for your manangement endpoint: + +[indent=0] +---- + management.contextpath=/manage +---- + +The `application.properties` example above will change the endpoint from `/{id}` to +`/manage/{id}` (e.g. `/manage/info`). + + + +[[production-ready-customizing-management-server-port]] +=== Customizing the management server port +Exposing management endpoints using the default HTTP port is a sensible choice for cloud +based deployments. If, however, your application runs inside your own data center you +may prefer to expose endpoints using a different HTTP port. + +The `management.port` property can be used to change the HTTP port. Since your management +port is often protected by a firewall, and not exposed to the public, you might also +want to disable management security: + +[indent=0] +---- + management.port=8081 + management.security.enabled=false +---- + + + +[[production-ready-customizing-management-server-address]] +=== Customizing the management server address +You can customize the address that the management endpoints are available on by +setting the `management.security.address` property. This can be useful if you want to +listen only on an internal or ops-facing network, or to only listen for connections from +`localhost`. + +NOTE: You can only listen on a different address if the port is different to the +main server port. + +Here is an example `application.properties` that will not allow remote management +connections: + +[indent=0] +---- + management.port=8081 + management.address=127.0.0.1 +---- + + + +[[production-ready-disabling-http-endpoints]] +=== Disabling HTTP endpoints +If you don't want to expose endpoints over HTTP you can set the management port to `-1`: + +[indent=0] +---- + management.port=-1 +---- + + + +[[production-ready-jmx]] +== Monitoring and management over JMX +Java Management Extensions (JMX) provide a standard mechanism to monitor and manage +applications. By default Spring Boot will expose management endpoints as JMX MBeans +under the `org.springframework.boot` domain. + + + +[[production-ready-custom-mbean-names]] +=== Customizing MBean names +The name of the MBean is usually generated from the `id` of the endpoint. For example +the `health` endpoint is exposed as `org.springframework.boot/Endpoint/HealthEndpoint`. + +If your application contains more than one Spring `ApplicationContext` you may find that +names clash. To solve this problem you can set the `endpoints.jmx.uniqueNames` property +to `true` so that MBean names are always unique. + +You can also customize the JMX domain under which endpoints are exposed. Here is an +example `application.properties`: + +[indent=0] +---- + endpoints.jmx.domain=myapp + endpoints.jmx.uniqueNames=true +---- + + + +[[production-ready-disable-jmx-endpoints]] +=== Disabling JMX endpoints +If you don't want to expose endpoints over JMX you can set the `spring.jmx.enabled` +property to `false`: + +[indent=0] +---- + spring.jmx.enabled=false +---- + + + +[[production-ready-jolokia]] +=== Using Jolokia for JMX over HTTP +Jolokia is a JMX-HTTP bridge giving an alternative method of accessing JMX beans. To +use Jolokia, simply include a dependency to `org.jolokia:jolokia-core`. For example, +using Maven you you add the following: + +[source,xml,indent=0] +---- + + org.jolokia + jolokia-core + +---- + +Jolokia can then be accessed using `/jolokia` on your management HTTP server. + + + +[[production-ready-customizing-jolokia]] +==== Customizing Jolokia +Jolokia has a number of settings that you would traditionally configure using servlet +parameters. With Spring Boot you can use your `application.properties`, simply prefix the +parameter with `jolokia.config.`: + +[indent=0] +---- + jolokia.config.debug=true +---- + + + +[[production-ready-disabling-jolokia]] +==== Disabling Jolokia +If you are using Jolokia but you don't want Spring Boot to configure it, simply set the +`endpoints.jolokia.enabled` property to `false`: + +[indent=0] +---- + jolokia.config.enabled=false +---- + + + +[[production-ready-remote-shell]] +== Monitoring and management using a remote shell +Spring Boot supports an integrated Java shell called ``CRaSH''. You can use CRaSH to +`ssh` or `telnet` into your running application. To enable remote shell support add a +dependency to `spring-boot-starter-shell-remote`: + +[source,xml,indent=0] +---- + + org.springframework.boot + spring-boot-starter-shell-remote + +---- + +TIP: If you want to also enable telnet access your will additionally need a dependency +on `org.crsh:crsh.shell.telnet`. + + + +[[production-ready-connecting-to-the-remote-shell]] +=== Connecting to the remote shell +By default the remote shell will listen for connections on port `2000`. The default user +is `user` and the default password will be randomly generated and displayed in the log +output, you should see a message like this: + +[indent=0] +---- + Using default password for shell access: ec03e16c-4cf4-49ee-b745-7c8255c1dd7e +---- + +Linux and OSX users can use `ssh` to connect to the remote shell, Windows users can +download and install http://www.putty.org/[PuTTY]. + +[indent=0,subs="attributes"] +---- + $ ssh -p 2000 user@localhost + + user@localhost's password: + . ____ _ __ _ _ + /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ + ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ + \\/ ___)| |_)| | | | | || (_| | ) ) ) ) + ' |____| .__|_| |_|_| |_\__, | / / / / + =========|_|==============|___/=/_/_/_/ + :: Spring Boot :: (v{spring-boot-version}) on myhost +---- + +Type `help` for a list of commands. Spring boot provides `metrics`, `beans` and +`autoconfig` commands. You can also use the `jmx` command to query endpoint data: + +[indent=0] +---- + jmx find -p org.springframework.boot:type=Endpoint,name=healthEndpoint | jmx get Data +---- + + + +[[production-ready-remote-shell-credentials]] +==== Remote shell credentials +You can use the `shell.auth.simple.username` and `shell.auth.simple.password` properties +to configure custom connection credentials. It is also possible to use a +``Spring Security'' `AuthenticationManager` to handle login duties. See the +{dc-spring-boot-actuator}/autoconfigure/CrshAutoConfiguration.{dc-ext}[`CrshAutoConfiguration`] +and {dc-spring-boot-actuator}/autoconfigure/ShellProperties.{dc-ext}[`ShellProperties`] +Javadoc for full details. + + + +[[production-ready-extending-the-remote-shell]] +=== Extending the remote shell +The remote shell can be extended in a number of interesting ways. + + + +[[production-ready-remote-commands]] +==== Remote shell commands +You can write additional shell commands using Groovy or Java (see the CRaSH documentation +for details). By default Spring Boot will search for commands in the following locations: + +* `classpath*:/commands/**` +* `classpath*:/crash/commands/**` + +TIP: You can change the search path by settings a `shell.commandpathpatterns` property. + +Here is a simple ``hello world'' command that could be loaded from +`src/main/resources/commands/Hello.groovy` + +[source,groovy,indent=0] +---- + package commands + + import org.springframework.boot.actuate.endpoint.BeansEndpoint + + class hello { + + @Usage("Say Hello") + @Command + def main(InvocationContext context) { + return "Hello" + } + + } +---- + +Spring Boot adds some additional attributes to `InvocationContext` that you can access +from your command: + +[cols="2,3"] +|=== +| Attribute Name | Description + +|`spring.boot.version` +|The version of Spring Boot + +|`spring.version` +|The version of the core Spring Framework + +|`spring.beanFactory` +|Access to the Spring `BeanFactory` +|=== + + + +[[production-ready-remote-shell-plugins]] +==== Remote shell plugins +In addition to new commands, it is also possible to extend other CRaSH shell features. +All Spring Beans that extends `org.crsh.plugin.CRaSHPlugin` will be automatically +registered with the shell. + +For more information please refer to the http://www.crashub.org/[CRaSH reference +documentation]. + + + +[[production-ready-metrics]] +== Metrics +Spring Boot Actuator includes a metrics service with ``gauge'' and ``counter'' support. +A ``gauge'' records a single value; and a ``counter'' records a delta (an increment or +decrement). Metrics for all HTTP requests are automatically recorded, so if you hit the +`metrics` endpoint should should see a response similar to this: + +[source,json,indent=0] +---- + { + "counter.status.200.root": 20, + "counter.status.200.metrics": 3, + "counter.status.401.root": 4, + "gauge.response.root": 2, + "gauge.response.metrics": 3, + "mem": 466944, + "mem.free": 410117, + "processors": 8 + } +---- + +Here we can see basic `memory` and `processor` information along with some HTTP metrics. +In this instance the `root` (``/'') and `/metrics` URLs have returned `HTTP 200` responses +`20` and `3` times respectively. It also appears that the `root` URL returned `HTTP 401` +(unauthorized) `4` times. + +The `gauge` shows the last response time for a request. So the last request to `root` took +`2ms` to respond and the last to `/metrics` took `3ms`. + +NOTE: In this example we are actually accessing the endpoint over HTTP using the +`/metrics` URL, this explains why `metrics` appears in the response. + + + +[[production-ready-recording-metrics]] +=== Recording your own metrics +To record your own metrics inject a +{sc-spring-boot-actuator}/metrics/CounterService.{sc-ext}[`CounterService`] and/or +{sc-spring-boot-actuator}/metrics/GaugeService.{sc-ext}[`GaugeService`] into +your bean. The `CounterService` exposes `increment`, `decrement` and `reset` methods; the +`GaugeService` provides a `submit` method. + +Here is a simple example that counts the number of times that a method is invoked: + +[source,java,indent=0] +---- + import org.springframework.beans.factory.annotation.Autowired; + import org.springframework.boot.actuate.metrics.CounterService; + import org.springframework.stereotype.Service; + + @Service + public class MyService { + + private final CounterService counterService; + + @Autowired + public MyService(CounterService counterService) { + this.counterService = counterService; + } + + public void exampleMethod() { + this.counterService.increment("services.system.myservice.invoked"); + } + + } +---- + +TIP: You can use any string as a metric name but you following guidelines of your chosen +store/graphing technology. Some good guidelines for Graphite are available on +http://matt.aimonetti.net/posts/2013/06/26/practical-guide-to-graphite-monitoring/[Matt Aimonetti's Blog]. + + + +[[production-ready-metric-repositories]] +=== Metric repositories +Metric service implementations are usually bound to a +{sc-spring-boot-actuator}/metrics/repository/MetricRepository.{sc-ext}[`MetricRepository`]. +A `MetricRepository` is responsible for storing and retrieving metric information. Spring +Boot provides an `InMemoryMessageRespository` and a `RedisMetricRepository` out of the +box (the in-memory repository is the default) but you can also write your own. The +`MetricRepository` interface is actually composed of higher level `MetricReader` and +`MetricWriter` interfaces. For full details refer to the +{dc-spring-boot-actuator}/metrics/repository/MetricRepository.{dc-ext}[Javadoc]. + + + +[[production-ready-code-hale-metrics]] +=== Coda Hale Metrics +User of the http://metrics.codahale.com/[Coda Hale ``Metrics'' library] will automatically +find that Spring Boot metrics are published to `com.codahale.metrics.MetricRegistry`. A +default `com.codahale.metrics.MetricRegistry` Spring bean will be created when you declare +a dependency to the `com.codahale.metrics:metrics-core` library; you can also register you +own `@Bean` instance if you need customizations. + +Users can create Coda Hale metrics by prefixing their metric names with the appropriate +type (e.g. `histogram.*`, `meter.*`). + + + +[[production-ready-metrics-message-channel-integration]] +=== Message channel integration +If the ``Spring Messaging'' jar is on your classpath a `MessageChannel` called +`metricsChannel` is automatically created (unless one already exists). All metric update +events are additionally published as ``messages'' on that channel. Additional analysis or +actions can be taken by clients subscribing to that channel. + + + +[[production-ready-auditing]] +== Auditing +Spring Boot Actuator has a flexible audit framework that will publish events once Spring +Security is in play (``authentication success'', ``failure'' and ``access denied'' +exceptions by default). This can be very useful for reporting, and also to implement a +lock-out policy based on authentication failures. + +You can also choose to use the audit services for your own business events. To do that +you can either inject the existing `AuditEventRepository` into your own components and +use that directly, or you can simply publish `AuditApplicationEvent` via the Spring +`ApplicationEventPublisher` (using `ApplicationEventPublisherAware`). + + + +[[production-ready-tracing]] +== Tracing +Tracing is automatically enable for all HTTP requests. You can view the `trace` endpoint +and obtain basic information about the last few requests: + +[source,json,indent=0] +---- + [{ + "timestamp": 1394343677415, + "info": { + "method": "GET", + "path": "/trace", + "headers": { + "request": { + "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", + "Connection": "keep-alive", + "Accept-Encoding": "gzip, deflate", + "User-Agent": "Mozilla/5.0 Gecko/Firefox", + "Accept-Language": "en-US,en;q=0.5", + "Cookie": "_ga=GA1.1.827067509.1390890128; ..." + "Authorization": "Basic ...", + "Host": "localhost:8080" + }, + "response": { + "Strict-Transport-Security": "max-age=31536000 ; includeSubDomains", + "X-Application-Context": "application:8080", + "Content-Type": "application/json;charset=UTF-8", + "status": "200" + } + } + } + },{ + "timestamp": 1394343684465, + ... + }] +---- + + + +[[production-ready-custom-tracing]] +=== Custom tracing +If you need to trace additional events you can inject a +{sc-spring-boot-actuator}/trace/TraceRepository.{sc-ext}[`TraceRepository`] into your +Spring Beans. The `add` method accepts a single `Map` structure that will be converted to +JSON and logged. + +By default an `InMemoryTraceRepository` will be used that stores the last 100 events. You +can define your own instance of the `InMemoryTraceRepository` bean if you need to expand +the capacity. You can also create your own alternative `TraceRepository` implementation +if needed. + + + +[[production-ready-error-handling]] +== Error Handling +Spring Boot Actuator provides an `/error` mapping by default that handles all errors in a +sensible way. If you want more specific error pages for some conditions, the embedded +servlet containers support a uniform Java DSL for customizing the error handling. + + + +[[production-ready-whats-next]] +== What to read next +If you want to explore some of the concepts discussed in this chapter, you can take a +look at the actuator {github-code}/spring-boot-samples[sample applications]. You also +might want to read about graphing tools such as http://graphite.wikidot.com/[Graphite]. + +Otherwise, you can continue on, to read about Spring Boot's +<>. diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc new file mode 100644 index 0000000000..affd73db8e --- /dev/null +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc @@ -0,0 +1,323 @@ +[[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 +``<>'' +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] + [] + + Available commands are: + + run [options] [--] [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] [--] [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 +``<>'' that you can +use with Gradle or Maven. diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc new file mode 100644 index 0000000000..5dfc7790d5 --- /dev/null +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -0,0 +1,1611 @@ +[[boot-features]] += Spring Boot features + +[partintro] +-- +This section dives into the details of Spring Boot. Here you can learn about the key +features that you will want to use and customize. If you haven't already, you might want +to read the ``<>'' and +``<>'' sections so that you have a good grounding +of the basics. +-- + + + +[[boot-features-spring-application]] +== SpringApplication +The `SpringApplication` class provides a convenient way to bootstrap a Spring application +that will be started from a `main()` method. In many situations you can just delegate to +the static `SpringApplication.run` method: + +[source,java,indent=0] +---- + public static void main(String[] args) { + SpringApplication.run(MySpringConfiguration.class, args); + } +---- + +When you application starts you should see something similar to the following: + +[indent=0,subs="attributes"] +---- + . ____ _ __ _ _ + /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ +( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ + \\/ ___)| |_)| | | | | || (_| | ) ) ) ) + ' |____| .__|_| |_|_| |_\__, | / / / / + =========|_|==============|___/=/_/_/_/ + :: Spring Boot :: v{spring-boot-version} + +2013-07-31 00:08:16.117 INFO 56603 --- [ main] o.s.b.s.app.SampleApplication : Starting SampleApplication v0.1.0 on mycomputer with PID 56603 (/apps/myapp.jar started by pwebb) +2013-07-31 00:08:16.166 INFO 56603 --- [ main] ationConfigEmbeddedWebApplicationContext : Refreshing org.springframework.boot.context.embedded.AnnotationConfigEmbeddedWebApplicationContext@6e5a8246: startup date [Wed Jul 31 00:08:16 PDT 2013]; root of context hierarchy +2014-03-04 13:09:54.912 INFO 41370 --- [ main] .t.TomcatEmbeddedServletContainerFactory : Server initialized with port: 8080 +2014-03-04 13:09:56.501 INFO 41370 --- [ main] o.s.b.s.app.SampleApplication : Started SampleApplication in 2.992 seconds (JVM running for 3.658) +---- + +By default `INFO` logging messages will shown, including some relevant startup details +such as the user that launched the application. + + + +[[boot-features-customizing-spring-application]] +=== Customizing SpringApplication +If the `SpringApplication` defaults aren't to your taste you can instead create a local +instance and customize it. For example, to turn off the banner you would write: + +[source,java,indent=0] +---- + public static void main(String[] args) { + SpringApplication app = new SpringApplication(MySpringConfiguration.class); + app.setShowBanner(false); + app.run(args); + } +---- + +NOTE: The constructor arguments passed to `SpringApplication` are configuration sources +for spring beans. In most cases these will be references to `@Configuration` classes, but +they could also be references to XML configuration or to packages that should be scanned. + +It is also possible to configure the `SpringApplication` using an `application.properties` +file. See ``<>'' for details. + +For a complete list of the configuration options, see the +{dc-spring-boot}/SpringApplication.{dc-ext}[`SpringApplication` Javadoc]. + + + +[[boot-features-fluent-builder-api]] +=== Fluent builder API +If you need to build an `ApplicationContext` hierarchy (multiple contexts with a +parent/child relationship), or if you just prefer using a ``fluent'' builder API, you +can use the `SpringApplicationBuilder`. + +The `SpringApplicationBuilder` allows you to chain together multiple method calls, and +includes `parent` and `child` methods that allow you to create a hierarchy. + +For example: +[source,java,indent=0] +---- + new SpringApplicationBuilder() + .showBanner(false) + .sources(Parent.class) + .child(Application.class) + .run(args); +---- + +NOTE: There are some restrictions when creating an `ApplicationContext` hierarchy, e.g. +the parent application context is *not* a `WebApplicationContext`. Both parent and child +are executed with the same `Environment` constructed in the usual way to include command +line arguments. Any `ServletContextAware` components all have to go in the child +context, otherwise there is no way for Spring Boot to create the `ServletContext` in time. + + + +[[boot-features-application-events-and-listeners]] +=== Application events and listeners +In addition to the usual Spring Framework events, such as `ContextRefreshedEvent`, a +`SpringApplication` sends some additional application events. Some events are actually +triggered before the `ApplicationContext` is created. + +You can register event listeners in a number of ways, the most common being +`SpringApplication.addListeners(...)` method. + +Application events are sent in the following order, as your application runs: + +. An `ApplicationStartedEvent` is sent at the start of a run, but before any + processing except the registration of listeners and initializers. +. An `ApplicationEnvironmentPreparedEvent` is sent when the `Environment` to be used in + the context is known, but before the context is created. +. An `ApplicationPreparedEvent` is sent just before the refresh is started, but after bean + definitions have been loaded. +. An `ApplicationFailedEvent` is sent if there is an exception on startup. + +TIP: You often won't need to use application events, but it can be handy to know that they +exist. Internally, Spring Boot uses events to handle a variety of tasks. + + + +[[boot-features-web-environment]] +=== Web environment +A `SpringApplication` will attempt to create the right type of `ApplicationContext` on +your behalf. By default, an `AnnotationConfigApplicationContext` or +`AnnotationConfigEmbeddedWebApplicationContext` will be used, depending on whether you +are developing a web application or not. + +The algorithm used to determine a ``web environment'' is fairly simplistic (based on the +presence of a few classes). You can use `setWebEnvironment(boolean webEnvironment)` if +you need to override the default. + +It is also possible to take complete control of the `ApplicationContext` type that will +be used by calling `setApplicationContextClass(...)`. + +TIP: It is often desirable call `setWebEnvironment(false)` when using `SpringApplication` +within a JUnit test. + + + +[[boot-features-command-line-runner]] +=== Using the CommandLineRunner +If you want access to the raw command line arguments, or you need to run some specific code +once the `SpringApplication` has started you can implement the `CommandLineRunner` +interface. The `run(String... args)` method will be called on all spring beans +implementing this interface. + +[source,java,indent=0] +---- + import org.springframework.boot.* + import org.springframework.stereotype.* + + @Component + public class MyBean implements CommandLineRunner { + + public void run(String... args) { + // Do something... + } + + } +---- + +You can additionally implement the `org.springframework.core.Ordered` interface or use the +`org.springframework.core.annotation.Order` annotation if several `CommandLineRunner` +beans are defined that must be called in a specific order. + + + +[[boot-features-application-exit]] +=== Application exit +Each `SpringApplication` will register a shutdown hook with the JVM to ensure that the +`ApplicationContext` is closed gracefully on exit. All the standard Spring lifecycle +callbacks (such as the `DisposableBean` interface, or the `@PreDestroy` annotation) can +be used. + +In addition, beans may implement the `org.springframework.boot.ExitCodeGenerator` +interface if they wish to return a specific exit code when the application ends. + + + +[[boot-features-external-config]] +== Externalized Configuration +Spring Boot likes you to externalize your configuration so you can work with the same +application code in different environments. You can use properties files, YAML files, +environment variables and command-line arguments to externalize configuration. Property +values can be injected directly into your beans using the `@Value` annotation, accessed +via Spring's `Environment` abstraction or bound to structured objects. + +Spring Boot uses a very particular `PropertySource` order that is designed to allow +sensible overriding of values, properties are considered in the the following order: + +. Command line arguments. +. Java System properties (`System.getProperties()`). +. OS environment variables. +. `@PropertySource` annotations on your `@Configuration` classes. +. Application properties outside of your packaged jar (`application.properties` + including YAML and profile variants). +. Application properties packaged inside your jar (`application.properties` + including YAML and profile variants). +. Default properties (specified using `SpringApplication.setDefaultProperties`). + +To provide a concrete example, suppose you develop a `@Component` that uses a +`name` property: + +[source,java,indent=0] +---- + import org.springframework.stereotype.* + import org.springframework.beans.factory.annotation.* + + @Component + public class MyBean { + + @Value("${name}") + private String name; + + // ... + + } +---- + +You can bundle an `application.properties` inside your jar that provides a sensible +default `name`. When running in production, an `application.properties` can be provided +outside of your jar that overrides `name`; and for one off testing, you can launch with +a specific command line switch (e.g. `java -jar app.jar --name="Spring"`). + + + +[[boot-features-external-config-command-line-args]] +=== Accessing command line properties +By default SpringApplication will convert any command line option arguments (starting +with ``--'', e.g. `--server.port=9000`) to a `property` and add it to the Spring +`Environment`. As mentioned above, command line properties always take precedence over +other property sources. + +If you don't want command line properties to be added to the `Environment` you can disable +them using `SpringApplication.setAddCommandLineProperties(false)`. + + + +[[boot-features-external-config-application-property-files]] +=== Application property files +`SpringApplication` will load properties from `application.properties` files in the +following locations and add them to the Spring `Environment`: + +. The current directory +. A `/config` subdir of the current directory. +. The classpath root +. A classpath `/config` package + +The list is ordered by precedence (locations higher in the list override lower items). + +NOTE: You can also use YAML ('.yml') files as an alternative to '.properties' (see below) + +If you don't like `application.properties` as the configuration file name you can switch +to another by specifying a `spring.config.name` environment property. You can also refer +to an explicit location using the `spring.config.location` environment property. + +[indent=0] +---- + $ java -jar myproject.jar --spring.config.name=myproject +---- + + + +[[boot-features-external-config-profile-specific-properties]] +=== Profile specific properties +In addition to `application.properties` files, profile specific properties can also be +defined using the naming convention `application-{profile}.properties`. + +Profile specific properties are loaded from the same locations as standard +`application.properties`, with profiles specific files overriding the default ones. + + + +[[boot-features-external-config-placeholders-in-properties]] +=== Placeholders in properties +The values in `application.properties` are filtered through the existing `Environment` +when they are used so you can refer back to previously defined values (e.g. from System +properties). + +[indent=0] +---- + app.name: MyApp + app.description: ${app.name} is a Spring Boot application +---- + +TIP: You can also use this technique to create ``short'' variants of existing Spring Boot +properties. + + + +[[boot-features-external-config-yaml]] +=== Using YAML instead of Properties +http://yaml.org[YAML] is a superset of JSON, and as such is a very convenient format +for specifying hierarchical configuration data. The `SpringApplication` class will +automatically support YAML as an alternative to properties whenever you have the +http://code.google.com/p/snakeyaml/[SnakeYAML] library on your classpath. + +NOTE: If you use ``starter POMs'' SnakeYAML will be automatically provided via +`spring-boot-starter`. + + + +[[boot-features-external-config-loading-yaml]] +==== Loading YAML +Spring Boot provides two convenient classes that can be used to load YAML documents. The +`YamlPropertiesFactoryBean` will load YAML as `Properties` and the `YamlMapFactoryBean` +will load YAML as a `Map`. + +For example, the following YAML document: + +[source,yaml,indent=0] +---- + dev: + url: http://dev.bar.com + name: Developer Setup + prod: + url: http://foo.bar.com + name: My Cool App +---- + +Would be transformed into these properties: + +[indent=0] +---- + environments.dev.url=http://dev.bar.com + environments.dev.name=Developer Setup + environments.prod.url=http://foo.bar.com + environments.prod.name=My Cool App +---- + +YAML lists are represented as comma-separated values (useful for simple String values) +and also as property keys with `[index]` dereferencers, for example this YAML: + +[source,yaml,indent=0] +---- + servers: + - dev.bar.com + - foo.bar.com +---- + +Would be transformed into these properties: + +[indent=0] +---- + servers=dev.bar.com,foo.bar.com + servers[0]=dev.bar.com + servers[1]=foo.bar.com +---- + + + +[[boot-features-external-config-exposing-yaml-to-spring]] +==== Exposing YAML as properties in the Spring Environment +The `YamlPropertySourceLoader` class can be used to expose YAML as a `PropertySource` +in the Spring `Environment`. This allows you to use the familiar `@Value` annotation with +placeholders syntax to access YAML properties. + + + +[[boot-features-external-config-multi-profile-yaml]] +==== Multi-profile YAML documents +You can specify multiple profile-specific YAML document in a single file by +by using a `spring.profiles` key to indicate when the document applies. For example: + +[source,yaml,indent=0] +---- + server: + address: 192.168.1.100 + --- + spring: + profiles: production + server: + address: 192.168.1.120 +---- + + + +[[boot-features-external-config-yaml-shortcomings]] +==== YAML shortcomings +YAML files can't be loaded via the `@PropertySource` annotation. So in the +case that you need to load values that way, you need to use a properties file. + + + +[[boot-features-external-config-typesafe-configuration-properties]] +=== Typesafe Configuration Properties +Using the `@Value("${property}")` annotation to inject configuration properties can +sometimes be cumbersome, especially if you are working with multiple properties or +your data is hierarchical in nature. Spring Boot provides an alternative method +of working with properties that allows strongly typed beans to govern and validate +the configuration of your application. For example: + +[source,java,indent=0] +---- + @Component + @ConfigurationProperties(name="connection") + public class ConnectionSettings { + + private String username; + + private InetAddress remoteAddress; + + // ... getters and setters + + } +---- + +When the `@EnableConfigurationProperties` annotation is applied to your `@Configuration`, +any beans annotated with `@ConfigurationProperties` will be automatically configured +from the `Environment` properties. This style of configuration works particularly well +with the `SpringApplication` external YAML configuration: + +[source,yaml,indent=0] +---- + # application.yml + + connection: + username: admin + remoteAddress: 192.168.1.1 + + # additional configuration as required +---- + +To work with `@ConfigurationProperties` beans you can just inject them in the same way +as any other bean. + +[source,java,indent=0] +---- + @Service + public class MyService { + + @Autowired + private ConnectionSettings connection; + + //... + + @PostConstruct + public void openConnection() { + Server server = new Server(); + this.connection.configure(server); + } + + } +---- + +It is also possible to shortcut the registration of `@ConfigurationProperties` bean +definitions by simply listing the properties classes directly in the +`@EnableConfigurationProperties` annotation: + +[source,java,indent=0] +---- + @Configuration + @EnableConfigurationProperties(ConnectionSettings.class) + public class MyConfiguration { + } +---- + + + +[[boot-features-external-config-relaxed-binding]] +==== Relaxed binding +Spring Boot uses some relaxed rules for binding `Environment` properties to +`@ConfigurationProperties` beans, so there doesn't need to be an exact match between +the `Environment` property name and the bean property name. Common examples where this +is useful include underscore separated (e.g. `context_path` binds to `contextPath`), and +capitalized (e.g. `PORT` binds to `port`) environment properties. + +Spring will attempt to coerce the external application properties to the right type when +it binds to the `@ConfigurationProperties` beans. If you need custom type conversion you +can provide a `ConversionService` bean (with bean id `conversionService`) or custom +property editors (via a `CustomEditorConfigurer` bean). + + + +[[boot-features-external-config-validation]] +==== @ConfigurationProperties Validation +Spring Boot will attempt to validate external configuration, by default using JSR-303 +(if it is on the classpath). You can simply add JSR-303 `javax.valididation` constraint +annotations to your `@ConfigurationProperties` class: + +[source,java,indent=0] +---- + @Component + @ConfigurationProperties(name="connection") + public class ConnectionSettings { + + @NotNull + private InetAddress remoteAddress; + + // ... getters and setters + + } +---- + +You can also add a custom Spring `Validator` by creating a bean definition called +`configurationPropertiesValidator`. + +TIP: The `spring-boot-actuator` module includes an endpoint that exposes all +`@ConfigurationProperties` beans. Simply point your web browser to `/configprops` +or use the equivalent JMX endpoint. See the +``<>''. +section for details. + + +[[boot-features-profiles]] +== Profiles +Spring Profiles provide a way to segregate parts of your application configuration and +make it only available in certain environments. Any `@Component` or `@Configuration` can +be marked with `@Profile` to limit when it is loaded: + +[source,java,indent=0] +---- + @Configuration + @Profile("production") + public class ProductionConfiguraiton { + + // ... + + } +---- + +Spring Boot takes this a stage further, in that you can use a `spring.profiles.active` +`Environment` property to specify which profiles are active. You can specify the property +in any of the usual ways, for example you could include it in your +`application.properties`: + +[indent=0] +---- + spring.profiles.active=dev,hsqldb +---- + +or specify on the command line using the switch `--spring.profiles.active=dev,hsqldb`. + + + +[[boot-features-adding-active-profiles]] +=== Adding active profiles +The `spring.profiles.active` property follows the same ordering rules as other +properties, the highest `PropertySource` will win. This means that you can specify +active profiles in `application.properties` then *replace* them using the command line +switch. + +Sometimes it is useful to have profile specific properties that *add* to the active +profiles rather than replace them. The `+` prefix can be used to add active profiles. + +For example, when an application with following properties is run using the switch +`--spring.profiles.active=prod` the `proddb` and `prodmq` profiles will also be activated: + +[source,yaml,indent=0] +---- + --- + my.property: fromyamlfile + --- + spring.profiles: prod + spring.profiles.active: +proddb,+prodmq +---- + + + +[[boot-features-programmatically-setting-profiles]] +=== Programmatically setting profiles +You can programmatically set active profiles by calling +`SpringApplication.setAdditionalProfiles(...)` before your application runs. It is also +possible to activate profiles using Spring's `ConfigurableEnvironment` interface. + + + +[[boot-features-profile-specific-configuration]] +=== Profile specific configuration files +Profile specific variants of both `application.properties` (or `application.yml`) and +files referenced via `@ConfigurationProperties` are considered as files are loaded. +See ``<>'' for details. + + + +[[boot-features-logging]] +== Logging +Spring Boot uses http://commons.apache.org/logging[Commons Logging] for all internal +logging, but leaves the underlying log implementation open. Default configurations are +provided for +http://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html[Java Util Logging], +http://logging.apache.org/log4j/[Log4J] and +http://logback.qos.ch/[Logback]. +In each case there is console output and file output (rotating, 10 Mb file size). + +By default, If you use the ``Starter POMs'', Logback will be used for logging. Appropriate +Logback routing is also included to ensure that dependent libraries that use +Java Util Logging, Commons Logging, Log4J or SLF4J will all work correctly. + +TIP: There are a lot of logging frameworks available for Java. Don't worry if the above +list seems confusing, generally you won't need to change your logging dependencues and +the Spring Boot defaults will work just fine. + + + +[[boot-features-logging-format]] +=== Log format +The default log output from Spring Boot looks like this: + +[indent=0] +---- +2014-03-05 10:57:51.112 INFO 45469 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet Engine: Apache Tomcat/7.0.52 +2014-03-05 10:57:51.253 INFO 45469 --- [ost-startStop-1] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext +2014-03-05 10:57:51.253 INFO 45469 --- [ost-startStop-1] o.s.web.context.ContextLoader : Root WebApplicationContext: initialization completed in 1358 ms +2014-03-05 10:57:51.698 INFO 45469 --- [ost-startStop-1] o.s.b.c.e.ServletRegistrationBean : Mapping servlet: 'dispatcherServlet' to [/] +2014-03-05 10:57:51.702 INFO 45469 --- [ost-startStop-1] o.s.b.c.embedded.FilterRegistrationBean : Mapping filter: 'hiddenHttpMethodFilter' to: [/*] +---- + +The following items are output: + +* Date and Time -- Millesecond precision and easily sortable. +* Log Level -- `ERROR`, `WARN`, `INFO`, `DEBUG` or `TRACE`. +* Process ID. +* A `---` separator to distinguish the start of actual log messages. +* Logger name -- This is usually the source class name (often abbreviated). +* The log message. + + + +[[boot-features-logging-console-output]] +=== Console output +The default log configuration will echo messages to the console as they written. By +default `ERROR`, `WARN` and `INFO` level messages are logged. To also log `DEBUG` level +messages to the console you can start your application with a `--debug` flag. + +[indent=0] +---- + $ java -jar myapp.jar --debug +---- + +If your terminal supports ANSI, color output will be used to aid readability. + + + +[[boot-features-logging-file-output]] +=== File output +By default, log files are written to `spring.log` in your `temp` directory and rotate at +10 Mb. You can easily customize the output folder by setting the `logging.path` property +(for example in your `application.properties`). It is also possible to change the filename +using a `logging.file` property. + +As with console output, `ERROR`, `WARN` and `INFO` level messages are logged by default. + + + +[[boot-features-custom-log-configuration]] +=== Custom log configuration + +The various logging systems can be activated by including the appropriate libraries on +the classpath, and further customized by providing a suitable configuration file in the +root of the classpath, or in a location specified by the Spring `Environment` property +`logging.config`. + +Depending on your logging system, the following files will be loaded: + +|=== +|Logging System |Customization + +|Logback +|`logback.xml` + +|Log4j +|`log4j.properties` or `log4j.xml` + +|JDK (Java Util Logging) +|`logging.properties` +|=== + +To help with the customization some other properties are transferred from the Spring +`Environment` to System properties: + +|=== +|Spring Environment |System Property |Comments + +|`logging.file` +|`LOG_FILE` +|Used in default log configuration if defined. + +|`logging.path` +|`LOG_PATH` +|Used in default log configuration if defined. + +|`PID` +|`PID` +|The current process ID is discovered if possible and not already provided. +|=== + +All the logging systems supported can consult System properties when parsing their +configuration files. See the default configurations in `spring-boot.jar` for examples. + +WARNING: There are know classloading issues with Java Util Logging that cause problems +when running from an ``executable jar''. We recommend that you avoid it if at all +possible. + + + +[[boot-features-developing-web-applications]] +== Developing web applications +Spring Boot is well suited for web application development. You can easily create a +self-contained HTTP server using embedded Tomcat or Jetty. Most web applications will +use the `spring-boot-starter-web` module to get up and running quickly. + +If you haven't yet developed a Spring Boot web application you can follow the +"Hello World!" example in the +``<>'' section. + + + +[[boot-features-spring-mvc]] +=== The ``Spring Web MVC framework'' +The Spring Web MVC framework (often referred to as simply ``Spring MVC'') is a rich +``model view controller'' web framework. Spring MVC lets you create special `@Controller` +or `@RestController` beans to handle incoming HTTP requests. Methods in your controller +are mapped to HTTP using `@RequestMapping` annotations. + +Here is a typical example `@RestController` to serve JSON data: + +[source,java,indent=0] +---- + @RestController + @RequestMapping(value="/users") + public class MyRestController { + + @RequestMapping(value="/{user}", method=RequestMethod.GET) + public User getUser(@PathVariable Long user) { + // ... + } + + @RequestMapping(value="/{user}/customers", method=RequestMethod.GET) + List getUserCustomers(@PathVariable Long user) { + // ... + } + + @RequestMapping(value="/{user}", method=RequestMethod.DELETE) + public User deleteUser(@PathVariable Long user) { + // ... + } + + } +---- + +Spring MVC is part of the core Spring Framework and detailed information is available in +the {spring-reference}#mvc[reference documentation]. There are also several guides +available at http://spring.io/guides that cover Spring MVC. + + + +[[boot-features-spring-mvc-auto-configuration]] +==== Spring MVC auto-configuration +Spring Boot provides auto-configuration for Spring MVC that works well with most +applications. If you want to take complete control of Spring MVC you can add your +own `@Configuration` annotated with `@EnableWebMvc`. + +The auto-configuration adds the following features on top of Spring's defaults: + +* Inclusion of `ContentNegotiatingViewResolver` and `BeanNameViewResolver` beans. +* Support for serving static resources, including support for WebJars (see below). +* Automatic registration of `Converter`, `GenericConverter`, `Formatter` beans. +* Support for `HttpMessageConverters` (see below). +* Static `index.html` support. +* Custom `Favicon` support. + + + +[[boot-features-spring-mvc-message-converters]] +==== HttpMessageConverters +Spring MVC uses the `HttpMessageConverter` interface to convert HTTP requests and +responses. Sensible defaults are included out of the box, for example Objects can be +automatically converted to JSON (using the Jackson library) or XML (using JAXB). + +If you need to add or customize converters you can use Spring Boot's +`HttpMessageConverters` class: +[source,java,indent=0] +---- + import org.springframework.boot.autoconfigure.web.HttpMessageConverters; + import org.springframework.context.annotation.*; + import org.springframework.http.converter.*; + + @Configuration + public class MyConfiguration { + + @Bean + public HttpMessageConverters customConverters() { + HttpMessageConverter additional = ... + HttpMessageConverter another = ... + return new HttpMessageConverters(additional, another); + } + + } +---- + + + +[[boot-features-spring-mvc-static-content]] +==== Static Content +By default Spring Boot will serve static content from a folder called `/static` (or +`/public` or `/resources` or `/META-INF/resources`) in the classpath or from the root +of the `ServeltContext`. It uses the `ResourceHttpRequestHandler` from Spring MVC so you +can modify that behavior by adding your own `WebMvcConfigurerAdapter` and overriding the +`addResourceHandlers` method. + +In a stand-alone web application the default servlet from the container is also +enabled, and acts as a fallback, serving content from the root of the `ServletContext` if +Spring decides not to handle it. Most of the time this will not happen (unless you modify +the default MVC configuration) because Spring will always be able to handle requests +through the `DispatcherServlet`. + +In addition to the ``standard'' static resource locations above, a special case is made for +http://www.webjars.org/[Webjars content]. Any resources with a path in `/webjars/**` will +be served from jar files if they are packaged in the Webjars format. + +TIP: Do not use the `src/main/webapp` folder if your application will be packaged as a +jar. Although this folder is a common standard, it will *only* work with war packaging +and it will be silently ignored by most build tools if you generate a jar. + + + +[[boot-features-spring-mvc-template-engines]] +==== Template engines +As well as REST web services, you can also use Spring MVC to serve dynamic HTML content. +Spring MVC supports a variety of templating technologies including: velocity, freemarker, +and JSPs. Many other templating engines also ship their own Spring MVC integrations. + +Spring Boot includes auto-configuration support for the Thymeleaf templating engine. +Thymeleaf is an XML/XHTML/HTML5 template engine that can work both in web and non-web +environments. If allows you to create natural templates, that can be correctly displayed +by browsers and therefore work also as static prototypes. Thymeleaf templates will be +picked up automatically from `src/main/resources/templates`. + +TIP: JSPs should be avoided if possible, there are several +<> when using them with embedded +servlet containers. + + + +[[boot-features-embedded-container]] +=== Embedded servlet container support +Spring Boot includes support for embedded Tomcat and Jetty servers. Most developers will +simply use the appropriate ``Starter POM'' to obtain a fully configured instance. By +default both Tomcat and Jetty will listen for HTTP requests on port `8080`. + + + +[[boot-features-embedded-container-servlets-and-filters]] +==== Servlets and Filters +When using an embedded servlet container you can register Servlets and Filters directly as +Spring beans. This can be particularly convenient if you want to refer to a value from +your `application.properties` during configuration. + +By default, if the context contains only a single Servlet it will be mapped to `/`. In +the case of multiple Servlets beans the bean name will be used as a path prefix. Filters +will map to `/*`. + +If convention based mapping is not flexible enough you can use the +`ServletRegistrationBean` and `FilterRegistrationBean` classes for complete control. You +can also register items directly if your bean implements the `ServletContextInitializer` +interface. + + + +[[boot-features-embedded-container-application-context]] +==== The EmbeddedWebApplicationContext +Under the hood Spring Boot uses a new type of `ApplicationContext` for embedded +servlet container support. The `EmbeddedWebApplicationContext` is a special +type of `WebApplicationContext` that bootstraps itself by searching for a single +`EmbeddedServletContainerFactory` bean. Usually a `TomcatEmbeddedServletContainerFactory` +or `JettyEmbeddedServletContainerFactory` will have been auto-configured. + +NOTE: You usually won't need to be aware of these implementation classes. Most +applications will be auto-configured and the appropriate `ApplicationContext` and +`EmbeddedServletContainerFactory` will be created on your behalf. + + + +[[boot-features-customizing-embedded-containers]] +==== Customizing embedded servlet containers +Common servlet container settings can be configured using Spring `Environment` +properties. Usually you would define the properties in your `application.properties` +file. + +Common server settings include: + +* `server.port` -- The listen port for incoming HTTP requests. +* `server.address` -- The interface address to bind to. +* `server.sessionTimeout` -- A session timeout. + +See the {sc-spring-boot-autoconfigure}/web/ServerProperties.{sc-ext}[`ServerProperties`] +class for a complete list. + + + +[[boot-features-programmatic-embedded-container-customization]] +===== Programmatic customization +If you need to configure your embdedded servlet container programmatically you can register +a Spring bean that implements the `EmbeddedServletContainerCustomizer` interface. +`EmbeddedServletContainerCustomizer` provides access to the +`ConfigurableEmbeddedServletContainerFactory` which includes numerous customization +setter methods. + +[source,java,indent=0] +---- + import org.springframework.boot.context.embedded.*; + import org.springframework.stereotype.Component; + + @Component + public class CustomizationBean implements EmbeddedServletContainerCustomizer { + + @Override + public void customize(ConfigurableEmbeddedServletContainer container) { + container.setPort(9000); + } + + } +---- + + + +[[boot-features-customizing-configurableembeddedservletcontainerfactory-directly]] +===== Customizing ConfigurableEmbeddedServletContainerFactory directly +If the above customization techniques are too limited, you can register the +`TomcatEmbeddedServletContainerFactory` or `JettyEmbeddedServletContainerFactory` bean +yourself. + +[source,java,indent=0] +---- + @Bean + public EmbeddedServletContainerFactory servletContainer() { + TomcatEmbeddedServletContainerFactory factory = new TomcatEmbeddedServletContainerFactory(); + factory.setPort(9000); + factory.setSessionTimeout(10, TimeUnit.MINUTES); + factory.addErrorPages(new ErrorPage(HttpStatus.404, "/notfound.html"); + return factory; + } +---- + +Setters are provided for many configuration options. Several protected method +``hooks'' are also provided should you need to do something more exotic. See the +source code documentation for details. + + + +[[boot-features-jsp-limitations]] +==== JSP limitations +When running a Spring Boot application that uses an embedded servlet container (and is +packaged as an executable archive), there are some limitations in the JSP support. + +* With Tomcat it should work if you use war packaging, i.e. an executable war will work, + and will also be deployable to a standard container (not limited to, but including + Tomcat). An executable jar will not work because of a hard coded file pattern in Tomcat. + +* Jetty does not currently work as an embedded container with JSPs. + +There is a {github-code}/spring-boot-samples/spring-boot-sample-web-jsp[JSP sample] so +you can see how to set things up. + + + +[[boot-features-sql]] +== Working with SQL databases +The Spring Framework provides extensive support for working with SQL databases. From +direct JDBC access using `JdbcTemplate` though to complete ``object relational mapping'' +technologies such as Hibernate. Spring Data provides an additional level of functionality, +creating `Repoistory` implementations directly from interfaces and using conventions to +generate queries from your method names. + + + +[[boot-features-configure-datasource]] +=== Configure a DataSource +Java's `javax.sql.DataSource` interface provides a standard method of working with +database connections. Traditionally a DataSource uses a `URL` along with some +credentials to establish a database connection. + + + +[[boot-features-embedded-database-support]] +==== Embedded Database Support +It's often convenient develop applications using an in-memory embedded database. +Obviously, in-memory databases do not provide persistent storage; you will need to +populate your database when your application starts and be prepared to throw away +data when your application ends. + +TIP: The ``How-to'' section includes a <> + +Spring Boot can auto-configure embedded http://www.h2database.com[H2], +http://hsqldb.org/[HSQL] and http://db.apache.org/derby/[Derby] databases. You don't +need to provide any connection URLs, simply include a build dependency to the +embedded database that you want to use. + +For example, typical POM dependencies would be: + +[source,xml,indent=0] +---- + + org.springframework.boot + spring-boot-starter-data-jpa + + + org.hsqldb + hsqldb + runtime + +---- + +NOTE: You need a dependency on `spring-jdbc` for an embedded database to be +auto-configured. In this example it's pulled in transitively via +`spring-boot-starter-data-jpa`. + + + +[[boot-features-connect-to-production-database]] +==== Connection to a production database +Production database connections can also be auto-configured using a pooling +`DataSource`. Here's the algorithm for choosing a specific implementation. + +* We prefer the Tomcat pooling `DataSource` for its performance and concurrency, so if + that is available we always choose it. +* If commons-dbcp is available we will use that, but we don't recommend it in production. + +If you use the `spring-boot-starter-jdbc` or `spring-boot-starter-data-jpa` +``starter POMs'' you will automcatically get a dependency to `tomcat-jdbc`. + +NOTE: Additional connection pools can always be configured manually. If you define your +own `DataSource` bean, auto-configuration will not occur. + +DataSource configuration is controlled by external configuration properties in +`spring.datasource.*`. For example, you might declare the following section +in `application.properties`: + +[indent=0] +---- + spring.datasource.url: jdbc:mysql://localhost/test + spring.datasource.username: dbuser + spring.datasource.password: dbpass + spring.datasource.driverClassName: com.mysql.jdbc.Driver +---- + +See {sc-spring-boot-autoconfigure}/jdbc/AbstractDataSourceConfiguration.{sc-ext}[`AbstractDataSourceConfiguration`] +for more of the supported options. + +NOTE: For a pooling `DataSource` to be created we need to be able to verify that a valid +`Driver` class is available, so we check for that before doing anything. I.e. if you set +`spring.datasource.driverClassName=com.mysql.jdbc.Driver` then that class has to be +loadable. + +[[boot-features-using-jdbc-template]] +=== Using JdbcTemplate +Spring's `JdbcTemplate` and `NamedParameterJdbcTemplate` classes are auto-configured and +you can `@Autowire` them directly into your own beans: + +[source,java,indent=0] +---- + import org.springframework.beans.factory.annotation.Autowired; + import org.springframework.jdbc.core.JdbcTemplate; + import org.springframework.stereotype.Component; + + @Component + public class MyBean { + + private final JdbcTemplate jdbcTemplate; + + @Autowired + public MyBean(JdbcTemplate jdbcTemplate) { + this.jdbcTemplate = jdbcTemplate; + } + + // ... + + } +---- + + + +[[boot-features-jpa-and-spring-data]] +=== JPA and ``Spring Data'' +The Java Persistence API is a standard technology that allows you to ``map'' objects to +relational databases. The `spring-boot-starter-data-jpa` POM provides a quick way to get +started. It provides the following key dependencies: + +* Hibernate -- One of the most popular JPA implementations. +* Spring Data JPA -- Makes it easy to easily implement JPA based repositories. +* Spring ORMs -- Core ORM support from the Spring Framework. + +TIP: We won't go into too many details of JPA or Spring Data here. You can follow the +http://spring.io/guides/gs/accessing-data-jpa/[``Accessing Data with JPA''] guide from +http://spring.io and read the http://projects.spring.io/spring-data-jpa/[Spring Data JPA] +and http://hibernate.org/orm/documentation/[Hibernate] reference documentation. + + + +[[boot-features-entity-classes]] +==== Entity Classes +Traditionally, JPA ``Entity'' classes are specified in a `persistence.xml` file. With +Spring Boot this file is not necessary and instead ``Entity Scanning'' is used. By +default all packages below your main configuration class (the one annotated with +`@EnableAutoConfiguration`) will be searched. + +Any classes annotated with `@Entity`, `@Embeddable` or `@MappedSuperclass` will be +considered. A typical entity class would look something like this: + +[source,java,indent=0] +---- + package com.example.myapp.domain; + + import java.io.Serializable; + import javax.persistence.*; + + @Entity + public class City implements Serializable { + + @Id + @GeneratedValue + private Long id; + + @Column(nullable = false) + private String name; + + @Column(nullable = false) + private String state; + + // ... additional members, often include @OneToMany mappings + + protected City() { + // no-args constructor required by JPA spec + // this one is protected since it shouldn't be used directly + } + + public City(String name, String state) { + this.name = name; + this.country = country; + } + + public String getName() { + return this.name; + } + + public String getState() { + return this.state; + } + + // ... etc + + } +---- + +TIP: You can customize entity scanning locations using the `@EntityScan` annotation. +See the ``<>'' +how-to. + + + +[[boot-features-spring-data-jpa-repositories]] +==== Spring Data JPA Repositories +Spring Data JPA repositories are interfaces that you can define to access data. JPA +queries are created automatically from your method names. For example, a `CityRepoistory` +interface might declare a `findAllByState(String state)` method to find all cities +in a given state. + +For more complex queries you can annotate your method using Spring Data's +{spring-data-javadoc}/repository/Query.html[`Query`] annotation. + +Spring Data repositories usually extend from the +{spring-data-commons-javadoc}/repository/Repository.html[`Repository`] or +{spring-data-commons-javadoc}/repository/CrudRepository.html[`CrudRepository`] interfaces. If you are using +auto-configuration, repositories will be searched from the package containing your +main configuration class (the one annotated with `@EnableAutoConfiguration`) down. + +Here is a typical Spring Data repository: + +[source,java,indent=0] +---- + package com.example.myapp.domain; + + import org.springframework.data.domain.*; + import org.springframework.data.repository.*; + + public interface CityRepository extends Repository { + + Page findAll(Pageable pageable); + + City findByNameAndCountryAllIgnoringCase(String name, String country); + + } +---- + +TIP: We have barely scratched the surface of Spring Data JPA. For complete details check +their http://projects.spring.io/spring-data-jpa/[reference documentation]. + + + +[[boot-features-creating-and-dropping-jpa-databases]] +==== Creating and dropping JPA databases +By default JPA database will be automatically created *only* if you use an embedded +database (H2, HSQL or Derby). You can explicitly configure JPA settings using +`spring.jpa.*` properties. For example, to create and drop tables you can add the +following to your `application.properties`. + +[indent=0] +---- + spring.jpa.hibernate.ddl-auto="create-drop" +---- + + + +[[boot-features-nosql]] +== Working with NoSQL technologies +Spring Data provides additional projects that help you access a variety of NoSQL +technologies including +http://projects.spring.io/spring-data-mongodb/[MongoDB], +http://projects.spring.io/spring-data-neo4j/[Neo4J], +http://projects.spring.io/spring-data-redis/[Redis], +http://projects.spring.io/spring-data-gemfire/[Gemfire], +http://projects.spring.io/spring-data-couchbase/[Couchbase] and +http://projects.spring.io/spring-data-cassandra/[Cassandra]. +Spring Boot provides auto-configuration for MongoDB; you can make use of the other +project, but you will need to configure them yourself. Refer to the appropriate +reference documentation at http://projects.spring.io/spring-data. + + + +[[boot-features-mongodb]] +=== MongoDB +http://www.mongodb.com/[MongoDB] is an open-source NoSQL document database that uses a +JSON-like schema instead of traditional table-based relational data. Spring Boot offers +several conveniences for working with MongoDB, including the The +`spring-boot-starter-data-mongodb` ``Starter POM''. + + + +[[boot-features-connecting-to-mongodb]] +==== Connecting to a MongoDB database +You can inject an auto-configured `com.mongodb.Mongo` instance as you would any other +Spring Bean. By default the instance will attempt to connect to a MongoDB server using +the URL `mongodb://localhost/test`: + +[source,java,indent=0] +---- + import org.springframework.beans.factory.annotation.Autowired; + import org.springframework.stereotype.Component; + + import com.mongodb.Mongo; + + @Component + public class MyBean { + + private final Mongo mongo; + + @Autowired + public MyBean(Mongo mongo) { + this.mongo = mongo; + } + + // ... + + } +---- + +You can set `spring.data.mongodb.url` property to change the `url`, or alternatively +specify a `host`/`port`. For example, you might declare the following in your +`application.properties`: + +[indent=0] +---- + spring.data.mongodb.host = mongoserver + spring.data.mongodb.port = 27017 +---- + +TIP: If `spring.data.mongodb.port` is not specified the default of `27017` is used. You +could simply delete this line from the sample above. + +You can also declare your own `Mongo` `@Bean` if you want to take complete control of +establishing the MongoDB connection. + + + +[[boot-features-mongo-template]] +==== MongoTemplate +Spring Data Mongo provides a {spring-data-mongo-javadoc}/core/MongoTemplate.html[`MongoTemplate`] +class that is very similar in its design to Spring's `JdbcTemplate`. As with +`JdbcTemplate` Spring Boot auto-configures a bean for you to simply inject: + +[source,java,indent=0] +---- + import org.springframework.beans.factory.annotation.Autowired; + import org.springframework.data.mongodb.core.MongoTemplate; + import org.springframework.stereotype.Component; + + @Component + public class MyBean { + + private final MongoTemplate mongoTemplate; + + @Autowired + public MyBean(MongoTemplate mongoTemplate) { + this.mongoTemplate = mongoTemplate; + } + + // ... + + } +---- + +See the `MongoOperations` Javadoc for complete details. + + + +[[boot-features-spring-data-mongo-repositories]] +==== Spring Data MongoDB repositories +Spring Data includes repository support for MongoDB. As with the JPA repositories +discussed earlier, the basic principal is that queries are constructed for you +automatically based on method names. + +In fact, both Spring Data JPA and Spring Data MongoDB share the same common +infrastructure; so you could take the JPA example from earlier and, assuming that +`City` is now a Mongo data class rather than a JPA `@Entity`, it will work in the +same way. + +[source,java,indent=0] +---- + package com.example.myapp.domain; + + import org.springframework.data.domain.*; + import org.springframework.data.repository.*; + + public interface CityRepository extends Repository { + + Page findAll(Pageable pageable); + + City findByNameAndCountryAllIgnoringCase(String name, String country); + + } +---- + +TIP: For complete details of Spring Data MongoDB, including its rich object mapping +technologies, refer to their http://projects.spring.io/spring-data-mongodb/[reference +documentation]. + + + +[[boot-features-testing]] +== Testing +Spring Boot provides a number of useful tools for testing your application. The +`spring-boot-starter-parent` POM provides JUnit, Hamcrest and Mockito ``test'' `scope` +dependencies. There are also useful test utilities in the core `spring-boot` module +under the `org.springframework.boot.test` package. There is also a +`spring-boot-starter-test` ``Starter POM''. + + + +[[boot-features-test-scope-dependencies]] +=== Test scope dependencies +If you extend your Maven project from the `spring-boot-starter-parent` POM, or use the +`spring-boot-starter-test` ``Starter POM'' (in the `test` `scope`), you will find +the following provided libraries: + +* Junit -- The de-facto standard for unit testing Java applications. +* Hamcrest -- A library of matcher objects (also known as constraints or predicates) + allowing `assertThat` style JUnit assertions. +* Mockito -- A Java mocking framework. + +These are common libraries that we generally find useful when writing Tests. You are free +to replace them if they don't suit your needs. + + + +[[boot-features-testing-spring-applications]] +=== Testing Spring applications +One of the major advantages of dependency injection is that it should make your code +easier to unit test. You can simply instantiate objects using the `new` operator without +even involving Spring. You can also use _mock objects_ instead of real dependencies. + +Often you need to move beyond ``unit testing'' and start ``integration testing'' (with +a Spring `ApplicationContext` actually involved in the process). It's useful to be able +to perform integration testing without requiring deployment of your application or +needing to connect to other infrastructure. + +The Spring Framework includes a dedicated test module for just such integration testing. +You can declare a dependency directly to `org.springframework:spring-test` or use the +`spring-boot-starter-test` ``Starter POM'' to pull it in transitively. + +If you have not use the `spring-test` module before you should start by reading the +{spring-reference}/#testing[relevant section] of the Spring Framework reference +documentation. + + + +[[boot-features-testing-spring-boot-applications]] +=== Testing Spring Boot applications +A Spring Boot application is just a Spring `ApplicationContext` so nothing very special +has to be done to test it beyond what you would normally do with a vanilla Spring context. +One thing to watch out for though is that the external properties, logging and other +features of Spring Boot are only installed in the context by default if you use +`SpringApplication` to create it. + +Spring Boot provides a `@SpringApplicationConfiguration` annotation as an alternative +to the standard `spring-test` `@ContextConfiguration` annotation. If you use +`@SpringApplicationConfiguration` to configure the `ApplicationContext` used in your +tests, it will be created via `SpringApplication` and you will get the additional Spring +Boot features. + +For example: +[source,java,indent=0,subs="verbatim,quotes,attributes"] +---- + @RunWith(SpringJUnit4ClassRunner.class) + @SpringApplicationConfiguration(classes = SampleDataJpaApplication.class) + public class CityRepositoryIntegrationTests { + + @Autowired + CityRepository repository; + + // ... + + } +---- + +TIP: The context loader guesses whether you want to test a web application or not (e.g. with +`MockMVC`) by looking for the `@WebAppConfiguration` annotation. (`MockMVC` and +`@WebAppConfiguration` are part of `spring-test`). + + + +[[boot-features-test-utilities]] +=== Test utilities +A few test utility classes are packaged as part of `spring-boot` that are generally +useful when testing your application. + + + +[[boot-features-configfileapplicationcontextinitializer-test-utility]] +==== ConfigFileApplicationContextInitializer +`ConfigFileApplicationContextInitializer` is an `ApplicationContextInitializer` that +can apply to your tests to load Spring Boot `application.properties` files. You can use +when you don't need the full features provided by `@SpringApplicationConfiguration`. + +[source,java,indent=0] +---- + @ContextConfiguration(classes = Config.class, + initializers = ConfigFileApplicationContextInitializer.class) +---- + + + +[[boot-features-environment-test-utilities]] +==== EnvironmentTestUtils +`EnvironmentTestUtils` allows you to quickly add properties to a +`ConfigurableEnvironment` or `ConfigurableApplicationContext`. Simply call it with +`key=value` strings: + +[source,java,indent=0] +---- +EnvironmentTestUtils.addEnvironment(env, "org=Spring", "name=Boot"); +---- + + + +[[boot-features-output-capture-test-utility]] +==== OutputCapture +`OutputCapture` is a JUnit `Rule` that you can use to capture `System.out` and +`System.err` output. Simply declare the capture as a `@Rule` then use `toString()` +for assertions: + +[source,java,indent=0] +---- +import org.junit.Rule; +import org.junit.Test; +import org.springframework.boot.test.OutputCapture; + +import static org.hamcrest.Matchers.*; +import static org.junit.Assert.*; + +public class MyTest { + + @Rule + public OutputCapture capture = new OutputCapture(); + + @Test + public void testName() throws Exception { + System.out.println("Hello World!"); + assertThat(capture.toString(), containsString("World")); + } + +} +---- + + + +[[boot-features-developing-auto-configuration]] +== Developing auto-configuration and using conditions +If you work in a company that develops shared libraries, or if you work on an open-source +or commercial library, you might want to develop your own auto-configuration. +Auto-configuration classes can be bundled in external jars and still be picked-up by +Spring Boot. + + + +[[boot-features-understanding-auto-configured-beans]] +=== Understanding auto-configured beans +Under the hood, auto-configuration is implemented with standard `@Configuration` classes. +Additional `@Conditional` annotations are used to constrain when the auto-configuration +should apply. Usually auto-configuration classes use `@ConditionalOnClass` and +`@ConditionalOnMissingBean` annotations. This ensures that auto-configuration only +applies when relevant classes are found and when you have not declared your own +`@Configuration`. + +You can browse the source code of `spring-boot-autoconfigure` to see the `@Configuration` +classes that we provide (see the `META-INF/spring.factories` file). + + + +[[boot-features-locating-auto-configuration-candidates]] +=== Locating auto-configuration candidates +Spring Boot checks for the presence of a `META-INF/spring.factories` file within your +published jar. The file should list your configuration classes under the +`EnableAutoConfiguration` key. + +[indent=0] +---- + org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ + com.mycorp.libx.autoconfigure.LibXAutoConfiguration,\ + com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration +---- + +You can use the +{sc-spring-boot-autoconfigure}/AutoConfigureAfter.{sc-ext}[`@AutoConfigureAfter`] or +{sc-spring-boot-autoconfigure}/AutoConfigureBefore.{sc-ext}[`@AutoConfigureBefore`] +annotations if your configuration needs to be applied in a specific order. For example, +if you provide web specific configuration, your class may need to be applied after +`WebMvcAutoConfiguration`. + + + +[[boot-features-condition-annotations]] +=== Condition annotations +You almost always want to include one or more `@Condition` annotations on your +auto-configuration class. The `@ConditionalOnMissingBean` is one common example that is +used to allow developers to ``override'' auto-configuration if they are not happy with +your defaults. + +Spring Boot includes a number of `@Conditional` annotations that you can reuse in your own +code by annotating `@Configuration` classes or individual `@Bean` methods. + + + +[[boot-features-class-conditions]] +==== Class conditions +The `@ConditionalOnClass` and `@ConditionalOnMissingClass` annotations allows configuration +to be skipped based on the presence or absence of specific classes. Due to the fact that +annotation meta-data is parsed using http://asm.ow2.org/[ASM] you can actually use the +`value` attribute to refer to the real class, even though that class might not actually +appear on the running application classpath. You can also use the `name` attribute if you +prefer to specify the class name using a `String` value. + + + +[[boot-features-bean-conditions]] +==== Bean conditions +The `@ConditionalOnBean` and `@ConditionalOnMissingBean` annotations allow configurations +to be skipped based on the presence or absence of specific beans. You can use the `value` +attribute to specify beans by type, or `name` to specify beans by name. The `search` +attribute allows you to limit the `ApplicationContext` hierarchy that should be considered +when searching for beans. + +NOTE: `@Conditional` annotations are processed when `@Configuration` classes are +parsed. Auto-configure `@Configuration` is always parsed last (after any user defined +beans), however, if you are using these annotations on regular `@Configuration` classes, +care must be take not to refer to bean definitions that have not yet been created. + + + +[[boot-features-resource-conditions]] +==== Resource conditions +The `@ConditionalOnResource` annotation allows configuration to be skipped when a specific +resource is not present. Resources can be specified using the usual Spring conventions, +for example, `file:/home/user/test.dat`. + + + +[[boot-features-web-application-conditions]] +==== Web Application Conditions +The `@ConditionalOnWebApplication` and `@ConditionalOnNotWebApplication` annotations +allow configuration to be skipped depending on whether the application is a +'web application'. A web application is any application that is using a Spring +`WebApplicationContext`, defines a `session` scope or has a `StandardServletEnvironment`. + + + +[[boot-features-spel-conditions]] +==== SpEL expression conditions +The `@ConditionalOnExpression` annotation allows configuration to be skipped based on the +result of a {spring-reference}/#expressions[SpEL expression]. + + + +[[boot-features-whats-next]] +== What to read next +If you want to learn more about any of the classes discussed in this section you can +check out the {dc-root}[Spring Boot API documentation] or you can browse the +{github-code}[source code directly]. If you have specific questions, take a look at the +<> section. + +If you are comfortable with Spring Boot's core features, you can carry on and read +about <>. + diff --git a/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc b/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc new file mode 100644 index 0000000000..70be2bee11 --- /dev/null +++ b/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc @@ -0,0 +1,597 @@ +[[using-boot]] += Using Spring Boot + +[partintro] +-- +This section goes into more detail about how you should use Spring Boot. It covers topics +such as build systems, auto-configuration and run/deployment options. We also cover some +Spring Boot ``best practices''. Although there is nothing particularly special about +Spring Boot (it is just another library that you can consume). There are a few +recommendations that, when followed, will make your development process just a +little easier. + +If you're just starting out with Spring Boot, you should probably read the +``<>'' guide before diving into +this section. +-- + + + +[[using-boot-build-systems]] +== Build systems +It is strongly recommended that you choose a build system that supports _dependency +management_, and one that can consume artifacts published to the ``Maven Central'' +repository. We would recommend that you choose Maven or Gradle. It is possible to get +Spring Boot to work with other build systems (Ant for example), but they will not be +particularly well supported. + + + +[[using-boot-maven]] +=== Maven +Maven users can inherit from the `spring-boot-starter-parent` project to obtain sensible +defaults. The parent project provides the following features: + +* Java 1.6 as the default compiler level. +* UTF-8 source encoding. +* A Dependency Management section, allowing you to omit `` tags for common + dependencies. +* Generally useful test dependencies (http://junit.org/[JUnit], + https://code.google.com/p/hamcrest/[Hamcrest], + https://code.google.com/p/mockito/[Mockito]). +* Sensible https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html[resource filtering]. +* Sensible plugin configuration (http://mojo.codehaus.org/exec-maven-plugin/[exec plugin], + http://maven.apache.org/surefire/maven-surefire-plugin/[surefire], + https://github.com/ktoso/maven-git-commit-id-plugin[Git commit ID], + http://maven.apache.org/plugins/maven-shade-plugin/[shade]). + + + +[[using-boot-maven-parent-pom]] +==== Inheriting the starter parent +To configure your project to inherit from the `spring-boot-starter-parent` simply set +the `parent`: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + org.springframework.boot + spring-boot-starter-parent + {spring-boot-version} + +---- + +NOTE: You should only need to specify the Spring Boot version number on this dependency. +if you import additional starters, you can safely omit the version number. + + + +[[using-boot-maven-your-own-parent]] +==== 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 a +`scope=import` dependency: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + org.springframework.boot + spring-boot-starter-parent + {spring-boot-version} + import + + + +---- + + + +[[using-boot-maven-java-version]] +==== Changing the Java version +The `spring-boot-starter-parent` chooses fairly conservative Java compatibility. If you +want to follow our recommendation and use a later Java version you can add a +`java.version` property: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + 1.8 + +---- + + + +[[using-boot-maven-plugin]] +==== Using the Spring Boot Maven plugin +Spring Boot includes a <> +that can package the project as an executable jar. Add the plugin to your `` +section if you want to use it: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + org.springframework.boot + spring-boot-maven-plugin + + + +---- + +NOTE: You only need to add the plugin, there is no need for to configure it unless you +want to change the settings defined in the parent. + + + +[[using-boot-gradle]] +=== Gradle +Gradle users can directly import ``starter POMs'' in their `dependencies` section. Unlike +Maven, there is no ``super parent'' to import. + +[source,groovy,indent=0,subs="attributes"] +---- + apply plugin: 'java' + + repositories { mavenCentral() } + dependencies { + compile("org.springframework.boot:spring-boot-starter-web:{spring-boot-version}") + } +---- + +The <> +is also available and provides tasks to create executable jars and run projects from +source. It also adds a `ResolutionStrategy` that enables you to omit the version number +for ``blessed'' dependencies: + +[source,groovy,indent=0,subs="attributes"] +---- + buildscript { + repositories { mavenCentral() } + dependencies { + classpath("org.springframework.boot:spring-boot-gradle-plugin:{spring-boot-version}") + } + } + + apply plugin: 'java' + apply plugin: 'spring-boot' + + repositories { mavenCentral() } + dependencies { + compile("org.springframework.boot:spring-boot-starter-web") + testCompile("org.springframework.boot:spring-boot-starter-test") + } +---- + + + +[[using-boot-ant]] +=== Ant +It is possible to build a Spring Boot project using Apache Ant, however, no special +support or plugins are provided. Ant scripts can use the Ivy dependency system to import +starter POMs. + +See the ``<>'' ``How-to'' for more +complete instructions. + + + +[[using-boot-starter-poms]] +=== Starter POMs +Starter POMs 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. + +.What's in a name +**** +All starters follow a similar naming pattern; `spring-boot-starter-*`, where `*` is +a particular type of application. This naming structure is intended to help when you need +to find a starter. The Maven integration in many IDEs allow you to search dependencies by +name. For example, with the appropriate Eclipse or STS plugin installed, you can simply +hit `ctrl-space` in the POM editor and type ''spring-boot-starter'' for a complete list. +**** + +The following application starters are provided by Spring Boot under the +`org.springframework.boot` group: + +.Spring Boot application starters +|=== +| Name | Description + +|`spring-boot-starter` +|The core Spring Boot starter, including auto-configuration support, logging and YAML. + +|`spring-boot-starter-amqp` +|Support for the ``Advanced Message Queuing Protocol'' via `spring-rabbit`. + +|`spring-boot-starter-aop` +|Full AOP programming support including `spring-aop` and AspectJ. + +|`spring-boot-starter-batch` +|Support for ``Spring Batch'' including HSQLDB database. + +|`spring-boot-starter-data-jpa` +|Full support for the ``Java Persistence API'' including `spring-data-jpa`, `spring-orm` +and Hibernate. + +|`spring-boot-starter-data-mongodb` +|Support for the MongoDB NoSQL Database, including `spring-data-mongodb`. + +|`spring-boot-starter-data-rest` +|Support for exposing Spring Data repositories over REST via `spring-data-rest-webmvc`. + +|`spring-boot-starter-integration` +|Support for common `spring-integration` modules. + +|`spring-boot-starter-jdbc` +|JDBC Database support. + +|`spring-boot-starter-mobile` +|Support for `spring-mobile` + +|`spring-boot-starter-redis` +|Support for the REDIS key-value data store, including `spring-redis`. + +|`spring-boot-starter-security` +|Support for `spring-security`. + +|`spring-boot-starter-test` +|Support for common test dependencies, including JUnit, Hamcrest and Mockito along with + the `spring-test` module. + +|`spring-boot-starter-thymeleaf` +|Support for the Thymeleaf templating engine, including integration with Spring. + +|`spring-boot-starter-web` +|Support for full-stack web development, including Tomcat and `spring-webmvc`. + +|`spring-boot-starter-websocket` +|Support for websocket development with Tomcat. +|=== + +In addition to the application starters, the following starters can be used to +add ``<>'' features. + +.Spring Boot production ready starters +|=== +| Name | Description + +|`spring-boot-starter-actuator` +|Adds production ready features such as metrics and monitoring. + +|`spring-boot-starter-shell-remote` +|Adds remote `ssh` shell support. +|=== + +Finally, Spring Boot includes some starters that can be used if you want to exclude or +swap specific technical facets. + +.Spring Boot technical starters +|=== +| Name | Description + +|`spring-boot-starter-jetty` +|Imports the Jetty HTTP engine (to be used as an alternative to Tomcat) + +|`spring-boot-starter-log4j` +|Support the Log4J looggin framework + +|`spring-boot-starter-logging` +|Import Spring Boot's default logging framework (Logback). + +|`spring-boot-starter-tomcat` +|Import Spring Boot's default HTTP engine (Tomcat). +|=== + + + +[[using-boot-structuring-your-code]] +== Structuring your code +Spring Boot does not require any specific code layout to work, however, there are some +best practices that help. + + + +[[using-boot-using-the-default-package]] +=== Using the ``default'' package +When a class doesn't include a `package` declaration it is considered to be in the +``default package''. The use of the ``default package'' is generally discouraged, and +should be avoided. It can cause particular problems for Spring Boot applications that +use `@ComponentScan` or `@EntityScan` annotations, since every class from every jar, +will be read. + +TIP: We recommend that you use the follow Java's recommended package naming conventions +and use a reversed domain name (for example, `com.example.project`). + + + +[[using-boot-locating-the-main-class]] +=== Locating the main application class +We generally recommend that you locate your main application class in a root package +above other classes. The `@EnableAutoConfiguration` annotation is often placed on your +main class, and it implicitly defines a base ``search package'' for certain items. For +example, if you are writing a JPA application, the package of the +`@EnableAutoConfiguration` annotated class will be used to search for `@Entity` items. + +Using a root package also allows the `@ComponentScan` annotation to be used without +needing to specify a `basePackage` attribute. + +Here is a typical layout: + +[indent=0] +---- + com + +- example + +- myproject + +- Application.java + | + +- domain + | +- Customer.java + | +- CustomerRepository.java + | + +- service + | +- CustomerService.java + | + +- web + +- CustomerController.java +---- + +The `Application.java` file would declare the `main` method, along with the basic +`@Configuration`. + +[source,java,indent=0] +---- + package com.example.myproject; + + import org.springframework.boot.SpringApplication; + import org.springframework.boot.autoconfigure.EnableAutoConfiguration; + import org.springframework.context.annotation.ComponentScan; + import org.springframework.context.annotation.Configuration; + + @Configuration + @EnableAutoConfiguration + @ComponentScan + public class Application { + + public static void main(String[] args) { + SpringApplication.run(Application.class, args); + } + + } +---- + + + +[[using-boot-configuration-classes]] +== Configuration classes +Spring Boot favors Java-based configuration. Although it is possible to call +`SpringApplication.run()` with an XML source, we generally recommend that your primary +source is a `@Configuration` class. Usually the class that defines the `main` method +is also a good candidate as the primary `@Configuration`. + +TIP: Many Spring configuration examples have been published on the Internet that use XML +configuration. Always try to use the equivalent Java-base configuration if possible. +Searching for `enable*` annotations can be a good starting point. + + + +[[using-boot-importing-configuration]] +=== Importing additional configuration classes +You don't need to put all your `@Configuration` into a single class. The `@Import` +annotation can be used to import additional configuration classes. Alternatively, you +can use `@ComponentScan` to automatically pickup all Spring components, including +`@Configuration` classes. + + + +[[using-boot-importing-xml-configuration]] +=== Importing XML configuration +If you absolutely must use XML based configuration, we recommend that you still start +with a `@Configuration` class. You can then use an additional `@ImportResource` +annotation to load XML configuration files. + + + +[[using-boot-auto-configuration]] +== Auto-configuration +Spring Boot auto-configuration attempts to automatically configure your Spring +application based on the jar dependencies that you have added. For example, If +`HSQLDB` is on your classpath, and you have not manually configured any database +connection beans, then we will auto-configure an in-memory database. + +You need to opt-in to auto-configuration by adding the `@EnableAutoConfiguration` +annotation to one of your `@Configuration` classes. + +TIP: You should only ever add one `@EnableAutoConfiguration` annotation. We generally +recommend that you add it to your primary `@Configuration` class. + + + +[[using-boot-replacing-auto-configuration]] +=== Gradually replacing auto-configuration +Auto-configuration is noninvasive, at any point you can start to define your own +configuration to replace specific parts of the auto-configuration. For example, if +you add your own `DataSource` bean, the default embedded database support will back away. + +If you need to find out what auto-configuration is currently being applied, and why, +starting your application with the `--debug` switch. This will log an auto-configuration +report to the console. + + + +[[using-boot-disabling-specific-auto-configutation]] +=== Disabling specific auto-configuration +If you find that specific auto-configure classes are being applied that you don't want, +you can use the exclude attribute of `@EnableAutoConfiguration` to disable them. + +[source,java,indent=0] +---- + import org.springframework.boot.autoconfigure.*; + import org.springframework.boot.autoconfigure.jdbc.*; + import org.springframework.context.annotation.*; + + @Configuration + @EnableAutoConfiguration(exclude={EmbeddedDatabaseConfiguration.class}) + public class MyConfiguration { + } +---- + + + +[[using-boot-spring-beans-and-dependency-injection]] +== Spring Beans and dependency injection +You are free to use any the standard Spring Framework techniques to defines your beans +and their injected dependencies. For simplicity, we often find that using `@ComponentScan` +to find your beans, in combination with `@Autowired` constructor injection works well. + +If you structure your code as suggested above (locating your application class in a root +package), you can add `@ComponentScan` without any arguments. All of your application +components (`@Component`, `@Service`, `@Repoistory`, `@Controller` etc.) will be +automatically registered as Spring Beans. + +Here is an example `@Service` Bean that uses constructor injection to obtain a +required `RiskAssessor` bean. + +[source,java,indent=0] +---- + package com.example.service; + + import org.springframework.beans.factory.annotation.Autowired; + import org.springframework.stereotype.Service; + + @Service + public class DatabaseAccountService implements AccountService { + + private final RiskAssessor riskAssessor; + + @Autowired + public DatabaseAccountService(RiskAssessor riskAssessor) { + this.riskAssessor = riskAssessor; + } + + // ... + + } +---- + +TIP: Notice how using constructor injection allows the `riskAssessor` field to be marked +as `final`, indicating that it cannot be subsequently changed. + +[[using-boot-running-your-application]] +== Running your application +One of the biggest advantages of packaging your application as jar and using an embedded +HTTP server is that you can run your application as you would any other. Debugging Spring +Boot applications is also easy; you don't need any special IDE plugins or extensions. + +NOTE: This section only covers jar based packaging, If you choose to package your +application as a war file you should refer to your server and IDE documentation. + + + +[[using-boot-running-from-an-ide]] +=== Running from an IDE +You can run a Spring Boot application from your IDE as a simple Java application, however, +first you will need to import your project. Import steps will vary depending on your IDE +and build system. Most IDEs can import Maven projects directly, for example Eclipse users +can select `Import...` -> `Existing Maven Projects` from the `File` menu. + +If you can't directly import your project into your IDE, you may be able to generate IDE +meta-data using a build plugin. Maven includes plugins for +http://maven.apache.org/plugins/maven-eclipse-plugin/[Eclipse] and +http://maven.apache.org/plugins/maven-idea-plugin/[IDEA]; Gradle offers plugins +for http://www.gradle.org/docs/current/userguide/ide_support.html[various IDEs]. + +TIP: If you accidentally run a web application twice you will see a ``Port already in +use'' error. STS users can use the `Relauch` button rather than `Run` to ensure that +any existing instance is closed. + + + +[[using-boot-running-as-a-packaged-application]] +=== Running as a packaged application +If you use the Spring Boot Maven or Gradle plugins to create an executable jar you can +run your application using `java -jar`. For example: + +[indent=0,subs="attributes"] +---- + $ java -jar target/myproject-0.0.1-SNAPSHOT.jar +---- + +It is also possible to run a packaged application with remote debugging support enabled. +This allows you to attach a debugger to your packaged application: + +[indent=0,subs="attributes"] +---- + $ java -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8000,suspend=n \ + -jar target/myproject-0.0.1-SNAPSHOT.jar +---- + + + +[[using-boot-running-with-the-maven-plugin]] +=== Using the Maven plugin +The Spring Boot Maven plugin includes a `run` goal which can be used to quickly compile +and run your application. Applications run in an exploded form, and you can edit +resources for instant ``hot'' reload. + +[indent=0,subs="attributes"] +---- + $ mvn spring-boot:run +---- + + + +[[using-boot-running-with-the-gradle-plugin]] +=== Using the Gradle plugin +The Spring Boot Gradle plugin also includes a `run` goal which can be used to run +your application in an exploded form. The `bootRun` task is added whenever you import +the `spring-boot-plugin` + +[indent=0,subs="attributes"] +---- + $ gradle bootRun +---- + + + +[[using-boot-hot-swapping]] +=== Hot swapping +Since Spring Boot applications are just plain Java application, JVM hot-swapping should +work out of the box. JVM hot swapping is somewhat limited with the bytecode that it can +replace, for a more complete solution the +https://github.com/spring-projects/spring-loaded[Spring Loaded] project, or +http://zeroturnaround.com/software/jrebel/[JRebel] can be used. + +See the <> section for details. + + + +[[using-boot-packaging-for-production]] +== Packaging your application for production +Executable jars can be used for production deployment. As they are self contained, they +are also ideally suited for cloud-based deployment. + +For additional ``production ready'' features, such as health, auditing and metric REST +or JMX end-points; consider adding `spring-boot-actuator`. See +``<>'' for details. + + + +[[using-boot-whats-next]] +== What to read next +You should now have good understanding of how you can use Spring Boot along with some best +practices that you should follow. You can now go on to learn about specific +``<>'' in depth, or you +could skip ahead and read about the +``<>'' aspects of Spring +Boot.