From a9240e0bac4d71792bc22642093cbda86ed82f85 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Wed, 24 Feb 2021 17:18:04 +0100 Subject: [PATCH] Document all supported SpringProperties keys in the reference manual Closes gh-26554 --- src/docs/asciidoc/appendix.adoc | 84 ++++++++++++++++++++ src/docs/asciidoc/core/core-beans.adoc | 23 +++--- src/docs/asciidoc/core/core-expressions.adoc | 16 ++-- src/docs/asciidoc/data-access.adoc | 11 +-- src/docs/asciidoc/index.adoc | 1 + src/docs/asciidoc/testing.adoc | 6 +- 6 files changed, 114 insertions(+), 27 deletions(-) create mode 100644 src/docs/asciidoc/appendix.adoc diff --git a/src/docs/asciidoc/appendix.adoc b/src/docs/asciidoc/appendix.adoc new file mode 100644 index 00000000000..4de25e06451 --- /dev/null +++ b/src/docs/asciidoc/appendix.adoc @@ -0,0 +1,84 @@ +[[appendix]] += Appendix +:doc-root: https://docs.spring.io +:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework +:toc: left +:toclevels: 4 +:tabsize: 4 +:docinfo1: + +This part of the reference documentation covers topics that apply to multiple modules +within the core Spring Framework. + + +[[appendix-spring-properties]] +== Spring Properties + +{api-spring-framework}/core/SpringProperties.html[`SpringProperties`] is a static holder +for properties that control certain low-level aspects of the Spring Framework. Users can +configure these properties via JVM system properties or programmatically via the +`SpringProperties.setProperty(String key, String value)` method. The latter may be +necessary if the deployment environment disallows custom JVM system properties. As an +alternative, these properties may be configured in a `spring.properties` file in the root +of the classpath -- for example, deployed within the application's JAR file. + +The following table lists all currently supported Spring properties. + +.Supported Spring Properties +|=== +| Name | Description + +| `spring.beaninfo.ignore` +| Instructs Spring to use the `Introspector.IGNORE_ALL_BEANINFO` mode when calling the +JavaBeans `Introspector`. See +{api-spring-framework}++/beans/CachedIntrospectionResults.html#IGNORE_BEANINFO_PROPERTY_NAME++[`CachedIntrospectionResults`] +for details. + +| `spring.expression.compiler.mode` +| The mode to use when compiling expressions for the +<>. + +| `spring.getenv.ignore` +| Instructs Spring to ignore operating system environment variables if a Spring +`Environment` property -- for example, a placeholder in a configuration String -- isn't +resolvable otherwise. See +{api-spring-framework}++/core/env/AbstractEnvironment.html#IGNORE_GETENV_PROPERTY_NAME++[`AbstractEnvironment`] +for details. + +| `spring.index.ignore` +| Instructs Spring to ignore the components index located in +`META-INF/spring.components`. See <>. + +| `spring.jdbc.getParameterType.ignore` +| Instructs Spring to ignore `java.sql.ParameterMetaData.getParameterType` completely. +See the note in <>. + +| `spring.jndi.ignore` +| Instructs Spring to ignore a default JNDI environment, as an optimization for scenarios +where nothing is ever to be found for such JNDI fallback searches to begin with, avoiding +the repeated JNDI lookup overhead. See +{api-spring-framework}++/jndi/JndiLocatorDelegate.html#IGNORE_JNDI_PROPERTY_NAME++[`JndiLocatorDelegate`] +for details. + +| `spring.objenesis.ignore` +| Instructs Spring to ignore Objenesis, not even attempting to use it. See +{api-spring-framework}++/objenesis/SpringObjenesis.html#IGNORE_OBJENESIS_PROPERTY_NAME++[`SpringObjenesis`] +for details. + +| `spring.test.constructor.autowire.mode` +| The default _test constructor autowire mode_ to use if `@TestConstructor` is not present +on a test class. See <>. + +| `spring.test.context.cache.maxSize` +| The maximum size of the context cache in the _Spring TestContext Framework_. See +<>. + +| `spring.test.enclosing.configuration` +| The default _enclosing configuration inheritance mode_ to use if +`@NestedTestConfiguration` is not present on a test class. See +<>. + +|=== diff --git a/src/docs/asciidoc/core/core-beans.adoc b/src/docs/asciidoc/core/core-beans.adoc index 84ee7990c50..f64fbd36d1e 100644 --- a/src/docs/asciidoc/core/core-beans.adoc +++ b/src/docs/asciidoc/core/core-beans.adoc @@ -7120,10 +7120,10 @@ metadata is provided per-instance rather than per-class. While classpath scanning is very fast, it is possible to improve the startup performance of large applications by creating a static list of candidates at compilation time. In this -mode, all modules that are target of component scan must use this mechanism. +mode, all modules that are targets of component scanning must use this mechanism. -NOTE: Your existing `@ComponentScan` or `` directives must remain +unchanged to request the context to scan candidates in certain packages. When the `ApplicationContext` detects such an index, it automatically uses it rather than scanning the classpath. @@ -7152,12 +7152,10 @@ configuration, as shown in the following example: compileOnly "org.springframework:spring-context-indexer:{spring-version}" } ---- -==== With Gradle 4.6 and later, the dependency should be declared in the `annotationProcessor` configuration, as shown in the following example: -==== [source,groovy,indent=0subs="verbatim,quotes,attributes"] ---- dependencies { @@ -7165,19 +7163,20 @@ configuration, as shown in the following example: } ---- -That process generates a `META-INF/spring.components` file that is -included in the jar file. +The `spring-context-indexer` artifact generates a `META-INF/spring.components` file that +is included in the jar file. NOTE: When working with this mode in your IDE, the `spring-context-indexer` must be registered as an annotation processor to make sure the index is up-to-date when candidate components are updated. -TIP: The index is enabled automatically when a `META-INF/spring.components` is found +TIP: The index is enabled automatically when a `META-INF/spring.components` file is found on the classpath. If an index is partially available for some libraries (or use cases) -but could not be built for the whole application, you can fallback to a regular classpath -arrangement (as though no index was present at all) by setting `spring.index.ignore` to -`true`, either as a system property or in a `spring.properties` file at the root of the -classpath. +but could not be built for the whole application, you can fall back to a regular classpath +arrangement (as though no index were present at all) by setting `spring.index.ignore` to +`true`, either as a JVM system property or via the +<> mechanism. + diff --git a/src/docs/asciidoc/core/core-expressions.adoc b/src/docs/asciidoc/core/core-expressions.adoc index 5a1399dd831..d445738f513 100644 --- a/src/docs/asciidoc/core/core-expressions.adoc +++ b/src/docs/asciidoc/core/core-expressions.adoc @@ -433,9 +433,9 @@ interpreter and only 3ms using the compiled version of the expression. The compiler is not turned on by default, but you can turn it on in either of two different ways. You can turn it on by using the parser configuration process -(<>) or by using a system -property when SpEL usage is embedded inside another component. This section -discusses both of these options. +(<>) or by using a Spring property +when SpEL usage is embedded inside another component. This section discusses both of +these options. The compiler can operate in one of three modes, which are captured in the `org.springframework.expression.spel.SpelCompilerMode` enum. The modes are as follows: @@ -496,10 +496,12 @@ It is important to ensure that, if a classloader is specified, it can see all th the expression evaluation process. If you do not specify a classloader, a default classloader is used (typically the context classloader for the thread that is running during expression evaluation). -The second way to configure the compiler is for use when SpEL is embedded inside some other -component and it may not be possible to configure it through a configuration object. In these -cases, it is possible to use a system property. You can set the `spring.expression.compiler.mode` -property to one of the `SpelCompilerMode` enum values (`off`, `immediate`, or `mixed`). +The second way to configure the compiler is for use when SpEL is embedded inside some +other component and it may not be possible to configure it through a configuration +object. In these cases, it is possible to set the `spring.expression.compiler.mode` +property via a JVM system property (or via the +<> mechanism) to one of the +`SpelCompilerMode` enum values (`off`, `immediate`, or `mixed`). [[expressions-compiler-limitations]] diff --git a/src/docs/asciidoc/data-access.adoc b/src/docs/asciidoc/data-access.adoc index 0dc692dad16..104eb810ba4 100644 --- a/src/docs/asciidoc/data-access.adoc +++ b/src/docs/asciidoc/data-access.adoc @@ -4463,13 +4463,14 @@ While this usually works well, there is a potential for issues (for example, wit `null` values). Spring, by default, calls `ParameterMetaData.getParameterType` in such a case, which can be expensive with your JDBC driver. You should use a recent driver version and consider setting the `spring.jdbc.getParameterType.ignore` property to `true` -(as a JVM system property or in a `spring.properties` file in the root of your classpath) -if you encounter a performance issue (as reported on Oracle 12c, JBoss and PostgreSQL). +(as a JVM system property or via the +<> mechanism) if you encounter +a performance issue (as reported on Oracle 12c, JBoss, and PostgreSQL). Alternatively, you might consider specifying the corresponding JDBC types explicitly, -either through a 'BatchPreparedStatementSetter' (as shown earlier), through an explicit type -array given to a 'List' based call, through 'registerSqlType' calls on a -custom 'MapSqlParameterSource' instance, or through a 'BeanPropertySqlParameterSource' +either through a `BatchPreparedStatementSetter` (as shown earlier), through an explicit type +array given to a `List` based call, through `registerSqlType` calls on a +custom `MapSqlParameterSource` instance, or through a `BeanPropertySqlParameterSource` that derives the SQL type from the Java-declared property type even for a null value. ==== diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc index 3c1e2673ab5..cb2901e8ce4 100644 --- a/src/docs/asciidoc/index.adoc +++ b/src/docs/asciidoc/index.adoc @@ -24,6 +24,7 @@ WebSocket, RSocket. <> :: Remoting, JMS, JCA, JMX, Email, Tasks, Scheduling, Caching. <> :: Kotlin, Groovy, Dynamic Languages. +<> :: miscellaneous topics. Rod Johnson, Juergen Hoeller, Keith Donald, Colin Sampaleanu, Rob Harrop, Thomas Risberg, Alef Arendsen, Darren Davison, Dmitriy Kopylenko, Mark Pollack, Thierry Templier, Erwin diff --git a/src/docs/asciidoc/testing.adoc b/src/docs/asciidoc/testing.adoc index c8ca05c3d1d..724dd4fa16b 100644 --- a/src/docs/asciidoc/testing.adoc +++ b/src/docs/asciidoc/testing.adoc @@ -1847,7 +1847,7 @@ constructor takes precedence over both `@TestConstructor` and the default mode. The default _test constructor autowire mode_ can be changed by setting the `spring.test.constructor.autowire.mode` JVM system property to `all`. Alternatively, the default mode may be set via the -{api-spring-framework}/core/SpringProperties.html[`SpringProperties`] mechanism. +<> mechanism. As of Spring Framework 5.3, the default mode may also be configured as a https://junit.org/junit5/docs/current/user-guide/#running-tests-config-params[JUnit Platform configuration parameter]. @@ -1880,7 +1880,7 @@ change the default mode. The default _enclosing configuration inheritance mode_ is `INHERIT`, but it can be changed by setting the `spring.test.enclosing.configuration` JVM system property to `OVERRIDE`. Alternatively, the default mode may be set via the -{api-spring-framework}/core/SpringProperties.html[`SpringProperties`] mechanism. +<> mechanism. ===== The <> honors `@NestedTestConfiguration` semantics for the @@ -4567,7 +4567,7 @@ maximum size is reached, a least recently used (LRU) eviction policy is used to close stale contexts. You can configure the maximum size from the command line or a build script by setting a JVM system property named `spring.test.context.cache.maxSize`. As an alternative, you can set the same property via the -{api-spring-framework}/core/SpringProperties.html[`SpringProperties`] mechanism. +<> mechanism. Since having a large number of application contexts loaded within a given test suite can cause the suite to take an unnecessarily long time to run, it is often beneficial to