mirror of
https://github.com/spring-projects/spring-boot.git
synced 2024-07-15 01:07:30 +08:00
More updated howtos
This commit is contained in:
Dave Syer
parent
19fa5b9af6
commit
e28e6d9593
156
docs/howto.md
156
docs/howto.md
@ -40,6 +40,22 @@ Javadocs. Some rules of thumb:
|
||||
* Look for `@ConditionalOnExpression` annotations that switch features
|
||||
on and off in response to SpEL expressions, normally evaluated with
|
||||
placeholders resolved from the `Environment`.
|
||||
|
||||
## Add a Servlet, Filter or ServletContextListener to an Application
|
||||
|
||||
`Servlet`, `Filter`, `ServletContextListener` and the other listeners
|
||||
supported by the Servlet spec can be added to your application as
|
||||
`@Bean` definitions. Be very careful that they don't cause eager
|
||||
initialization of too many other beans because they have to be
|
||||
installed in th container very early in the application lifecycle
|
||||
(e.g. it's not a good idea to have them depend on your `DataSource` or
|
||||
JPA configuration). You can work around restrictions like that by
|
||||
initializing them lazily when first used instead of on initialization.
|
||||
|
||||
In the case of `Filters` and `Servlets` you can also add mappings and
|
||||
init parameters by adding a `FilterRegistrationBean` or
|
||||
`ServletRegistrationBean` instead of or as well as the underlying
|
||||
component.
|
||||
|
||||
## Configure Tomcat
|
||||
|
||||
@ -62,6 +78,45 @@ are quite rich so once you have access to the
|
||||
of ways. Or the nuclear option is to add your own
|
||||
`JettyEmbeddedServletContainerFactory`.
|
||||
|
||||
## Terminate SSL in Tomcat
|
||||
|
||||
Add a `EmbeddedServletContainerCustomizer` and in that add a
|
||||
`TomcatConnectorCustomizer` that sets up the connector to be secure:
|
||||
|
||||
```java
|
||||
@Bean
|
||||
public EmbeddedServletContainerCustomizer containerCustomizer(){
|
||||
return new EmbeddedServletContainerCustomizer() {
|
||||
@Override
|
||||
public void customize(ConfigurableEmbeddedServletContainerFactory factory) {
|
||||
if(factory instanceof TomcatEmbeddedServletContainerFactory){
|
||||
TomcatEmbeddedServletContainerFactory containerFactory = (TomcatEmbeddedServletContainerFactory) factory;
|
||||
containerFactory.addConnectorCustomizers(new TomcatConnectorCustomizer() {
|
||||
|
||||
@Override
|
||||
public void customize(Connector connector) {
|
||||
|
||||
connector.setPort(serverPort);
|
||||
connector.setSecure(true);
|
||||
connector.setScheme("https");
|
||||
connector.setAttribute("keyAlias", "tomcat");
|
||||
connector.setAttribute("keystorePass", "password");
|
||||
try {
|
||||
connector.setAttribute("keystoreFile", ResourceUtils.getFile("src/ssl/tomcat.keystore").getAbsolutePath());
|
||||
} catch (FileNotFoundException e) {
|
||||
throw new IllegalStateException("Cannot load keystore", e);
|
||||
}
|
||||
connector.setAttribute("clientAuth", "false");
|
||||
connector.setAttribute("sslProtocol", "TLS");
|
||||
connector.setAttribute("SSLEnabled", true);
|
||||
|
||||
});
|
||||
}
|
||||
}
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Reload Static Content (E.g. Thymeleaf Templates) Without Restarting the Container
|
||||
|
||||
If you are using Thymeleaf, then set
|
||||
@ -195,7 +250,6 @@ Applications that are not already Spring applications might be
|
||||
convertible to a Spring Boot application, and the guidance above might
|
||||
help, but your mileage may vary.
|
||||
|
||||
|
||||
## Serve Static Content
|
||||
|
||||
Spring Boot by default will serve static content from a folder called
|
||||
@ -252,6 +306,23 @@ For more detail look at the
|
||||
[`ManagementServerProperties`](https://github.com/spring-projects/spring-boot/blob/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/properties/ManagementServerProperties.java?source=c)
|
||||
source code.
|
||||
|
||||
## Customize "Whitelabel" Error Page
|
||||
|
||||
The Actuator installs a "whitelabel" error page that you will see in
|
||||
browser client if you encounter a server error (machine clients
|
||||
consuming JSON and other media types should see a sensible response
|
||||
with the right error code). To switch it off you can set
|
||||
`error.whitelabel.enabled=false`, but normally in addition or
|
||||
alternatively to that you will want to add your own error page
|
||||
replacing the whitelabel one. If you are using Thymeleaf you can do
|
||||
this by adding an "error.html" template. In general what you need is a
|
||||
`View` that resolves with a name of "error", and/or a `@Controller`
|
||||
that handles the "/error" path. Unless you replaced some of the
|
||||
default configuration you should find a `BeanNameViewResolver` in your
|
||||
`ApplicationContext` so a `@Bean` with id "error" would be a simple
|
||||
way of doing that. Look at `ErrorMvcAutoConfiguration` for more
|
||||
options.
|
||||
|
||||
## Use 'Short' Command Line Arguments
|
||||
|
||||
Some people like to use (for example) `--port=9000` instead of
|
||||
@ -361,6 +432,89 @@ to load an `ApplicationContext` via a `DispatcherServlet`.
|
||||
|
||||
TODO: add some detail.
|
||||
|
||||
## Configure a DataSource
|
||||
|
||||
Spring Boot will create a `DataSource` for you if you have
|
||||
`spring-jdbc` and some other things on the classpath. 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 neither of those is available but an embedded database is then we
|
||||
create one of those for you (preference order is h2, then Apache
|
||||
Derby, then hsqldb).
|
||||
|
||||
The pooling `DataSource` option is controlled by external
|
||||
configuration properties in `spring.datasource.*` for example:
|
||||
|
||||
```properties
|
||||
spring.datasource.url: jdbc:mysql://localhost/test
|
||||
spring.datasource.username: root
|
||||
spring.datasource.password:
|
||||
spring.datasource.driverClassName: com.mysql.jdbc.Driver
|
||||
```
|
||||
|
||||
The `@ConfigurationProperties` for `spring.datasource` are defined in
|
||||
`AbstractDataSourceConfiguration` (so see there for more options).
|
||||
|
||||
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.
|
||||
|
||||
To override the default settings just define a `@Bean` of your own of
|
||||
type `DataSource`. See
|
||||
[`DataSourceAutoConfiguration`]((https://github.com/spring-projects/spring-boot/blob/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/jdbc/DataSourceAutoConfiguration.java))
|
||||
for more details.
|
||||
|
||||
## Use Spring Data Repositories
|
||||
|
||||
Spring Data can create implementations for you of `@Repository`
|
||||
interfaces of various flavours. Spring Boot will handle all of that
|
||||
for you as long as those `@Repositories` are included in a
|
||||
`@ComponentScan`.
|
||||
|
||||
For many applications all you will need is to put the right Spring
|
||||
Data dependencies on your classpath (there is a
|
||||
"spring-boot-starter-data-jpa" for JPA and for Mongodb you only nee
|
||||
dto add "spring-datamongodb"), create some repository interfaces to
|
||||
handle your `@Entity` objects, and then add a `@ComponentScan` that
|
||||
covers those packages. Examples are in the
|
||||
[JPA sample](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-samples/spring-boot-sample-data-jpa)
|
||||
or the
|
||||
[Mongodb sample](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-samples/spring-boot-sample-data-mongodb).
|
||||
|
||||
## Configure JPA Properties
|
||||
|
||||
Spring JPA already provides some vendor-independent configuration
|
||||
options (e.g. for SQL logging) and Spring Boot exposes those, and a
|
||||
few more for hibernate as external configuration properties. The most
|
||||
common options to set are
|
||||
|
||||
```properties
|
||||
spring.jpa.hibernate.ddl-auto: create-drop
|
||||
spring.jpa.hibernate.naming_strategy: org.hibernate.cfg.ImprovedNamingStrategy
|
||||
spring.jpa.database: H2
|
||||
spring.jpa.show-sql: true
|
||||
```
|
||||
|
||||
(Because of relaxed data binding hyphens or underscores should work
|
||||
equally well as property keys.) The `ddl-auto` setting is a special
|
||||
case in that it has different defaults depending on whether you are
|
||||
using an embedded database ("create-drop") or not ("none"). In
|
||||
addition all properties in `spring.jpa.properties.*` are passed
|
||||
through as normal JPA properties (with the prefix stripped) when the
|
||||
local `EntityManagerFactory` is created.
|
||||
|
||||
See
|
||||
[`HibernateJpaAutoConfiguration`](https://github.com/spring-projects/spring-boot/blob/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/orm/jpa/HibernateJpaAutoConfiguration.java)
|
||||
and
|
||||
[`JpaBaseConfiguration`](https://github.com/spring-projects/spring-boot/blob/master/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/orm/jpa/JpaBaseConfiguration.java)
|
||||
for more details.
|
||||
|
||||
<span id="discover.options"/>
|
||||
## Discover Built-in Options for External Properties
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user