From e28e6d9593da1ac81d97977b29167666b06870d5 Mon Sep 17 00:00:00 2001 From: Dave Syer Date: Fri, 29 Nov 2013 09:46:10 +0000 Subject: [PATCH] More updated howtos --- docs/howto.md | 156 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 155 insertions(+), 1 deletion(-) diff --git a/docs/howto.md b/docs/howto.md index 31c6a06a981..c802fd3f22a 100644 --- a/docs/howto.md +++ b/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. + ## Discover Built-in Options for External Properties