Skip to content

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

Polish documentation 

Apply consistent styling and edit a few section for clarity.
parent e032b673
Show whitespace changes
Inline Side-by-side
Showing with 182 additions and 136 deletions
spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc
View file @ 62d2b413
......@@ -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
#!/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
else
kill $PID
fi
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
......
spring-boot-docs/src/main/asciidoc/production-ready-features.adoc
View file @ 62d2b413
......@@ -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
****
......
spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
View file @ 62d2b413
......@@ -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
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,20 +1430,29 @@ 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]
----
......@@ -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]
......@@ -1618,32 +1640,41 @@ 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]
----
......@@ -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
=== 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).
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-hornetq]]
=== 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, 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.
==== 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.
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.
[[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 (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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment