diff --git a/spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc b/spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc index c57551b72ab..2aa5c436dfe 100644 --- a/spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc +++ b/spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc @@ -235,63 +235,70 @@ an extensive https://github.com/CloudBees-community/springboot-gradle-cloudbees that covers the steps that you need to follow when deploying to CloudBees. + [[cloud-deployment-openshift]] == Openshift https://www.openshift.com/[Openshift] is the RedHat public (and enterprise) PaaS solution. Like Heroku, it works by running scripts triggered by git commits, so you can script -the launching of a Spring Boot app in pretty much any way you like as long as the -Java runtime is available (which is a standard feature you can ask from at Openshift). -To do this you can use the https://www.openshift.com/developers/do-it-yourself[DIY Cartridge] -and hooks in your repository under `.openshift/action_scripts`: +the launching of a Spring Boot application in pretty much any way you like as long as the +Java runtime is available (which is a standard feature you can ask for at Openshift). +To do this you can use the +https://www.openshift.com/developers/do-it-yourself[DIY Cartridge] and hooks in your +repository under `.openshift/action_scripts`: The basic model is to: -1. Ensure Java and your build tool are installed remotely, e.g. using -a `pre_build` hook (Java and Maven are installed by default, Gradle is not) - +1. Ensure Java and your build tool are installed remotely, e.g. using a `pre_build` hook + (Java and Maven are installed by default, Gradle is not) 2. Use a `build` hook to build your jar (using Maven or Gradle), e.g. + +[indent=0] ---- -#!/bin/bash -cd $OPENSHIFT_REPO_DIR -mvn package -s .openshift/settings.xml -DskipTests=true + #!/bin/bash + cd $OPENSHIFT_REPO_DIR + mvn package -s .openshift/settings.xml -DskipTests=true ---- + 3. Add a `start` hook that calls `java -jar ...` + +[indent=0] ---- -#!/bin/bash -cd $OPENSHIFT_REPO_DIR -nohup java -jar target/*.jar --server.port=${OPENSHIFT_DIY_PORT} --server.address=${OPENSHIFT_DIY_IP} & + #!/bin/bash + cd $OPENSHIFT_REPO_DIR + nohup java -jar target/*.jar --server.port=${OPENSHIFT_DIY_PORT} --server.address=${OPENSHIFT_DIY_IP} & ---- + 4. Use a `stop` hook (since the start is supposed to return cleanly), e.g. + +[indent=0] ---- -#!/bin/bash -source $OPENSHIFT_CARTRIDGE_SDK_BASH -PID=$(ps -ef | grep java.*\.jar | grep -v grep | awk '{ print $2 }') -if [ -z "$PID" ] -then - client_result "Application is already stopped" -else - kill $PID -fi + #!/bin/bash + source $OPENSHIFT_CARTRIDGE_SDK_BASH + PID=$(ps -ef | grep java.*\.jar | grep -v grep | awk '{ print $2 }') + if [ -z "$PID" ] + then + client_result "Application is already stopped" + else + kill $PID + fi ---- + 5. Embed service bindings from environment variables provided by the platform in your `application.properties`, e.g. + +[indent=0] ---- -spring.datasource.url: jdbc:mysql://${OPENSHIFT_MYSQL_DB_HOST}:${OPENSHIFT_MYSQL_DB_PORT}/${OPENSHIFT_APP_NAME} -spring.datasource.username: ${OPENSHIFT_MYSQL_DB_USERNAME} -spring.datasource.password: ${OPENSHIFT_MYSQL_DB_PASSWORD} + spring.datasource.url: jdbc:mysql://${OPENSHIFT_MYSQL_DB_HOST}:${OPENSHIFT_MYSQL_DB_PORT}/${OPENSHIFT_APP_NAME} + spring.datasource.username: ${OPENSHIFT_MYSQL_DB_USERNAME} + spring.datasource.password: ${OPENSHIFT_MYSQL_DB_PASSWORD} ---- -There's a blog on https://www.openshift.com/blogs/run-gradle-builds-on-openshift[running Gradle -in Openshift] on their website that will get you started with a gradle build to run -the app. A http://issues.gradle.org/browse/GRADLE-2871[bug in Gradle] currently prevents you -from using Gradle newer than 1.6. +There's a blog on https://www.openshift.com/blogs/run-gradle-builds-on-openshift[running +Gradle in Openshift] on their website that will get you started with a gradle build to +run the app. A http://issues.gradle.org/browse/GRADLE-2871[bug in Gradle] currently +prevents you from using Gradle newer than 1.6. + + [[cloud-deployment-whats-next]] == What to read next diff --git a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc index dd738750c79..53eade7c510 100644 --- a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc @@ -13,9 +13,9 @@ Auditing, health and metrics gathering can be automatically applied to your appl [[production-ready-enabling]] == Enabling production-ready features. -The https://github.com/spring-projects/spring-boot/tree/master/spring-boot-actuator[`spring-boot-actuator`] module provides all of Spring Boot's production-ready -features. The simplest way to enable the features is to add a dependency to the -`spring-boot-starter-actuator` ``Starter POM''. +The {github-code}/spring-boot-actuator[`spring-boot-actuator`] module provides all of +Spring Boot's production-ready features. The simplest way to enable the features is to add +a dependency to the `spring-boot-starter-actuator` ``Starter POM''. .Definition of Actuator **** diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index aba10c6f688..18aded06ea7 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -308,12 +308,12 @@ can set up default values for your application in `application.properties` (or w other basename you choose with `spring.config.name`) and override it at runtime with a different file, keeping the defaults. -> Note: if you use environment variables not system properties, most operating systems -disallow period-separated key names, but you can use underscores instead (e.g. +NOTE: if you use environment variables not system properties, most operating systems +disallow period-separated key names, but you can use underscores instead (e.g. `SPRING_CONFIG_NAME` instead of `spring.config.name`). -> Note: If you are running in a container then JNDI properties (in `java:comp/env`) or -servlet context initialization parameters can be used instead of or as well as +NOTE: If you are running in a container then JNDI properties (in `java:comp/env`) or +servlet context initialization parameters can be used instead of, or as well as, environment variables or system properties. @@ -1430,27 +1430,36 @@ 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 Redis, MongoDB, Elasticsearch, Solr and Gemfire; you can make use of the other -projects, but you will need to configure them yourself. Refer to the appropriate -reference documentation at http://projects.spring.io/spring-data. +Spring Boot provides auto-configuration for Redis, MongoDB, Elasticsearch, Solr and +Gemfire; you can make use of the other projects, but you will need to configure them +yourself. Refer to the appropriate reference documentation at +http://projects.spring.io/spring-data[projects.spring.io/spring-data]. + [[boot-features-redis]] === Redis -http://redis.io/[Redis] is a cache, message broker and richly-featured key-value store. Spring Boot offers basic autoconfiguration for the https://github.com/xetorthio/jedis/[Jedis] client library and abstractions on top of it provided by https://github.com/spring-projects/spring-data-redis[Spring Data Redis]. There is a `spring-boot-starter-redis` ``Starter POM`` for collecting the dependencies in a convenient way. +http://redis.io/[Redis] is a cache, message broker and richly-featured key-value store. +Spring Boot offers basic auto-configuration for the https://github.com/xetorthio/jedis/[Jedis] +client library and abstractions on top of it provided by +https://github.com/spring-projects/spring-data-redis[Spring Data Redis]. There is a +`spring-boot-starter-redis` ``Starter POM'' for collecting the dependencies in a +convenient way. + + [[boot-features-connecting-to-redis]] ==== Connecting to Redis -You can inject an auto-configured `RedisConnectionFactory`, `StringRedisTemplate` or vanilla `RedisTemplate` instance as you would any other -Spring Bean. By default the instance will attempt to connect to a Redis server using -`localhost:6379`: +You can inject an auto-configured `RedisConnectionFactory`, `StringRedisTemplate` or +vanilla `RedisTemplate` instance as you would any other Spring Bean. By default the +instance will attempt to connect to a Redis server using `localhost:6379`: [source,java,indent=0] ---- @Component public class MyBean { - private StringRedisTemplate template; + private StringRedisTemplate template; @Autowired public MyBean(StringRedisTemplate template) { @@ -1462,9 +1471,11 @@ Spring Bean. By default the instance will attempt to connect to a Redis server u } ---- -If you add a `@Bean` of your own of any of the autoconfigured types it will replace the default -(except in the case of `RedisTemplate` the exlcusion is based on the bean name "redisTemplate" not its type). -If `commons-pool2` is on the classpath you will get a pooled connection factory by default. +If you add a `@Bean` of your own of any of the auto-configured types it will replace the +default (except in the case of `RedisTemplate` the exclusion is based on the bean name +``redisTemplate'' not its type). If `commons-pool2` is on the classpath you will get a +pooled connection factory by default. + [[boot-features-mongodb]] @@ -1581,22 +1592,33 @@ TIP: For complete details of Spring Data MongoDB, including its rich object mapp technologies, refer to their http://projects.spring.io/spring-data-mongodb/[reference documentation]. + + [[boot-features-gemfire]] === Gemfire -https://github.com/spring-projects/spring-data-gemfire[Spring Data Gemfire] provides convenient Spring-friendly -tools for accessing the http://www.gopivotal.com/big-data/pivotal-gemfire#details[Pivotal Gemfire] data management platform. -There is a `spring-boot-starter-data-gemfire` ``Starter POM`` for collecting the dependencies in a convenient way. There is currently no autoconfig support for Gemfire but you can enable Spring Data Repositories with a https://github.com/spring-projects/spring-data-gemfire/blob/master/src/main/java/org/springframework/data/gemfire/repository/config/EnableGemfireRepositories.java[single annotation]. +https://github.com/spring-projects/spring-data-gemfire[Spring Data Gemfire] provides +convenient Spring-friendly tools for accessing the http://www.gopivotal.com/big-data/pivotal-gemfire#details[Pivotal Gemfire] +data management platform. There is a `spring-boot-starter-data-gemfire` ``Starter POM'' +for collecting the dependencies in a convenient way. There is currently no auto=config +support for Gemfire, but you can enable Spring Data Repositories with a +https://github.com/spring-projects/spring-data-gemfire/blob/master/src/main/java/org/springframework/data/gemfire/repository/config/EnableGemfireRepositories.java[single annotation]. [[boot-features-solr]] === Solr -http://lucene.apache.org/solr/[Apache Solr] is a search engine. Spring Boot offers basic autoconfiguration for the solr client library and abstractions on top of it provided by https://github.com/spring-projects/spring-data-elasticsearch[Spring Data Solr]. There is a `spring-boot-starter-data-solr` ``Starter POM`` for collecting the dependencies in a convenient way. +http://lucene.apache.org/solr/[Apache Solr] is a search engine. Spring Boot offers basic +auto-configuration for the solr client library and abstractions on top of it provided by +https://github.com/spring-projects/spring-data-elasticsearch[Spring Data Solr]. There is +a `spring-boot-starter-data-solr` ``Starter POM'' for collecting the dependencies in a +convenient way. + + [[boot-features-connecting-to-solr]] ==== Connecting to Solr -You can inject an auto-configured `SolrServer` instance as you would any other -Spring Bean. By default the instance will attempt to connect to a server using +You can inject an auto-configured `SolrServer` instance as you would any other Spring +Bean. By default the instance will attempt to connect to a server using `http://localhost:8983/solr`: [source,java,indent=0] @@ -1604,7 +1626,7 @@ Spring Bean. By default the instance will attempt to connect to a server using @Component public class MyBean { - private SolrServer solr; + private SolrServer solr; @Autowired public MyBean(SolrServer solr) { @@ -1618,39 +1640,48 @@ Spring Bean. By default the instance will attempt to connect to a server using If you add a `@Bean` of your own of type `SolrServer` it will replace the default. + + [[boot-features-spring-data-solr-repositories]] ==== Spring Data Solr repositories Spring Data includes repository support for Apache Solr. As with the JPA repositories discussed earlier, the basic principle is that queries are constructed for you automatically based on method names. -In fact, both Spring Data JPA and Spring Data Solr share the same common -infrastructure; so you could take the JPA example from earlier and, assuming that -`City` is now a `@SolrDocument` class rather than a JPA `@Entity`, it will work in the -same way. +In fact, both Spring Data JPA and Spring Data Solr share the same common infrastructure; +so you could take the JPA example from earlier and, assuming that `City` is now a +`@SolrDocument` class rather than a JPA `@Entity`, it will work in the same way. + +TIP: For complete details of Spring Data Solr, refer to their +http://projects.spring.io/spring-data-solr/[reference documentation]. -TIP: For complete details of Spring Data Solr, including its rich object mapping -technologies, refer to their http://projects.spring.io/spring-data-solr/[reference -documentation]. [[boot-features-elasticsearch]] === Elasticsearch -http://www.elasticsearch.org/[Elastic Search] is a search engine. Spring Boot offers basic autoconfiguration for the solr client library and abstractions on top of it provided by [Spring Data Solr](https://github.com/spring-projects/spring-data-elasticsearch). There is a `spring-boot-starter-data-elasticsearch` ``Starter POM`` for collecting the dependencies in a convenient way. +http://www.elasticsearch.org/[Elastic Search] is an open source, distributed, +real-time search and analytics engine. Spring Boot offers basic auto-configuration for +the Elasticsearch and abstractions on top of it provided by +[Spring Data Elasticsearch](https://github.com/spring-projects/spring-data-elasticsearch). +There is a `spring-boot-starter-data-elasticsearch` ``Starter POM'' for collecting the +dependencies in a convenient way. + + [[boot-features-connecting-to-elasticsearch]] ==== Connecting to Elasticsearch -You can inject an auto-configured `ElasticsearchTemplate` or Elasticsearch `Client` instance as you would any other -Spring Bean. By default the instance will attempt to connect to a local in-memory server (a `NodeClient` in Elasticsearch -terms), but you can switch to a remote server (i.e. a `TransportClient`) by setting `spring.data.elasticsearch.clusterNodes` -to a comma-separated "host:port" list. +You can inject an auto-configured `ElasticsearchTemplate` or Elasticsearch `Client` +instance as you would any other Spring Bean. By default the instance will attempt to +connect to a local in-memory server (a `NodeClient` in Elasticsearch terms), but you can +switch to a remote server (i.e. a `TransportClient`) by setting +`spring.data.elasticsearch.clusterNodes` to a comma-separated "host:port" list. [source,java,indent=0] ---- @Component public class MyBean { - private ElasticsearchTemplate template; + private ElasticsearchTemplate template; @Autowired public MyBean(ElasticsearchTemplate template) { @@ -1662,7 +1693,10 @@ to a comma-separated "host:port" list. } ---- -If you add a `@Bean` of your own of type `ElasticsearchTemplate` it will replace the default. +If you add a `@Bean` of your own of type `ElasticsearchTemplate` it will replace the +default. + + [[boot-features-spring-data-elasticsearch-repositories]] ==== Spring Data Elasticsearch repositories @@ -1672,64 +1706,65 @@ automatically based on method names. In fact, both Spring Data JPA and Spring Data Elasticsearch share the same common infrastructure; so you could take the JPA example from earlier and, assuming that -`City` is now an Elasticsearch `@Document` class rather than a JPA `@Entity`, it will work in the -same way. +`City` is now an Elasticsearch `@Document` class rather than a JPA `@Entity`, it will +work in the same way. + +TIP: For complete details of Spring Data Elasticsearch, refer to their +http://projects.spring.io/spring-data-elasticsearch/[reference documentation]. + -TIP: For complete details of Spring Data Elasticsearch, including its rich object mapping -technologies, refer to their http://projects.spring.io/spring-data-elasticsearch/[reference -documentation]. [[boot-features-messaging]] == Messaging +The Spring Framework provides extensive support for integrating with messaging systems: +from simplified use of the JMS API using `JmsTemplate` to a complete infrastructure to +receive messages asynchronously. Spring AMQP provides a similar feature set for the +``Advanced Message Queuing Protocol'' and Boot also provides auto-configuration options +for `RabbitTemplate` and RabbitMQ. + -The Spring Framework provides extensive support for integrating with messaging -systems: from simplified use of the JMS API using `JmsTemplate` to a complete -infrastructure to receive messages asynchronously. Spring AMQP provides a similar -feature set for the ``Advanced Message Queuing Protocol'' and Boot also provides -auto-configuration options for `RabbitTemplate` and RabbitMQ. [[boot-features-integration]] == Spring Integration - -Spring Integration provides abstractions over messaging and also other -transports such as HTTP, TCP etc. If Spring Integration is available -on your classpath it will be initialized through the `@EnableIntegration` -annotation. Message processing statistics will be published over JMX if -``spring-integration-jmx'' is also on the classpath. +Spring Integration provides abstractions over messaging and also other transports such as +HTTP, TCP etc. If Spring Integration is available on your classpath it will be initialized +through the `@EnableIntegration` annotation. Message processing statistics will be +published over JMX if ``spring-integration-jmx'' is also on the classpath. See the {sc-spring-boot-autoconfigure}/integration/IntegrationAutoConfiguration.{sc-ext}[`IntegrationAutoConfiguration`] class for more details. -[[boot-features-jms]] -== JMS -The `javax.jms.ConnectionFactory` interface provides a standard method of -creating a `javax.jms.Connection` to interact with a JMS broker. In practice, -you don't need to handle that yourself even if the `ConnectionFactory` is a -central piece of the JMS infrastructure as most of the higher-level JMS -components require a `ConnectionFactory` to operate. + +[[boot-features-jms]] +=== JMS +The `javax.jms.ConnectionFactory` interface provides a standard method of creating a +`javax.jms.Connection` for interacting with a JMS broker. Although Spring needs a +`ConnectionFactory` to work with JMS, you generally won't need to use it directly yourself +and you can instead rely on higher level messaging abstractions (see the +{spring-reference}/#jms[relevant section] of the Spring Framework reference +documentation for details). + [[boot-features-hornetq]] -=== HornetQ support +==== HornetQ support +Spring Boot can auto-configure a `ConnectionFactory` when it detects that HornetQ is +available on the classpath. If the broker is present, an embedded broker is started and +configured automatically (unless the mode property has been explicitly set). The supported +modes are: `embedded` (to make explicit that an embedded broker is required and should +lead to an error if the broker is not available in the classpath), and `native` to +connect to a broker using the the `netty` transport protocol. When the latter is +configured, Spring Boot configures a `ConnectionFactory` connecting to a broker running +on the local machine with the default settings. -Spring Boot can auto-configure a `ConnectionFactory` when it detects that -HornetQ is available on the classpath. If the broker is present, an embedded -broker is started and configured automatically unless the mode property has -been explicitly set. The supported modes are: `embedded` (to make explicit -that an embedded broker is required and should lead to an error if the broker -is not available in the classpath), and `native` to connect to a broker -using the the `netty` transport protocol. When the latter is configured, boot -configures a `ConnectionFactory` connecting to a broker running on the local -machine with the default settings. - -NOTE: if you are using `spring-boot-starter-hornetq` the necessary dependencies -to connect to an existing HornetQ instance are provided, as well as the Spring -infrastructure to integrate with JMS. Adding `org.hornetq:hornetq-jms-server` -to your application allows you to use the embedded mode. +NOTE: if you are using `spring-boot-starter-hornetq` the necessary dependencies to +connect to an existing HornetQ instance are provided, as well as the Spring infrastructure +to integrate with JMS. Adding `org.hornetq:hornetq-jms-server` to your application allows +you to use the embedded mode. HornetQ configuration is controlled by external configuration properties in -`spring.hornetq.*`. For example, you might declare the following section -in `application.properties`: +`spring.hornetq.*`. For example, you might declare the following section in +`application.properties`: [source,properties,indent=0] ---- @@ -1738,31 +1773,31 @@ in `application.properties`: spring.hornetq.port=9876 ---- -When embedding the broker, you can chose if you want to enable persistence and -the list of destinations that should be made available. These can be specified -as a comma separated list to create them with the default options or you can -define bean(s) of type `org.hornetq.jms.server.config.JMSQueueConfiguration` -or `org.hornetq.jms.server.config.TopicConfiguration`, for advanced queue and -topic configurations respectively. +When embedding the broker, you can chose if you want to enable persistence, and the list +of destinations that should be made available. These can be specified as a comma separated +list to create them with the default options; or you can define bean(s) of type +`org.hornetq.jms.server.config.JMSQueueConfiguration` or +`org.hornetq.jms.server.config.TopicConfiguration`, for advanced queue and topic +configurations respectively. See {sc-spring-boot-autoconfigure}/jms/hornetq/HornetQProperties.{sc-ext}[`HornetQProperties`] for more of the supported options. -No JNDI lookup is involved at all and destinations are resolved against their -names, either using the ``name'' attribute in the HornetQ configuration or the -names provided through configuration. +No JNDI lookup is involved at all and destinations are resolved against their names, +either using the ``name'' attribute in the HornetQ configuration or the names provided +through configuration. + + [[boot-features-activemq]] -=== ActiveMQ support - -Spring Boot can also configure a `ConnectionFactory` when it detects that -ActiveMQ is available on the classpath. If the broker is present, -an embedded broker is started and configured automatically if no broker URL -is specified through configuration. +==== ActiveMQ support +Spring Boot can also configure a `ConnectionFactory` when it detects that ActiveMQ is +available on the classpath. If the broker is present, an embedded broker is started and +configured automatically (as long as no broker URL is specified through configuration). ActiveMQ configuration is controlled by external configuration properties in -`spring.activemq.*`. For example, you might declare the following section -in `application.properties`: +`spring.activemq.*`. For example, you might declare the following section in +`application.properties`: [source,properties,indent=0] ---- @@ -1774,13 +1809,15 @@ in `application.properties`: See {sc-spring-boot-autoconfigure}/jms/activemq/ActiveMQProperties.{sc-ext}[`ActiveMQProperties`] for more of the supported options. -By default, ActiveMQ creates a destination if it does not exist yet so destinations -are resolved against their provided names. +By default, ActiveMQ creates a destination if it does not exist yet, so destinations are +resolved against their provided names. + + [[boot-features-using-jms-template]] -=== Using JmsTemplate -Spring's `JmsTemplate` is auto-configured and you can `@Autowire` it directly -into your own beans: +==== Using JmsTemplate +Spring's `JmsTemplate` is auto-configured and you can `@Autowire` it directly into your +own beans: [source,java,indent=0] ---- @@ -1803,18 +1840,20 @@ into your own beans: } ---- + + [[boot-features-jmx]] == Monitoring and management over JMX - -Java Management Extensions (JMX) provide a standard mechanism to -monitor and manage applications. By default Spring Boot will create an -`MBeanServer` with bean id "mbeanServer" and expose any of your beans -that are annotated with Spring JMX annotations (`@ManagedResource`, -`@ManagedAttribute`, `@ManagedOperation`). +Java Management Extensions (JMX) provide a standard mechanism to monitor and manage +applications. By default Spring Boot will create an `MBeanServer` with bean id +``mbeanServer'' and expose any of your beans that are annotated with Spring JMX +annotations (`@ManagedResource`, `@ManagedAttribute`, `@ManagedOperation`). See the {sc-spring-boot-autoconfigure}/jmx/JmxAutoConfiguration.{sc-ext}[`JmxAutoConfiguration`] class for more details. + + [[boot-features-testing]] == Testing Spring Boot provides a number of useful tools for testing your application. The