From c2bd229d4ce7481e05a1407e63cfe82695eb5c7f Mon Sep 17 00:00:00 2001 From: Juergen Hoeller Date: Fri, 15 Feb 2019 17:06:03 +0100 Subject: [PATCH] Clarify role of 'aware' callback interfaces --- src/docs/asciidoc/core/core-beans.adoc | 46 +++++++++++----------- src/docs/asciidoc/core/core-resources.adoc | 38 +++++++++--------- 2 files changed, 41 insertions(+), 43 deletions(-) diff --git a/src/docs/asciidoc/core/core-beans.adoc b/src/docs/asciidoc/core/core-beans.adoc index 122287bb172..0db3ea8a6c4 100644 --- a/src/docs/asciidoc/core/core-beans.adoc +++ b/src/docs/asciidoc/core/core-beans.adoc @@ -3746,16 +3746,16 @@ Thus, beans can programmatically manipulate the `ApplicationContext` that create through the `ApplicationContext` interface or by casting the reference to a known subclass of this interface (such as `ConfigurableApplicationContext`, which exposes additional functionality). One use would be the programmatic retrieval of other beans. -Sometimes this capability is useful. However, in general, you should avoid it, because it -couples the code to Spring and does not follow the Inversion of Control style, where -collaborators are provided to beans as properties. Other methods of the -`ApplicationContext` provide access to file resources, publishing application events, and -accessing a `MessageSource`. These additional features are described in +Sometimes this capability is useful. However, in general, you should avoid it, because +it couples the code to Spring and does not follow the Inversion of Control style, +where collaborators are provided to beans as properties. Other methods of the +`ApplicationContext` provide access to file resources, publishing application events, +and accessing a `MessageSource`. These additional features are described in <>. As of Spring 2.5, autowiring is another alternative to obtain a reference to the -`ApplicationContext`. The "`traditional`" `constructor` and `byType` autowiring modes (as -described in <>) can provide a dependency of type +`ApplicationContext`. The "`traditional`" `constructor` and `byType` autowiring modes +(as described in <>) can provide a dependency of type `ApplicationContext` for a constructor argument or a setter method parameter, respectively. For more flexibility, including the ability to autowire fields and multiple parameter methods, use the new annotation-based autowiring features. If you do, @@ -3789,11 +3789,10 @@ init-method. [[aware-list]] === Other `Aware` Interfaces -Besides `ApplicationContextAware` and `BeanNameAware` (discussed -<>), Spring offers a range of `Aware` interfaces that let -beans indicate to the container that they require a certain infrastructure dependency. As -a general rule, the name is a good indication of the dependency type. The following table -summarizes the most important `Aware` interfaces: +Besides `ApplicationContextAware` and `BeanNameAware` (discussed <>), +Spring offers a wide range of `Aware` callback interfaces that let beans indicate to the container +that they require a certain infrastructure dependency. As a general rule, the name indicates the +dependency type. The following table summarizes the most important `Aware` interfaces: [[beans-factory-nature-aware-list]] .Aware interfaces @@ -3822,7 +3821,7 @@ summarizes the most important `Aware` interfaces: | `BootstrapContextAware` | Resource adapter `BootstrapContext` the container runs in. Typically available only in - JCA aware `ApplicationContext` instances. + JCA-aware `ApplicationContext` instances. | <> | `LoadTimeWeaverAware` @@ -9336,19 +9335,18 @@ specific and appropriate to the actual application context type. You can configure a bean deployed into the application context to implement the special callback interface, `ResourceLoaderAware`, to be automatically called back at -initialization time with the application context itself passed in as the -`ResourceLoader`. You can also expose properties of type `Resource`, to be used to -access static resources. They are injected into it like any other properties. You -can specify those `Resource` properties as simple `String` paths and rely on a special -JavaBean `PropertyEditor` (which is automatically registered by the context) to convert -those text strings to actual `Resource` objects when the bean is deployed. +initialization time with the application context itself passed in as the `ResourceLoader`. +You can also expose properties of type `Resource`, to be used to access static resources. +They are injected into it like any other properties. You can specify those `Resource` +properties as simple `String` paths and rely on automatic conversion from those text +strings to actual `Resource` objects when the bean is deployed. The location path or paths supplied to an `ApplicationContext` constructor are actually -resource strings and, in simple form, are treated appropriately according to the specific context -implementation. For example `ClassPathXmlApplicationContext` treats a simple location path as a -classpath location. You can also use location paths (resource strings) with special -prefixes to force loading of definitions from the classpath or a URL, regardless of the -actual context type. +resource strings and, in simple form, are treated appropriately according to the specific +context implementation. For example `ClassPathXmlApplicationContext` treats a simple +location path as a classpath location. You can also use location paths (resource strings) +with special prefixes to force loading of definitions from the classpath or a URL, +regardless of the actual context type. diff --git a/src/docs/asciidoc/core/core-resources.adoc b/src/docs/asciidoc/core/core-resources.adoc index c88dd9cffd3..4d5c651aa7a 100644 --- a/src/docs/asciidoc/core/core-resources.adoc +++ b/src/docs/asciidoc/core/core-resources.adoc @@ -323,9 +323,9 @@ The following table summarizes the strategy for converting `String` objects to ` [[resources-resourceloaderaware]] == The `ResourceLoaderAware` interface -The `ResourceLoaderAware` interface is a special marker interface that identifies objects -that expect to be provided with a `ResourceLoader` reference. The following listing shows -the definition of the `ResourceLoaderAware` interface: +The `ResourceLoaderAware` interface is a special callback interface which identifies +components that expect to be provided with a `ResourceLoader` reference. The following +listing shows the definition of the `ResourceLoaderAware` interface: ==== [source,java,indent=0] @@ -338,29 +338,29 @@ the definition of the `ResourceLoaderAware` interface: ---- ==== -When a class implements `ResourceLoaderAware` and is deployed into an application -context (as a Spring-managed bean), it is recognized as `ResourceLoaderAware` by the -application context. The application context then invokes -`setResourceLoader(ResourceLoader)`, supplying itself as the argument (remember, all -application contexts in Spring implement the `ResourceLoader` interface). +When a class implements `ResourceLoaderAware` and is deployed into an application context +(as a Spring-managed bean), it is recognized as `ResourceLoaderAware` by the application +context. The application context then invokes `setResourceLoader(ResourceLoader)`, +supplying itself as the argument (remember, all application contexts in Spring implement +the `ResourceLoader` interface). -Since an `ApplicationContext` is a `ResourceLoader`, the bean could also -implement the `ApplicationContextAware` interface and use the supplied application -context directly to load resources. However, in general, it is better to use the specialized -`ResourceLoader` interface if that is all you need. The code would be coupled only -to the resource loading interface (which can be considered a utility interface) and not to -the whole Spring `ApplicationContext` interface. +Since an `ApplicationContext` is a `ResourceLoader`, the bean could also implement the +`ApplicationContextAware` interface and use the supplied application context directly to +load resources. However, in general, it is better to use the specialized `ResourceLoader` +interface if that is all you need. The code would be coupled only to the resource loading +interface (which can be considered a utility interface) and not to the whole Spring +`ApplicationContext` interface. As of Spring 2.5, you can rely upon autowiring of the `ResourceLoader` as an alternative to implementing the `ResourceLoaderAware` interface. The "`traditional`" `constructor` and -`byType` autowiring modes (as described in <>) are now capable -of providing a dependency of type `ResourceLoader` for either a constructor argument or a +`byType` autowiring modes (as described in <>) are now capable of +providing a dependency of type `ResourceLoader` for either a constructor argument or a setter method parameter, respectively. For more flexibility (including the ability to autowire fields and multiple parameter methods), consider using the annotation-based autowiring features. In that case, the `ResourceLoader` is autowired into a field, -constructor argument, or method parameter that expects the `ResourceLoader` type as -long as the field, constructor, or method in question carries the `@Autowired` -annotation. For more information, see <>. +constructor argument, or method parameter that expects the `ResourceLoader` type as long +as the field, constructor, or method in question carries the `@Autowired` annotation. +For more information, see <>.