From bd6d974561ad8ab8c31cd513d3816078c2b521ca Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Sat, 7 Mar 2015 07:30:52 +0100 Subject: [PATCH] Fix Admonition syntax The upgrade to a more recent asciidoc format led to a bunch of of broken Admonition as the text block now requires four equal signs while previous versions tolerated only 3. Issue: SPR-12791 --- src/asciidoc/core-aop-api.adoc | 72 +++++++++---------- src/asciidoc/core-aop.adoc | 108 ++++++++++++++--------------- src/asciidoc/core-beans.adoc | 60 ++++++++-------- src/asciidoc/core-expressions.adoc | 4 +- src/asciidoc/testing.adoc | 44 ++++++------ src/asciidoc/web-mvc.adoc | 52 +++++++------- src/asciidoc/web-portlet.adoc | 4 +- 7 files changed, 172 insertions(+), 172 deletions(-) diff --git a/src/asciidoc/core-aop-api.adoc b/src/asciidoc/core-aop-api.adoc index 13402649be..a99af0d4d3 100644 --- a/src/asciidoc/core-aop-api.adoc +++ b/src/asciidoc/core-aop-api.adoc @@ -87,11 +87,11 @@ Most MethodMatchers are static, meaning that their `isRuntime()` method returns In this case, the 3-argument matches method will never be invoked. [TIP] -=== +==== If possible, try to make pointcuts static, allowing the AOP framework to cache the results of pointcut evaluation when an AOP proxy is created. -=== +==== @@ -211,11 +211,11 @@ current call stack. For example, it might fire if the join point was invoked by in the `com.mycompany.web` package, or by the `SomeCaller` class. Control flow pointcuts are specified using the `org.springframework.aop.support.ControlFlowPointcut` class. [NOTE] -=== +==== Control flow pointcuts are significantly more expensive to evaluate at runtime than even other dynamic pointcuts. In Java 1.4, the cost is about 5 times that of other dynamic pointcuts. -=== +==== @@ -252,10 +252,10 @@ pointcuts in Spring can be arbitrarily complex. However, using the AspectJ point expression language is recommended if possible. [NOTE] -=== +==== Later versions of Spring may offer support for "semantic pointcuts" as offered by JAC: for example, "all methods that change instance variables in the target object." -=== +==== @@ -334,7 +334,7 @@ return a different value or throw an exception rather than invoke the proceed me However, you don't want to do this without good reason! [NOTE] -=== +==== MethodInterceptors offer interoperability with other AOP Alliance-compliant AOP implementations. The other advice types discussed in the remainder of this section implement common AOP concepts, but in a Spring-specific way. While there is an advantage @@ -342,7 +342,7 @@ in using the most specific advice type, stick with MethodInterceptor around advi you are likely to want to run the aspect in another AOP framework. Note that pointcuts are not currently interoperable between frameworks, and the AOP Alliance does not currently define pointcut interfaces. -=== +==== [[aop-api-advice-before]] @@ -394,10 +394,10 @@ An example of a before advice in Spring, which counts all method invocations: ---- [TIP] -=== +==== Before advice can be used with any pointcut. -=== +==== [[aop-api-advice-throws]] @@ -466,7 +466,7 @@ methods can be combined in a single class. ---- [NOTE] -=== +==== If a throws-advice method throws an exception itself, it will override the original exception (i.e. change the exception thrown to the user). The overriding exception will typically be a RuntimeException; this is compatible with any method @@ -474,13 +474,13 @@ signature. However, if a throws-advice method throws a checked exception, it wil to match the declared exceptions of the target method and is hence to some degree coupled to specific target method signatures. __Do not throw an undeclared checked exception that is incompatible with the target method's signature!__ -=== +==== [TIP] -=== +==== Throws advice can be used with any pointcut. -=== +==== [[aop-api-advice-after-returning]] @@ -526,10 +526,10 @@ This advice doesn't change the execution path. If it throws an exception, this w thrown up the interceptor chain instead of the return value. [TIP] -=== +==== After returning advice can be used with any pointcut. -=== +==== [[aop-api-advice-introduction]] @@ -720,9 +720,9 @@ FactoryBeans. (Remember that a factory bean introduces a layer of indirection, e it to create objects of a different type.) [NOTE] -=== +==== The Spring AOP support also uses factory beans under the covers. -=== +==== The basic way to create an AOP proxy in Spring is to use the __org.springframework.aop.framework.ProxyFactoryBean__. This gives complete control over @@ -808,12 +808,12 @@ chooses to create one of either a JDK- and CGLIB-based proxy for a particular ta object (that is to be proxied). [NOTE] -=== +==== The behavior of the `ProxyFactoryBean` with regard to creating JDK- or CGLIB-based proxies changed between versions 1.2.x and 2.0 of Spring. The `ProxyFactoryBean` now exhibits similar semantics with regard to auto-detecting interfaces as those of the `TransactionProxyFactoryBean` class. -=== +==== If the class of a target object that is to be proxied (hereafter simply referred to as the target class) doesn't implement any interfaces, then a CGLIB-based proxy will be @@ -897,13 +897,13 @@ interceptor or advisors in the current factory. Advisors, interceptors, before, returning and throws advice objects can be used. The ordering of advisors is significant. [NOTE] -=== +==== You might be wondering why the list doesn't hold bean references. The reason for this is that if the ProxyFactoryBean's singleton property is set to false, it must be able to return independent proxy instances. If any of the advisors is itself a prototype, an independent instance would need to be returned, so it's necessary to be able to obtain an instance of the prototype from the factory; holding a reference isn't sufficient. -=== +==== The "person" bean definition above can be used in place of a Person implementation, as follows: @@ -1134,12 +1134,12 @@ which allow you to add other advice types such as before and throws advice. AdvisedSupport is the superclass of both ProxyFactory and ProxyFactoryBean. [TIP] -=== +==== Integrating AOP proxy creation with the IoC framework is best practice in most applications. We recommend that you externalize configuration from Java code with AOP, as in general. -=== +==== @@ -1215,7 +1215,7 @@ manipulating its advice: ---- [NOTE] -=== +==== It's questionable whether it's advisable (no pun intended) to modify advice on a business object in production, although there are no doubt legitimate usage cases. However, it can be very useful in development: for example, in tests. I have sometimes @@ -1223,7 +1223,7 @@ found it very useful to be able to add test code in the form of an interceptor o advice, getting inside a method invocation I want to test. (For example, the advice can get inside a transaction created for that method: for example, to run SQL to check that a database was correctly updated, before marking the transaction for roll back.) -=== +==== Depending on how you created the proxy, you can usually set a `frozen` flag, in which case the `Advised` `isFrozen()` method will return true, and any attempts to modify @@ -1460,13 +1460,13 @@ this example, or Hibernate, JDO or JDBC): ---- [TIP] -=== +==== If you require only declarative transaction management, using these generic XML definitions will result in Spring automatically proxying all classes or methods with transaction attributes. You won't need to work directly with AOP, and the programming model is similar to that of .NET ServicedComponents. -=== +==== This mechanism is extensible. It's possible to do auto-proxying based on custom attributes. You need to: @@ -1517,12 +1517,12 @@ local object. The same target is returned for each invocation (as you would expe Let's look at the standard target sources provided with Spring, and how you can use them. [TIP] -=== +==== When using a custom target source, your target will usually need to be a prototype rather than a singleton bean definition. This allows Spring to create a new target instance when required. -=== +==== @@ -1586,9 +1586,9 @@ application's classpath to use this feature. It's also possible to subclass pooling API. [NOTE] -=== +==== Commons Pool 1.5+ is also supported but deprecated as of Spring Framework 4.2. -=== +==== Sample configuration is shown below: @@ -1652,11 +1652,11 @@ The cast will look as follows: ---- [NOTE] -=== +==== Pooling stateless service objects is not usually necessary. We don't believe it should be the default choice, as most stateless objects are naturally thread safe, and instance pooling is problematic if resources are cached. -=== +==== Simpler pooling is available using auto-proxying. It's possible to set the TargetSources used by any auto-proxy creator. @@ -1706,7 +1706,7 @@ of target source: ---- [NOTE] -=== +==== ThreadLocals come with serious issues (potentially resulting in memory leaks) when incorrectly using them in a multi-threaded and multi-classloader environments. One should always consider wrapping a threadlocal in some other class and never directly use @@ -1716,7 +1716,7 @@ always remember to correctly set and unset (where the latter simply involved a c any case since not unsetting it might result in problematic behavior. Spring's ThreadLocal support does this for you and should always be considered in favor of using ThreadLocals without other proper handling code. -=== +==== diff --git a/src/asciidoc/core-aop.adoc b/src/asciidoc/core-aop.adoc index f248398dbd..c03fd3ce15 100644 --- a/src/asciidoc/core-aop.adoc +++ b/src/asciidoc/core-aop.adoc @@ -156,7 +156,7 @@ API: Spring AOP remains backward-compatible. See <> for a more complete discussion of the whys and wherefores of each style. -=== +==== @@ -210,10 +210,10 @@ for pointcut parsing and matching. The AOP runtime is still pure Spring AOP thou there is no dependency on the AspectJ compiler or weaver. [NOTE] -=== +==== Using the AspectJ compiler and weaver enables use of the full AspectJ language, and is discussed in <>. -=== +==== @@ -304,22 +304,22 @@ declarations. .Autodetecting aspects through component scanning [NOTE] -=== +==== You may register aspect classes as regular beans in your Spring XML configuration, or autodetect them through classpath scanning - just like any other Spring-managed bean. However, note that the __@Aspect__ annotation is __not__ sufficient for autodetection in the classpath: For that purpose, you need to add a separate __@Component__ annotation (or alternatively a custom stereotype annotation that qualifies, as per the rules of Spring's component scanner). -=== +==== .Advising aspects with other aspects? [NOTE] -=== +==== In Spring AOP, it is __not__ possible to have aspects themselves be the target of advice from other aspects. The __@Aspect__ annotation on a class marks it as an aspect, and hence excludes it from auto-proxying. -=== +==== @@ -404,7 +404,7 @@ between the proxy object itself (bound to '++this++') and the target object behi proxy (bound to '++target++'). [NOTE] -=== +==== Due to the proxy-based nature of Spring's AOP framework, protected methods are by definition __not__ intercepted, neither for JDK proxies (where this isn't applicable) nor for CGLIB proxies (where this is technically possible but not recommendable for AOP @@ -416,7 +416,7 @@ consider the use of Spring-driven <> instead Spring's proxy-based AOP framework. This constitutes a different mode of AOP usage with different characteristics, so be sure to make yourself familiar with weaving first before making a decision. -=== +==== Spring AOP also supports an additional PCD named '++bean++'. This PCD allows you to limit the matching of join points to a particular named Spring bean, or to a set of named @@ -435,7 +435,7 @@ to pick them out. As is the case with other pointcut designators, the '++bean++' be &&'ed, ||'ed, and ! (negated) too. [NOTE] -=== +==== Please note that the '++bean++' PCD is __only__ supported in Spring AOP - and __not__ in native AspectJ weaving. It is a Spring-specific extension to the standard PCDs that AspectJ defines. @@ -445,7 +445,7 @@ concept) rather than at the type level only (which is what weaving-based AOP is to). Instance-based pointcut designators are a special capability of Spring's proxy-based AOP framework and its close integration with the Spring bean factory, where it is natural and straightforward to identify specific beans by name. -=== +==== [[aop-pointcuts-combining]] @@ -666,10 +666,10 @@ Some examples of common pointcut expressions are given below. ---- [NOTE] -=== +==== 'this' is more commonly used in a binding form :- see the following section on advice for how to make the proxy object available in the advice body. -=== +==== * any join point (method execution only in Spring AOP) where the target object implements the `AccountService` interface: @@ -681,10 +681,10 @@ for how to make the proxy object available in the advice body. ---- [NOTE] -=== +==== 'target' is more commonly used in a binding form :- see the following section on advice for how to make the target object available in the advice body. -=== +==== * any join point (method execution only in Spring AOP) which takes a single parameter, and where the argument passed at runtime is `Serializable`: @@ -696,10 +696,10 @@ for how to make the target object available in the advice body. ---- [NOTE] -=== +==== 'args' is more commonly used in a binding form :- see the following section on advice for how to make the method arguments available in the advice body. -=== +==== Note that the pointcut given in this example is different to `execution(* *(java.io.Serializable))`: the args version matches if the argument passed at runtime is @@ -716,10 +716,10 @@ parameter of type `Serializable`. ---- [NOTE] -=== +==== '@target' can also be used in a binding form :- see the following section on advice for how to make the annotation object available in the advice body. -=== +==== * any join point (method execution only in Spring AOP) where the declared type of the target object has an `@Transactional` annotation: @@ -731,10 +731,10 @@ how to make the annotation object available in the advice body. ---- [NOTE] -=== +==== '@within' can also be used in a binding form :- see the following section on advice for how to make the annotation object available in the advice body. -=== +==== * any join point (method execution only in Spring AOP) where the executing method has an `@Transactional` annotation: @@ -746,10 +746,10 @@ how to make the annotation object available in the advice body. ---- [NOTE] -=== +==== '@annotation' can also be used in a binding form :- see the following section on advice for how to make the annotation object available in the advice body. -=== +==== * any join point (method execution only in Spring AOP) which takes a single parameter, and where the runtime type of the argument passed has the `@Classified` annotation: @@ -761,10 +761,10 @@ for how to make the annotation object available in the advice body. ---- [NOTE] -=== +==== '@args' can also be used in a binding form :- see the following section on advice for how to make the annotation object(s) available in the advice body. -=== +==== * any join point (method execution only in Spring AOP) on a Spring bean named '++tradeService++': @@ -893,11 +893,11 @@ declared using the `@AfterReturning` annotation: ---- [NOTE] -=== +==== Note: it is of course possible to have multiple advice declarations, and other members as well, all inside the same aspect. We're just showing a single advice declaration in these examples to focus on the issue under discussion at the time. -=== +==== Sometimes you need access in the advice body to the actual value that was returned. You can use the form of `@AfterReturning` that binds the return value for this: @@ -1025,7 +1025,7 @@ execute. The `proceed` method may also be called passing in an `Object[]` - the in the array will be used as the arguments to the method execution when it proceeds. [NOTE] -=== +==== The behavior of proceed when called with an Object[] is a little different than the behavior of proceed for around advice compiled by the AspectJ compiler. For around advice written using the traditional AspectJ language, the number of arguments passed to @@ -1039,7 +1039,7 @@ aspects written for Spring and using proceed with arguments with the AspectJ com and weaver. There is a way to write such aspects that is 100% compatible across both Spring AOP and AspectJ, and this is discussed in the following section on advice parameters. -=== +==== [source,java,indent=0] [subs="verbatim,quotes"] @@ -1273,11 +1273,11 @@ the "argNames" attribute: other words, you should encounter no difficulties building with this flag on. [NOTE] -=== +==== If an @AspectJ aspect has been compiled by the AspectJ compiler (ajc) even without the debug information then there is no need to add the argNames attribute as the compiler will retain the needed information. -=== +==== * If the code has been compiled without the necessary debug information, then Spring AOP will attempt to deduce the pairing of binding variables to parameters (for example, if @@ -1382,10 +1382,10 @@ you would write the following: [[aop-instantiation-models]] === Aspect instantiation models [NOTE] -=== +==== (This is an advanced topic, so if you are just starting out with AOP you can safely skip it until later.) -=== +==== By default there will be a single instance of each aspect within the application context. AspectJ calls this the singleton instantiation model. It is possible to define @@ -1555,14 +1555,14 @@ application context configuration). An `` element can contain pointc advisor, and aspect elements (note these must be declared in that order). [WARNING] -=== +==== The `` style of configuration makes heavy use of Spring's <> mechanism. This can cause issues (such as advice not being woven) if you are already using explicit auto-proxying via the use of `BeanNameAutoProxyCreator` or suchlike. The recommended usage pattern is to use either just the `` style, or just the `AutoProxyCreator` style. -=== +==== @@ -2247,10 +2247,10 @@ proceed, and if we fail with a `PessimisticLockingFailureException` we simply tr unless we have exhausted all of our retry attempts. [NOTE] -=== +==== This class is identical to the one used in the @AspectJ example, but with the annotations removed. -=== +==== The corresponding Spring configuration is: @@ -2461,7 +2461,7 @@ To force CGLIB proxying when using the @AspectJ autoproxy support, set the ---- [NOTE] -=== +==== Multiple `` sections are collapsed into a single unified auto-proxy creator at runtime, which applies the __strongest__ proxy settings that any of the `` sections (typically from different XML bean definition files) specified. @@ -2471,7 +2471,7 @@ elements. To be clear: using '++proxy-target-class="true"++' on ``, `` or `` elements will force the use of CGLIB proxies __for all three of them__. -=== +==== @@ -2746,7 +2746,7 @@ deserialization (e.g., via http://docs.oracle.com/javase/6/docs/api/java/io/Serializable.html[readResolve()]). [NOTE] -=== +==== One of the key phrases in the above paragraph is '__in essence__'. For most cases, the exact semantics of '__after returning from the initialization of a new object__' will be fine... in this context, '__after initialization__' means that the dependencies will be @@ -2767,7 +2767,7 @@ types in AspectJ http://www.eclipse.org/aspectj/doc/next/progguide/semantics-joinPoints.html[in this appendix] of the http://www.eclipse.org/aspectj/doc/next/progguide/index.html[AspectJ Programming Guide]. -=== +==== For this to work the annotated types must be woven with the AspectJ weaver - you can either use a build-time Ant or Maven task to do this (see for example the @@ -2817,13 +2817,13 @@ configuration aspect. ---- [NOTE] -=== +==== Do not activate `@Configurable` processing through the bean configurer aspect unless you really mean to rely on its semantics at runtime. In particular, make sure that you do not use `@Configurable` on bean classes which are registered as regular Spring beans with the container: You would get double initialization otherwise, once through the container and once through the aspect. -=== +==== [[aop-configurable-testing]] @@ -2891,11 +2891,11 @@ default visibility methods directly is the only way to get transaction demarcati the execution of such methods. [TIP] -=== +==== Since Spring Framework 4.2, `spring-aspects` provides a similar aspect that offers the exact same features for the standard `javax.transaction.Transactional` annotation. Check `JtaAnnotationTransactionAspect` for more details. -=== +==== For AspectJ programmers that want to use the Spring configuration and transaction management support but don't want to (or cannot) use annotations, `spring-aspects.jar` @@ -2975,11 +2975,11 @@ configuration: ---- [NOTE] -=== +==== Do not be misled by the name of the `` element: using it will result in the creation of __Spring AOP proxies__. The @AspectJ style of aspect declaration is just being used here, but the AspectJ runtime is __not__ involved. -=== +==== @@ -3027,12 +3027,12 @@ to very quickly get some performance metrics, so that we can then apply a finer- profiling tool to that specific area immediately afterwards. [NOTE] -=== +==== The example presented here uses XML style configuration, it is also possible to configure and use @AspectJ with <>. Specifically the `@EnableLoadTimeWeaving` annotation can be used as an alternative to `` (see <> for details). -=== +==== Here is the profiling aspect. Nothing too fancy, just a quick-and-dirty time-based profiler, using the @AspectJ-style of aspect declaration. @@ -3218,12 +3218,12 @@ have all been introduced in the above example, and the rest of this section will the 'why' behind each bit of configuration and usage in detail. [NOTE] -=== +==== The `ProfilingAspect` used in this example may be basic, but it is quite useful. It is a nice example of a development-time aspect that developers can use during development (of course), and then quite easily exclude from builds of the application being deployed into UAT or production. -=== +==== [[aop-aj-ltw-the-aspects]] @@ -3274,14 +3274,14 @@ runtime, which opens the door to all manner of interesting applications, one of happens to be the LTW of aspects. [TIP] -=== +==== If you are unfamiliar with the idea of runtime class file transformation, you are encouraged to read the javadoc API documentation for the `java.lang.instrument` package before continuing. This is not a huge chore because there is - rather annoyingly - precious little documentation there... the key interfaces and classes will at least be laid out in front of you for reference as you read through this section. -=== +==== Configuring a `LoadTimeWeaver` for a particular `ApplicationContext` can be as easy as adding one line. (Please note that you almost certainly will need to be using an diff --git a/src/asciidoc/core-beans.adoc b/src/asciidoc/core-beans.adoc index 4432083b4f..3c4981edf8 100644 --- a/src/asciidoc/core-beans.adoc +++ b/src/asciidoc/core-beans.adoc @@ -2104,14 +2104,14 @@ as a <>, the same instance of the `com bean is returned each time. [TIP] -=== +==== The interested reader may also find the `ServiceLocatorFactoryBean` (in the `org.springframework.beans.factory.config` package) to be of use. The approach used in ServiceLocatorFactoryBean is similar to that of another utility class, `ObjectFactoryCreatingFactoryBean`, but it allows you to specify your own lookup interface as opposed to a Spring-specific lookup interface. Consult the javadocs of these classes for additional information. -=== +==== [[beans-factory-arbitrary-method-replacement]] @@ -2806,7 +2806,7 @@ Spring `InitializingBean` and `DisposableBean` interfaces. The container calls to perform certain actions upon initialization and destruction of your beans. [TIP] -=== +==== The JSR-250 `@PostConstruct` and `@PreDestroy` annotations are generally considered best practice for receiving lifecycle callbacks in a modern Spring application. Using these @@ -2815,7 +2815,7 @@ details see <>. If you don't want to use the JSR-250 annotations but you are still looking to remove coupling consider the use of init-method and destroy-method object definition metadata. -=== +==== Internally, the Spring Framework uses `BeanPostProcessor` implementations to process any callback interfaces it can find and call the appropriate methods. If you need custom @@ -2952,7 +2952,7 @@ is exactly the same as: but does not couple the code to Spring. [TIP] -=== +==== The `destroy-method` attribute of a `` element can be assigned a special `(inferred)` value which instructs Spring to automatically detect a public `close` or `shutdown` method on the specific bean class. This special `(inferred)` value can also be @@ -2960,7 +2960,7 @@ set on the `default-destroy-method` attribute of a `` element to apply th behavior to an entire set of beans (see <>). Note that this is the default behavior with Java config. -=== +==== [[beans-factory-lifecycle-default-init-destroy-methods]] ==== Default initialization and destroy methods @@ -3819,7 +3819,7 @@ the following three supported integer values: Consult the `PropertyPlaceholderConfigurer` javadocs for more information. [TIP] -=== +==== You can use the `PropertyPlaceholderConfigurer` to substitute class names, which is sometimes useful when you have to pick a particular implementation class at runtime. For @@ -3843,7 +3843,7 @@ example: If the class cannot be resolved at runtime to a valid class, resolution of the bean fails when it is about to be created, which is during the `preInstantiateSingletons()` phase of an `ApplicationContext` for a non-lazy-init bean. -=== +==== [[beans-factory-overrideconfigurer]] @@ -4173,11 +4173,11 @@ The same applies for typed collections: ---- [TIP] -=== +==== Your beans can implement the `org.springframework.core.Ordered` interface or either use the `@Order` or standard `@Priority` annotation if you want items in the array or list to be sorted into a specific order. -=== +==== Even typed Maps can be autowired as long as the expected key type is `String`. The Map @@ -4367,7 +4367,7 @@ multiple `MovieCatalog` beans with the same qualifier value "action"; all of whi be injected into a `Set` annotated with `@Qualifier("action")`. [TIP] -=== +==== If you intend to express annotation-driven injection by name, do not primarily use `@Autowired`, even if is technically capable of referring to a bean name through @@ -4385,7 +4385,7 @@ narrowing through qualifier annotations at the parameter level. By contrast, `@R is supported only for fields and bean property setter methods with a single argument. As a consequence, stick with qualifiers if your injection target is a constructor or a multi-argument method. -=== +==== You can create your own custom qualifier annotations. Simply define an annotation and provide the `@Qualifier` annotation within your definition: @@ -5008,12 +5008,12 @@ The following is an alternative using XML ---- [TIP] -=== +==== The use of `` implicitly enables the functionality of ``. There is usually no need to include the `` element when using ``. -=== +==== [NOTE] ==== @@ -5107,12 +5107,12 @@ and the equivalent using XML ---- [NOTE] -=== +==== You can also disable the default filters by setting `useDefaultFilters=false` on the annotation or providing `use-default-filters="false"` as an attribute of the element. This will in effect disable automatic detection of classes annotated with `@Component`, `@Repository`, `@Service`, or `@Controller`. -=== +==== @@ -5149,11 +5149,11 @@ the `@Qualifier` annotation. Other method level annotations that can be specifie `@Scope`, `@Lazy`, and custom qualifier annotations. [TIP] -=== +==== In addition to its role for component initialization, the `@Lazy` annotation may also be placed on injection points marked with `@Autowired` or `@Inject`. In this context, it leads to the injection of a lazy-resolution proxy. -=== +==== Autowired fields and methods are supported as previously discussed, with additional support for autowiring of `@Bean` methods: @@ -5413,7 +5413,7 @@ Starting with Spring 3.0, Spring offers support for JSR-330 standard annotations annotations. You just need to have the relevant jars in your classpath. [NOTE] -=== +==== If you are using Maven, the `javax.inject` artifact is available in the standard Maven repository ( http://repo1.maven.org/maven2/javax/inject/javax.inject/1/[http://repo1.maven.org/maven2/javax/inject/javax.inject/1/]). @@ -5428,7 +5428,7 @@ You can add the following dependency to your file pom.xml: 1 ---- -=== +==== @@ -5754,7 +5754,7 @@ To enable component scanning, just annotate your `@Configuration` class as follo ---- [TIP] -=== +==== Experienced Spring users will be familiar with the XML declaration equivalent from Spring's `context:` namespace @@ -5766,7 +5766,7 @@ Spring's `context:` namespace ---- -=== +==== In the example above, the `com.acme` package will be scanned, looking for any @@ -5968,7 +5968,7 @@ on the `bean` element: ---- [NOTE] -=== +==== By default, beans defined using Java config that have a public `close` or `shutdown` method are automatically enlisted with a destruction callback. If you have a public `close` or `shutdown` method and you do not wish for it to be called when the container @@ -5988,7 +5988,7 @@ is managed outside the application. In particular, make sure to always do it for } ---- -=== +==== Of course, in the case of `Foo` above, it would be equally as valid to call the `init()` method directly during construction: @@ -6011,11 +6011,11 @@ method directly during construction: ---- [TIP] -=== +==== When you work directly in Java, you can do anything you like with your objects and do not always need to rely on the container lifecycle! -=== +==== [[beans-java-specifying-bean-scope]] @@ -6915,7 +6915,7 @@ bean of a configuration class: ---- [TIP] -=== +==== If a `@Configuration` class is marked with `@Profile`, all of the `@Bean` methods and `@Import` annotations associated with that class will be bypassed unless one or more of the specified profiles are active. If a `@Component` or `@Configuration` @@ -6924,7 +6924,7 @@ processed unless profiles 'p1' and/or 'p2' have been activated. If a given profi is prefixed with the NOT operator (`!`), the annotated element will be registered if the profile is **not** active. e.g., for `@Profile({"p1", "!p2"})`, registration will occur if profile 'p1' is active or if profile 'p2' is not active. -=== +==== [[beans-definition-profiles-xml]] === XML Bean definition profiles @@ -7105,12 +7105,12 @@ will return true if a `foo` system property or `foo` environment variable is pre runtime. [TIP] -=== +==== The search performed is hierarchical. By default, system properties have precedence over environment variables, so if the `foo` property happens to be set in both places during a call to `env.getProperty("foo")`, the system property value will 'win' and be returned preferentially over the environment variable. -=== +==== Most importantly, the entire mechanism is configurable. Perhaps you have a custom source of properties that you'd like to integrate into this search. No problem -- simply implement diff --git a/src/asciidoc/core-expressions.adoc b/src/asciidoc/core-expressions.adoc index 711d58a782..fceaff34f9 100644 --- a/src/asciidoc/core-expressions.adoc +++ b/src/asciidoc/core-expressions.adoc @@ -1170,7 +1170,7 @@ safe navigation operator will simply return null instead of throwing an exceptio ---- [NOTE] -=== +==== The Elvis operator can be used to apply default values in expressions, e.g. in an `@Value` expression: @@ -1181,7 +1181,7 @@ The Elvis operator can be used to apply default values in expressions, e.g. in a ---- This will inject a system property `pop3.port` if it is defined or 25 if not. -=== +==== diff --git a/src/asciidoc/testing.adoc b/src/asciidoc/testing.adoc index 19629154d3..47072ac68a 100644 --- a/src/asciidoc/testing.adoc +++ b/src/asciidoc/testing.adoc @@ -111,14 +111,14 @@ dealing with Spring MVC `ModelAndView` objects. .Unit testing Spring MVC Controllers [TIP] -=== +==== To test your Spring MVC ++Controller++s, use `ModelAndViewAssert` combined with `MockHttpServletRequest`, `MockHttpSession`, and so on from the <> package. Note: As of Spring 4.0, the set of mocks in the `org.springframework.mock.web` package is now based on the Servlet 3.0 API. -=== +==== @@ -1376,7 +1376,7 @@ provide access to the `ApplicationContext` automatically. .@Autowired ApplicationContext [TIP] -=== +==== As an alternative to implementing the `ApplicationContextAware` interface, you can inject the application context for your test class through the `@Autowired` annotation on either a field or setter method. For example: @@ -1415,7 +1415,7 @@ the web application context into your test as follows: Dependency injection via `@Autowired` is provided by the `DependencyInjectionTestExecutionListener` which is configured by default (see <>). -=== +==== Test classes that use the TestContext framework do not need to extend any particular class or implement a specific interface to configure their application context. Instead, @@ -1505,10 +1505,10 @@ configuration files>>. .Enabling Groovy script support [TIP] -=== +==== Support for using Groovy scripts to load an `ApplicationContext` in the Spring TestContext Framework is enabled automatically if Groovy is on the classpath. -=== +==== [source,java,indent=0] [subs="verbatim,quotes"] @@ -1545,7 +1545,7 @@ detect a default location based on the name of the test class. If your class is .Declaring XML config and Groovy scripts simultaneously [TIP] -=== +==== Both XML configuration files and Groovy scripts can be declared simultaneously via the `locations` or `value` attribute of `@ContextConfiguration`. If the path to a configured resource location ends with `.xml` it will be loaded using an `XmlBeanDefinitionReader`; @@ -1564,7 +1564,7 @@ The following listing demonstrates how to combine both in an integration test. // class body... } ---- -=== +==== [[testcontext-ctx-management-javaconfig]] ===== Context configuration with annotated classes @@ -1586,7 +1586,7 @@ To load an `ApplicationContext` for your tests using __annotated classes__ (see .Annotated Classes [TIP] -=== +==== The term __annotated class__ can refer to any of the following. * A class annotated with `@Configuration` @@ -1597,7 +1597,7 @@ The term __annotated class__ can refer to any of the following. Consult the javadocs of `@Configuration` and `@Bean` for further information regarding the configuration and semantics of __annotated classes__, paying special attention to the discussion of __`@Bean` Lite Mode__. -=== +==== If you omit the `classes` attribute from the `@ContextConfiguration` annotation, the TestContext framework will attempt to detect the presence of default configuration @@ -2699,12 +2699,12 @@ support introduced in Spring 2.5 and 3.0, you can use Spring's `@Autowired` anno or the `@Inject` annotation from JSR 300. [TIP] -=== +==== The TestContext framework does not instrument the manner in which a test instance is instantiated. Thus the use of `@Autowired` or `@Inject` for constructors has no effect for test classes. -=== +==== Because `@Autowired` is used to perform <>, if you have multiple bean definitions of the same type, you cannot rely on this @@ -2812,7 +2812,7 @@ this: ---- [NOTE] -=== +==== If you are extending from a Spring-provided test base class that happens to use `@Autowired` on one of its setter methods, you might have multiple beans of the affected type defined in your application context: for example, multiple `DataSource` beans. In @@ -2839,7 +2839,7 @@ narrowing the set of type matches to a specific bean. Its value is matched again `` declarations within the corresponding `` definitions. The bean name is used as a fallback qualifier value, so you may effectively also point to a specific bean by name there (as shown above, assuming that "myDataSource" is the bean id). -=== +==== [[testcontext-web-scoped-beans]] @@ -3136,13 +3136,13 @@ void` method in your test class with one of these annotations, and the __after transaction method__ is executed at the appropriate time. [TIP] -=== +==== Any __before methods__ (such as methods annotated with JUnit's `@Before`) and any __after methods__ (such as methods annotated with JUnit's `@After`) are executed __within__ a transaction. In addition, methods annotated with `@BeforeTransaction` or `@AfterTransaction` are naturally not executed for test methods that are not configured to run within a transaction. -=== +==== [[testcontext-tx-mgr-config]] ===== Configuring a transaction manager @@ -3211,7 +3211,7 @@ declarative SQL script execution with default transaction rollback semantics. [[testcontext-tx-false-positives]] .Avoid false positives when testing ORM code [NOTE] -=== +==== When you test application code that manipulates the state of the Hibernate session, make sure to __flush__ the underlying session within test methods that execute that code. Failing to flush the underlying session can produce __false positives__: your test may @@ -3245,7 +3245,7 @@ work__. // ... ---- -=== +==== [[testcontext-executing-sql]] @@ -3558,12 +3558,12 @@ provides an `executeSqlScript(..)` method for executing SQL scripts against the `DataSource`. [TIP] -=== +==== These classes are a convenience for extension. If you do not want your test classes to be tied to a Spring-specific class hierarchy, you can configure your own custom test classes by using `@RunWith(SpringJUnit4ClassRunner.class)`, `@ContextConfiguration`, `@TestExecutionListeners`, and so on. -=== +==== [[testcontext-junit4-runner]] ===== Spring JUnit Runner @@ -3624,13 +3624,13 @@ provides an `executeSqlScript(..)` method for executing SQL scripts against the [TIP] -=== +==== These classes are a convenience for extension. If you do not want your test classes to be tied to a Spring-specific class hierarchy, you can configure your own custom test classes by using `@ContextConfiguration`, `@TestExecutionListeners`, and so on, and by manually instrumenting your test class with a `TestContextManager`. See the source code of `AbstractTestNGSpringContextTests` for an example of how to instrument your test class. -=== +==== diff --git a/src/asciidoc/web-mvc.adoc b/src/asciidoc/web-mvc.adoc index 47a4fd78a4..9d5bea03db 100644 --- a/src/asciidoc/web-mvc.adoc +++ b/src/asciidoc/web-mvc.adoc @@ -449,13 +449,13 @@ on Servlet or Portlet APIs, although you can easily configure access to Servlet Portlet facilities. [TIP] -=== +==== Available in the https://github.com/spring-projects/[spring-projects Org on Github], a number of web applications leverage the annotation support described in this section including __MvcShowcase__, __MvcAjax__, __MvcBasic__, __PetClinic__, __PetCare__, and others. -=== +==== [source,java,indent=0] [subs="verbatim,quotes"] @@ -709,7 +709,7 @@ appropriate part of the URI. For example, when a request comes in for `/owners/f the value of `ownerId` is `fred`. [TIP] -=== +==== To process the @PathVariable annotation, Spring MVC needs to find the matching URI template variable by name. You can specify it in the annotation: @@ -735,7 +735,7 @@ will match the method argument name to the URI template variable name: // implementation omitted } ---- -=== +==== A method can have any number of `@PathVariable` annotations: @@ -952,7 +952,7 @@ Note that to enable the use of matrix variables, you must set the default it is set to `true`. [TIP] -=== +==== The MVC Java config and the MVC namespace both provide options for enabling the use of matrix variables. @@ -982,7 +982,7 @@ to `false`. ---- -=== +==== [[mvc-ann-requestmapping-consumes]] ==== Consumable Media Types @@ -1004,12 +1004,12 @@ Consumable media type expressions can also be negated as in __!text/plain__ to m all requests other than those with __Content-Type__ of __text/plain__. [TIP] -=== +==== The __consumes__ condition is supported on the type and on the method level. Unlike most other conditions, when used at the type level, method-level consumable types override rather than extend type-level consumable types. -=== +==== [[mvc-ann-requestmapping-produces]] @@ -1036,11 +1036,11 @@ __!text/plain__ to match to all requests other than those with an __Accept__ hea value of __text/plain__. [TIP] -=== +==== The __produces__ condition is supported on the type and on the method level. Unlike most other conditions, when used at the type level, method-level producible types override rather than extend type-level producible types. -=== +==== [[mvc-ann-requestmapping-params-and-headers]] @@ -1084,13 +1084,13 @@ specific request header value: ---- [TIP] -=== +==== Although you can match to __Content-Type__ and __Accept__ header values using media type wild cards (for example __"content-type=text/*"__ will match to __"text/plain"__ and __"text/html"__), it is recommended to use the __consumes__ and __produces__ conditions respectively instead. They are intended specifically for that purpose. -=== +==== @@ -1213,11 +1213,11 @@ this working you have to reorder the parameters as follows: ---- [NOTE] -=== +==== JDK 1.8's `java.util.Optional` is supported as a method parameter type with annotations that have a `required` attribute (e.g. `@RequestParam`, `@RequestHeader`, etc. The use of `java.util.Optional` in those cases is equivalent to having `required=false`. -=== +==== [[mvc-ann-return-types]] @@ -1512,7 +1512,7 @@ and such methods apply to many controllers. See the < for more details. [TIP] -=== +==== What happens when a model attribute name is not explicitly specified? In such cases a default name is assigned to the model attribute based on its type. For example if the @@ -1520,7 +1520,7 @@ method returns an object of type `Account`, the default name used is "account". change that through the value of the `@ModelAttribute` annotation. If adding attributes directly to the `Model`, use the appropriate overloaded `addAttribute(..)` method - i.e., with or without an attribute name. -=== +==== The `@ModelAttribute` annotation can be used on `@RequestMapping` methods as well. In that case the return value of the `@RequestMapping` method is interpreted as a model @@ -1818,12 +1818,12 @@ with all header values. [TIP] -=== +==== Built-in support is available for converting a comma-separated string into an array/collection of strings or other types known to the type conversion system. For example a method parameter annotated with `@RequestHeader("Accept")` may be of type `String` but also `String[]` or `List`. -=== +==== This annotation is supported for annotated handler methods in Servlet and Portlet environments. @@ -2248,14 +2248,14 @@ filters provided with the Spring Framework since they will not get involved in a dispatches unless needed. [WARNING] -=== +==== Note that for some Filters it is absolutely critical to ensure they are mapped to be invoked during asynchronous dispatches. For example if a filter such as the `OpenEntityManagerInViewFilter` is responsible for releasing database connection resources and must be invoked at the end of an async request. Below is an example of a propertly configured filter: -=== +==== [source,xml,indent=0] [subs="verbatim,quotes"] @@ -2456,13 +2456,13 @@ As you can see, the Spring adapter class `HandlerInterceptorAdapter` makes it ea extend the `HandlerInterceptor` interface. [TIP] -=== +==== In the example above, the configured interceptor will apply to all requests handled with annotated controller methods. If you want to narrow down the URL paths to which an interceptor applies, you can use the MVC namespace or the MVC Java config, or declare bean instances of type `MappedInterceptor` to do that. See <>. -=== +==== Note that the `postHandle` method of `HandlerInterceptor` is not always ideally suited for use with `@ResponseBody` and `ResponseEntity` methods. In such cases an `HttpMessageConverter` @@ -2776,7 +2776,7 @@ server: http://en.wikipedia.org/wiki/Content_negotiation[content negotiation]. [NOTE] -=== +==== One issue with the `Accept` header is that it is impossible to set it in a web browser within HTML. For example, in Firefox, it is fixed to: @@ -2788,7 +2788,7 @@ Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 For this reason it is common to see the use of a distinct URI for each representation when developing browser based web applications. -=== +==== To support multiple representations of a resource, Spring provides the `ContentNegotiatingViewResolver` to resolve a view based on the file extension or @@ -4023,13 +4023,13 @@ then resolved into the `/WEB-INF/jsp/registration.jsp` view by the `InternalResourceViewResolver` bean. [TIP] -=== +==== You do not need to define a `DefaultRequestToViewNameTranslator` bean explicitly. If you like the default settings of the `DefaultRequestToViewNameTranslator`, you can rely on the Spring Web MVC `DispatcherServlet` to instantiate an instance of this class if one is not explicitly configured. -=== +==== Of course, if you need to change the default settings, then you do need to configure your own `DefaultRequestToViewNameTranslator` bean explicitly. Consult the comprehensive diff --git a/src/asciidoc/web-portlet.adoc b/src/asciidoc/web-portlet.adoc index bad4875251..29e447c3cf 100644 --- a/src/asciidoc/web-portlet.adoc +++ b/src/asciidoc/web-portlet.adoc @@ -1123,7 +1123,7 @@ method-level annotations 'narrowing' the primary mapping for specific portlet re parameters. [TIP] -=== +==== `@RequestMapping` at the type level may be used for plain implementations of the `Controller` interface as well. In this case, the request processing code would follow @@ -1133,7 +1133,7 @@ would be expressed through an `@RequestMapping` annotation. This works for pre-b In the following discussion, we'll focus on controllers that are based on annotated handler methods. -=== +==== The following is an example of a form controller from the PetPortal sample application using this annotation: