root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 8 Packages Projects Releases Wiki Activity

Reference documentation updates 

Issue: SPR-14087
Issue: SPR-14272
Issue: SPR-13535
Issue: SPR-13843
Issue: SPR-14164
Issue: SPR-14319
This commit is contained in:
Juergen Hoeller 2016-05-30 15:04:57 +02:00
parent a2088c38ad
commit ad29db8675
3 changed files with 52 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
src/asciidoc/core-aop.adoc
View File

@ -438,7 +438,7 @@ be &&'ed, ||'ed, and ! (negated) too.
==== ====
Please note that the '++bean++' PCD is __only__ supported in Spring AOP - and __not__ in 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 native AspectJ weaving. It is a Spring-specific extension to the standard PCDs that
AspectJ defines. AspectJ defines and therefore not available for aspects declared in the `@Aspect` model.
The '++bean++' PCD operates at the __instance__ level (building on the Spring bean name The '++bean++' PCD operates at the __instance__ level (building on the Spring bean name
concept) rather than at the type level only (which is what weaving-based AOP is limited concept) rather than at the type level only (which is what weaving-based AOP is limited
@ -1991,7 +1991,7 @@ proceed with the method call: the presence of this parameter is an indication th
public class SimpleProfiler { public class SimpleProfiler {
public Object profile(ProceedingJoinPoint call, String name, int age) throws Throwable { public Object profile(ProceedingJoinPoint call, String name, int age) throws Throwable {
StopWatch clock = new StopWatch("Profiling for ''" + name + "'' and ''" + age + "''"); StopWatch clock = new StopWatch("Profiling for '" + name + "' and '" + age + "'");
try { try {
clock.start(call.toShortString()); clock.start(call.toShortString());
return call.proceed(); return call.proceed();
@ -2884,10 +2884,9 @@ A `@Transactional` annotation on a class specifies the default transaction seman
the execution of any __public__ operation in the class. the execution of any __public__ operation in the class.
A `@Transactional` annotation on a method within the class overrides the default A `@Transactional` annotation on a method within the class overrides the default
transaction semantics given by the class annotation (if present). Methods with `public`, transaction semantics given by the class annotation (if present). Methods of any
`protected`, and default visibility may all be annotated. Annotating `protected` and visibility may be annotated, including private methods. Annotating non-public methods
default visibility methods directly is the only way to get transaction demarcation for directly is the only way to get transaction demarcation for the execution of such methods.
the execution of such methods.
[TIP] [TIP]
==== ====

30
src/asciidoc/core-beans.adoc
View File

@ -437,6 +437,16 @@ you are using Spring AOP it helps a lot when applying advice to a set of beans r
by name. by name.
**** ****
[NOTE]
====
With component scanning in the classpath, Spring generates bean names for unnamed
components, following the rules above: essentially, taking the simple class name
and turning its initial character to lower-case. However, in the (unusual) special
case when there is more than one character and both the first and second characters
are upper case, the original casing gets preserved. These are the same rules as
defined by `java.beans.Introspector.decapitalize` (which Spring is using here).
====
[[beans-beanname-alias]] [[beans-beanname-alias]]
==== Aliasing a bean outside the bean definition ==== Aliasing a bean outside the bean definition
@ -1719,7 +1729,7 @@ then nested `constructor-arg` elements.
Let's review the examples from <<beans-constructor-injection>> with the `c:` namespace: Let's review the examples from <<beans-constructor-injection>> with the `c:` namespace:
[source,java,indent=0] [source,xml,indent=0]
[subs="verbatim,quotes"] [subs="verbatim,quotes"]
---- ----
<beans xmlns="http://www.springframework.org/schema/beans" <beans xmlns="http://www.springframework.org/schema/beans"
@ -1753,7 +1763,7 @@ For the rare cases where the constructor argument names are not available (usual
the bytecode was compiled without debugging information), one can use fallback to the the bytecode was compiled without debugging information), one can use fallback to the
argument indexes: argument indexes:
[source,java,indent=0] [source,xml,indent=0]
[subs="verbatim,quotes"] [subs="verbatim,quotes"]
---- ----
<!-- c-namespace index declaration --> <!-- c-namespace index declaration -->
@ -2561,7 +2571,7 @@ The Spring container creates a new instance of the `AppPreferences` bean by usin
`appPreferences` bean is scoped at the `ServletContext` level, stored as a regular `appPreferences` bean is scoped at the `ServletContext` level, stored as a regular
`ServletContext` attribute. This is somewhat similar to a Spring singleton bean but `ServletContext` attribute. This is somewhat similar to a Spring singleton bean but
differs in two important ways: It is a singleton per `ServletContext`, not per Spring differs in two important ways: It is a singleton per `ServletContext`, not per Spring
'ApplicationContext' (or which there may be several in any given web application), 'ApplicationContext' (for which there may be several in any given web application),
and it is actually exposed and therefore visible as a `ServletContext` attribute. and it is actually exposed and therefore visible as a `ServletContext` attribute.
@ -3707,7 +3717,7 @@ Find below the custom `BeanPostProcessor` implementation class definition:
public Object postProcessAfterInitialization(Object bean, public Object postProcessAfterInitialization(Object bean,
String beanName) throws BeansException { String beanName) throws BeansException {
System.out.println("Bean ''" + beanName + "'' created : " + bean.toString()); System.out.println("Bean '" + beanName + "' created : " + bean.toString());
return bean; return bean;
} }
@ -5798,8 +5808,8 @@ It is very common to use `@Component` without specifying a name for the componen
} }
---- ----
When using `@Named`, it is possible to use When using `@Named`, it is possible to use component scanning in the exact same way
component-scanning in the exact same way as when using Spring annotations: as when using Spring annotations:
[source,java,indent=0] [source,java,indent=0]
[subs="verbatim,quotes"] [subs="verbatim,quotes"]
@ -5811,6 +5821,12 @@ component-scanning in the exact same way as when using Spring annotations:
} }
---- ----
[NOTE]
====
In contrast to `@Component`, the JSR-330 `@Named` annotation is not composable.
Please use Spring's stereotype model for building custom component annotations.
====
[[beans-standard-annotations-limitations]] [[beans-standard-annotations-limitations]]
@ -7460,7 +7476,7 @@ hierarchy of property sources. To explain fully, consider the following:
ApplicationContext ctx = new GenericApplicationContext(); ApplicationContext ctx = new GenericApplicationContext();
Environment env = ctx.getEnvironment(); Environment env = ctx.getEnvironment();
boolean containsFoo = env.containsProperty("foo"); boolean containsFoo = env.containsProperty("foo");
System.out.println("Does my environment contain the ''foo'' property? " + containsFoo); System.out.println("Does my environment contain the 'foo' property? " + containsFoo);
---- ----
In the snippet above, we see a high-level way of asking Spring whether the `foo` property is In the snippet above, we see a high-level way of asking Spring whether the `foo` property is

38
src/asciidoc/integration.adoc
View File

@ -6001,7 +6001,7 @@ along with an inline image.
helper.setTo("test@host.com"); helper.setTo("test@host.com");
// use the true flag to indicate the text included is HTML // use the true flag to indicate the text included is HTML
helper.setText("<html><body><img src=''cid:identifier1234''></body></html>", true); helper.setText("<html><body><img src='cid:identifier1234'></body></html>", true);
// let's include the infamous windows Sample file (this time copied to c:/) // let's include the infamous windows Sample file (this time copied to c:/)
FileSystemResource res = new FileSystemResource(new File("c:/Sample.jpg")); FileSystemResource res = new FileSystemResource(new File("c:/Sample.jpg"));
@ -6492,7 +6492,7 @@ reference is provided for managing those methods annotated with `@Scheduled`.
[[scheduling-annotation-support-scheduled]] [[scheduling-annotation-support-scheduled]]
==== The @Scheduled Annotation ==== The @Scheduled Annotation
The @Scheduled annotation can be added to a method along with trigger metadata. For The `@Scheduled` annotation can be added to a method along with trigger metadata. For
example, the following method would be invoked every 5 seconds with a fixed delay, example, the following method would be invoked every 5 seconds with a fixed delay,
meaning that the period will be measured from the completion time of each preceding meaning that the period will be measured from the completion time of each preceding
invocation. invocation.
@ -6556,13 +6556,13 @@ Context, then those would typically have been provided through dependency inject
[NOTE] [NOTE]
==== ====
Make sure that you are not initializing multiple instances of the same @Scheduled Make sure that you are not initializing multiple instances of the same `@Scheduled`
annotation class at runtime, unless you do want to schedule callbacks to each such annotation class at runtime, unless you do want to schedule callbacks to each such
instance. Related to this, make sure that you do not use @Configurable on bean classes instance. Related to this, make sure that you do not use `@Configurable` on bean
which are annotated with @Scheduled and registered as regular Spring beans with the classes which are annotated with `@Scheduled` and registered as regular Spring beans
container: You would get double initialization otherwise, once through the container and with the container: You would get double initialization otherwise, once through the
once through the @Configurable aspect, with the consequence of each @Scheduled method container and once through the `@Configurable` aspect, with the consequence of each
being invoked twice. `@Scheduled` method being invoked twice.
==== ====
@ -6613,8 +6613,8 @@ asynchronous execution so that the caller can perform other tasks prior to calli
---- ----
`@Async` can not be used in conjunction with lifecycle callbacks such as `@Async` can not be used in conjunction with lifecycle callbacks such as
`@PostConstruct`. To asynchronously initialize Spring beans you currently have to use a `@PostConstruct`. To asynchronously initialize Spring beans you currently have to use
separate initializing Spring bean that invokes the `@Async` annotated method on the a separate initializing Spring bean that invokes the `@Async` annotated method on the
target then. target then.
[source,java,indent=0] [source,java,indent=0]
@ -6629,7 +6629,7 @@ target then.
} }
public class SampleBeanInititalizer { public class SampleBeanInitializer {
private final SampleBean bean; private final SampleBean bean;
@ -6645,6 +6645,14 @@ target then.
} }
---- ----
[NOTE]
====
There is no direct XML equivalent for `@Async` since such methods should be designed
for asynchronous execution in the first place, not externally re-declared to be async.
However, you may manually set up Spring's `AsyncExecutionInterceptor` with Spring AOP,
in combination with a custom pointcut.
====
[[scheduling-annotation-support-qualification]] [[scheduling-annotation-support-qualification]]
@ -7360,7 +7368,7 @@ message is surrounded by quotes. Below are the changes that I (the author) make
public String getMessage() { public String getMessage() {
// change the implementation to surround the message in quotes // change the implementation to surround the message in quotes
return "''" + this.message + "''" return "'" + this.message + "'"
} }
public void setMessage(String message) { public void setMessage(String message) {
@ -7767,7 +7775,7 @@ will want to do with this callback, and you can see an example of doing that bel
DelegatingMetaClass metaClass = new DelegatingMetaClass(goo.getMetaClass()) { DelegatingMetaClass metaClass = new DelegatingMetaClass(goo.getMetaClass()) {
public Object invokeMethod(Object object, String methodName, Object[] arguments) { public Object invokeMethod(Object object, String methodName, Object[] arguments) {
System.out.println("Invoking ''" + methodName + "''."); System.out.println("Invoking '" + methodName + "'.");
return super.invokeMethod(object, methodName, arguments); return super.invokeMethod(object, methodName, arguments);
} }
}; };
@ -8814,7 +8822,7 @@ up its declaration at runtime and understands its meaning. Note that as mentione
=== JCache (JSR-107) annotations === JCache (JSR-107) annotations
Since the Spring Framework 4.1, the caching abstraction fully supports the JCache Since the Spring Framework 4.1, the caching abstraction fully supports the JCache
standard annotations: these are `@CacheResult`, `@CacheEvict`, `@CacheRemove` and standard annotations: these are `@CacheResult`, `@CachePut`, `@CacheRemove` and
`@CacheRemoveAll` as well as the `@CacheDefaults`, `@CacheKey` and `@CacheValue` `@CacheRemoveAll` as well as the `@CacheDefaults`, `@CacheKey` and `@CacheValue`
companions. These annotations can be used right the way without migrating your companions. These annotations can be used right the way without migrating your
cache store to JSR-107: the internal implementation uses Spring's caching abstraction cache store to JSR-107: the internal implementation uses Spring's caching abstraction
@ -8996,7 +9004,7 @@ we did in the example above by defining the target cache through the `cache:defi
[[cache-store-configuration]] [[cache-store-configuration]]
=== Configuring the cache storage === Configuring the cache storage
Out of the box, the cache abstraction provides several storages integration. To use Out of the box, the cache abstraction provides several storage integration. To use
them, one needs to simply declare an appropriate `CacheManager` - an entity that them, one needs to simply declare an appropriate `CacheManager` - an entity that
controls and manages ++Cache++s and can be used to retrieve these for storage. controls and manages ++Cache++s and can be used to retrieve these for storage.