diff --git a/spring-context/src/main/java/org/springframework/cache/annotation/EnableCaching.java b/spring-context/src/main/java/org/springframework/cache/annotation/EnableCaching.java index 0ec602b9ea..c05b44ce1b 100644 --- a/spring-context/src/main/java/org/springframework/cache/annotation/EnableCaching.java +++ b/spring-context/src/main/java/org/springframework/cache/annotation/EnableCaching.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2016 the original author or authors. + * Copyright 2002-2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -148,15 +148,19 @@ import org.springframework.core.Ordered; * can be useful if you do not need to customize everything. See {@link CachingConfigurer} * Javadoc for further details. * - *

The {@link #mode()} attribute controls how advice is applied; if the mode is - * {@link AdviceMode#PROXY} (the default), then the other attributes such as - * {@link #proxyTargetClass()} control the behavior of the proxying. + *

The {@link #mode} attribute controls how advice is applied: If the mode is + * {@link AdviceMode#PROXY} (the default), then the other attributes control the behavior + * of the proxying. Please note that proxy mode allows for interception of calls through + * the proxy only; local calls within the same class cannot get intercepted that way. * - *

If the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then the - * {@link #proxyTargetClass()} attribute is obsolete. Note also that in this case the - * {@code spring-aspects} module JAR must be present on the classpath. + *

Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then the + * value of the {@link #proxyTargetClass} attribute will be ignored. Note also that in + * this case the {@code spring-aspects} module JAR must be present on the classpath, with + * compile-time weaving or load-time weaving applying the aspect to the affected classes. + * There is no proxy involved in such a scenario; local calls will be intercepted as well. * * @author Chris Beams + * @author Juergen Hoeller * @since 3.1 * @see CachingConfigurer * @see CachingConfigurationSelector @@ -183,16 +187,21 @@ public @interface EnableCaching { boolean proxyTargetClass() default false; /** - * Indicate how caching advice should be applied. The default is - * {@link AdviceMode#PROXY}. - * @see AdviceMode + * Indicate how caching advice should be applied. + *

The default is {@link AdviceMode#PROXY}. + * Please note that proxy mode allows for interception of calls through the proxy + * only. Local calls within the same class cannot get intercepted that way; + * a caching annotation on such a method within a local call will be ignored + * since Spring's interceptor does not even kick in for such a runtime scenario. + * For a more advanced mode of interception, consider switching this to + * {@link AdviceMode#ASPECTJ}. */ AdviceMode mode() default AdviceMode.PROXY; /** * Indicate the ordering of the execution of the caching advisor * when multiple advices are applied at a specific joinpoint. - * The default is {@link Ordered#LOWEST_PRECEDENCE}. + *

The default is {@link Ordered#LOWEST_PRECEDENCE}. */ int order() default Ordered.LOWEST_PRECEDENCE; diff --git a/spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java b/spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java index 8b7eb4c026..a06ed0cb57 100644 --- a/spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java +++ b/spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2016 the original author or authors. + * Copyright 2002-2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -58,14 +58,6 @@ import org.springframework.core.Ordered; * } * } * - *

The {@link #mode} attribute controls how advice is applied; if the mode is - * {@link AdviceMode#PROXY} (the default), then the other attributes control the behavior - * of the proxying. - * - *

Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then the - * value of the {@link #proxyTargetClass} attribute will be ignored. Note also that in - * this case the {@code spring-aspects} module JAR must be present on the classpath. - * *

By default, Spring will be searching for an associated thread pool definition: * either a unique {@link org.springframework.core.task.TaskExecutor} bean in the context, * or an {@link java.util.concurrent.Executor} bean named "taskExecutor" otherwise. If @@ -140,6 +132,17 @@ import org.springframework.core.Ordered; * demonstrates how the JavaConfig-based approach allows for maximum configurability * through direct access to actual componentry. * + *

The {@link #mode} attribute controls how advice is applied: If the mode is + * {@link AdviceMode#PROXY} (the default), then the other attributes control the behavior + * of the proxying. Please note that proxy mode allows for interception of calls through + * the proxy only; local calls within the same class cannot get intercepted that way. + * + *

Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then the + * value of the {@link #proxyTargetClass} attribute will be ignored. Note also that in + * this case the {@code spring-aspects} module JAR must be present on the classpath, with + * compile-time weaving or load-time weaving applying the aspect to the affected classes. + * There is no proxy involved in such a scenario; local calls will be intercepted as well. + * * @author Chris Beams * @author Juergen Hoeller * @author Stephane Nicoll @@ -182,8 +185,13 @@ public @interface EnableAsync { /** * Indicate how async advice should be applied. - *

The default is {@link AdviceMode#PROXY}. - * @see AdviceMode + *

The default is {@link AdviceMode#PROXY}. + * Please note that proxy mode allows for interception of calls through the proxy + * only. Local calls within the same class cannot get intercepted that way; an + * {@link Async} annotation on such a method within a local call will be ignored + * since Spring's interceptor does not even kick in for such a runtime scenario. + * For a more advanced mode of interception, consider switching this to + * {@link AdviceMode#ASPECTJ}. */ AdviceMode mode() default AdviceMode.PROXY; diff --git a/spring-tx/src/main/java/org/springframework/transaction/annotation/EnableTransactionManagement.java b/spring-tx/src/main/java/org/springframework/transaction/annotation/EnableTransactionManagement.java index f0d8d733f7..8d500e8d03 100644 --- a/spring-tx/src/main/java/org/springframework/transaction/annotation/EnableTransactionManagement.java +++ b/spring-tx/src/main/java/org/springframework/transaction/annotation/EnableTransactionManagement.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2016 the original author or authors. + * Copyright 2002-2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -131,15 +131,19 @@ import org.springframework.core.Ordered; * {@code @Transactional} methods. See {@link TransactionManagementConfigurer} Javadoc * for further details. * - *

The {@link #mode()} attribute controls how advice is applied; if the mode is + *

The {@link #mode} attribute controls how advice is applied: If the mode is * {@link AdviceMode#PROXY} (the default), then the other attributes control the behavior - * of the proxying. + * of the proxying. Please note that proxy mode allows for interception of calls through + * the proxy only; local calls within the same class cannot get intercepted that way. * - *

If the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then the - * {@link #proxyTargetClass()} attribute is obsolete. Note also that in this case the - * {@code spring-aspects} module JAR must be present on the classpath. + *

Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then the + * value of the {@link #proxyTargetClass} attribute will be ignored. Note also that in + * this case the {@code spring-aspects} module JAR must be present on the classpath, with + * compile-time weaving or load-time weaving applying the aspect to the affected classes. + * There is no proxy involved in such a scenario; local calls will be intercepted as well. * * @author Chris Beams + * @author Juergen Hoeller * @since 3.1 * @see TransactionManagementConfigurer * @see TransactionManagementConfigurationSelector @@ -167,16 +171,21 @@ public @interface EnableTransactionManagement { boolean proxyTargetClass() default false; /** - * Indicate how transactional advice should be applied. The default is - * {@link AdviceMode#PROXY}. - * @see AdviceMode + * Indicate how transactional advice should be applied. + *

The default is {@link AdviceMode#PROXY}. + * Please note that proxy mode allows for interception of calls through the proxy + * only. Local calls within the same class cannot get intercepted that way; an + * {@link Transactional} annotation on such a method within a local call will be + * ignored since Spring's interceptor does not even kick in for such a runtime + * scenario. For a more advanced mode of interception, consider switching this to + * {@link AdviceMode#ASPECTJ}. */ AdviceMode mode() default AdviceMode.PROXY; /** * Indicate the ordering of the execution of the transaction advisor * when multiple advices are applied at a specific joinpoint. - * The default is {@link Ordered#LOWEST_PRECEDENCE}. + *

The default is {@link Ordered#LOWEST_PRECEDENCE}. */ int order() default Ordered.LOWEST_PRECEDENCE; diff --git a/src/asciidoc/data-access.adoc b/src/asciidoc/data-access.adoc index 60810f9fd8..4c85115cfa 100644 --- a/src/asciidoc/data-access.adoc +++ b/src/asciidoc/data-access.adoc @@ -18,12 +18,16 @@ that the Spring Framework integrates with. -- + + [[transaction]] == Transaction Management + [[transaction-intro]] === Introduction to Spring Framework transaction management + Comprehensive transaction support is among the most compelling reasons to use the Spring Framework. The Spring Framework provides a consistent abstraction for transaction management that delivers the following benefits: @@ -59,9 +63,9 @@ server integration, and solutions to common problems.) - [[transaction-motivation]] === Advantages of the Spring Framework's transaction support model + Traditionally, Java EE developers have had two choices for transaction management: __global__ or __local__ transactions, both of which have profound limitations. Global and local transaction management is reviewed in the next two sections, followed by a @@ -69,9 +73,9 @@ discussion of how the Spring Framework's transaction management support addresse limitations of the global and local transaction models. - [[transaction-global]] ==== Global transactions + Global transactions enable you to work with multiple transactional resources, typically relational databases and message queues. The application server manages global transactions through the JTA, which is a cumbersome API to use (partly due to its @@ -92,9 +96,9 @@ negatives of EJB in general are so great that this is not an attractive proposit especially in the face of compelling alternatives for declarative transaction management. - [[transaction-local]] ==== Local transactions + Local transactions are resource-specific, such as a transaction associated with a JDBC connection. Local transactions may be easier to use, but have significant disadvantages: they cannot work across multiple transactional resources. For example, code that manages @@ -105,7 +109,6 @@ single transaction resource.) Another downside is that local transactions are in to the programming model. - [[transaction-programming-model]] ==== Spring Framework's consistent programming model @@ -150,9 +153,9 @@ configuration file, rather than your code, need to change. - [[transaction-strategies]] === Understanding the Spring Framework transaction abstraction + The key to the Spring transaction abstraction is the notion of a __transaction strategy__. A transaction strategy is defined by the `org.springframework.transaction.PlatformTransactionManager` interface: @@ -377,9 +380,9 @@ moving from local to global transactions or vice versa. - [[tx-resource-synchronization]] === Synchronizing resources with transactions + It should now be clear how you create different transaction managers, and how they are linked to related resources that need to be synchronized to transactions (for example `DataSourceTransactionManager` to a JDBC `DataSource`, `HibernateTransactionManager` to @@ -390,9 +393,9 @@ also discusses how transaction synchronization is triggered (optionally) through relevant `PlatformTransactionManager`. - [[tx-resource-synchronization-high]] ==== High-level synchronization approach + The preferred approach is to use Spring's highest level template based persistence integration APIs or to use native ORM APIs with transaction- aware factory beans or proxies for managing the native resource factories. These transaction-aware solutions @@ -404,9 +407,9 @@ for JDBC access by using the `JdbcTemplate`. These solutions are detailed in sub chapters of this reference documentation. - [[tx-resource-synchronization-low]] ==== Low-level synchronization approach + Classes such as `DataSourceUtils` (for JDBC), `EntityManagerFactoryUtils` (for JPA), `SessionFactoryUtils` (for Hibernate), `PersistenceManagerFactoryUtils` (for JDO), and so on exist at a lower level. When you want the application code to deal directly with @@ -446,7 +449,6 @@ with the relevant APIs. For example, if you use the Spring `JdbcTemplate` or behind the scenes and you won't need to write any special code. - [[tx-resource-synchronization-tadsp]] ==== TransactionAwareDataSourceProxy @@ -463,9 +465,9 @@ abstractions mentioned above. - [[transaction-declarative]] === Declarative transaction management + [NOTE] ==== Most Spring Framework users choose declarative transaction management. This option has @@ -529,9 +531,9 @@ declarative transaction management follows EJB convention (roll back is automati on unchecked exceptions), it is often useful to customize this behavior. - [[tx-decl-explained]] ==== Understanding the Spring Framework's declarative transaction implementation + It is not sufficient to tell you simply to annotate your classes with the `@Transactional` annotation, add `@EnableTransactionManagement` to your configuration, and then expect you to understand how it all works. This section explains the inner @@ -556,9 +558,9 @@ Conceptually, calling a method on a transactional proxy looks like this... image::images/tx.png[width=400] - [[transaction-declarative-first-example]] ==== Example of declarative transaction implementation + Consider the following interface, and its attendant implementation. This example uses `Foo` and `Bar` classes as placeholders so that you can concentrate on the transaction usage without focusing on a particular domain model. For the purposes of this example, @@ -783,9 +785,9 @@ insertFoo(..) method of the DefaultFooService class have been truncated for clar ---- - [[transaction-declarative-rolling-back]] ==== Rolling back a declarative transaction + The previous section outlined the basics of how to specify transactional settings for classes, typically service layer classes, declaratively in your application. This section describes how you can control the rollback of transactions in a simple @@ -873,9 +875,9 @@ possible. Programmatic rollback is available should you absolutely need it, but usage flies in the face of achieving a clean POJO-based architecture. - [[transaction-declarative-diff-tx]] ==== Configuring different transactional semantics for different beans + Consider the scenario where you have a number of service layer objects, and you want to apply a __totally different__ transactional configuration to each of them. You do this by defining distinct `` elements with differing `pointcut` and @@ -989,7 +991,6 @@ transactional settings. ---- - [[transaction-declarative-txadvice-settings]] ==== settings @@ -1053,7 +1054,6 @@ that are nested within `` and `` tags are summarized |=== - [[transaction-declarative-annotations]] ==== Using @Transactional @@ -1232,6 +1232,14 @@ any kind of method. AOP subsystem determines the order of the advice. |=== +[NOTE] +==== +The default advice mode for processing `@Transactional` annotations is "proxy" which +allows for interception of calls through the proxy only; local calls within the same +class cannot get intercepted that way. For a more advanced mode of interception, +consider switching to "aspectj" mode in combination with compile/load-time weaving. +==== + [NOTE] ==== The `proxy-target-class` attribute controls what type of transactional proxies are @@ -1275,7 +1283,6 @@ precedence over the transactional settings defined at the class level. } ---- - [[transaction-declarative-attransactional-settings]] ===== @Transactional settings @@ -1344,9 +1351,9 @@ transactions, the transaction name is always the fully-qualified class name + ". `handlePayment(..)` method of the `BusinessService` class started a transaction, the name of the transaction would be: `com.foo.BusinessService.handlePayment`. - [[tx-multiple-tx-mgrs-with-attransactional]] ===== Multiple Transaction Managers with @Transactional + Most Spring applications only need a single transaction manager, but there may be situations where you want multiple independent transaction managers in a single application. The value attribute of the `@Transactional` annotation can be used to @@ -1391,9 +1398,9 @@ transaction managers, differentiated by the "order" and "account" qualifiers. Th default `` target bean name `transactionManager` will still be used if no specifically qualified PlatformTransactionManager bean is found. - [[tx-custom-attributes]] ===== Custom shortcut annotations + If you find you are repeatedly using the same attributes with `@Transactional` on many different methods, then <> allows you to define custom shortcut annotations for your specific use cases. For example, @@ -1434,9 +1441,9 @@ Here we have used the syntax to define the transaction manager qualifier, but co have included propagation behavior, rollback rules, timeouts etc. - [[tx-propagation]] ==== Transaction propagation + This section describes some semantics of transaction propagation in Spring. Please note that this section is not an introduction to transaction propagation proper; rather it details some of the semantics regarding transaction propagation in Spring. @@ -1444,9 +1451,9 @@ details some of the semantics regarding transaction propagation in Spring. In Spring-managed transactions, be aware of the difference between __physical__ and __logical__ transactions, and how the propagation setting applies to this difference. - [[tx-propagation-required]] ===== Required + image::images/tx_prop_required.png[width=400] PROPAGATION_REQUIRED @@ -1470,9 +1477,9 @@ is not aware) silently marks a transaction as rollback-only, the outer caller st calls commit. The outer caller needs to receive an `UnexpectedRollbackException` to indicate clearly that a rollback was performed instead. - [[tx-propagation-requires_new]] ===== RequiresNew + image::images/tx_prop_requires_new.png[width=400] PROPAGATION_REQUIRES_NEW @@ -1483,9 +1490,9 @@ underlying physical transactions are different and hence can commit or roll back independently, with an outer transaction not affected by an inner transaction's rollback status. - [[tx-propagation-nested]] ===== Nested + `PROPAGATION_NESTED` uses a __single__ physical transaction with multiple savepoints that it can roll back to. Such partial rollbacks allow an inner transaction scope to trigger a rollback __for its scope__, with the outer transaction being able to continue @@ -1494,9 +1501,9 @@ is typically mapped onto JDBC savepoints, so will only work with JDBC resource transactions. See Spring's `DataSourceTransactionManager`. - [[transaction-declarative-applying-more-than-just-tx-advice]] ==== Advising transactional operations + Suppose you want to execute __both__ transactional __and__ some basic profiling advice. How do you effect this in the context of ``? @@ -1674,7 +1681,6 @@ order value. You configure additional aspects in similar fashion. - [[transaction-declarative-aspectj]] ==== Using @Transactional with AspectJ @@ -1729,9 +1735,9 @@ weaving with AspectJ. - [[transaction-programmatic]] === Programmatic transaction management + The Spring Framework provides two means of programmatic transaction management: * Using the `TransactionTemplate`. @@ -1742,7 +1748,6 @@ transaction management. The second approach is similar to using the JTA `UserTransaction` API, although exception handling is less cumbersome. - [[tx-prog-template]] ==== Using the TransactionTemplate @@ -1826,9 +1831,9 @@ Code within the callback can roll the transaction back by calling the }); ---- - [[tx-prog-template-settings]] ===== Specifying transaction settings + You can specify transaction settings such as the propagation mode, the isolation level, the timeout, and so forth on the `TransactionTemplate` either programmatically or in configuration. `TransactionTemplate` instances by default have the @@ -1877,7 +1882,6 @@ different settings (for example, a different isolation level), then you need to two distinct `TransactionTemplate` instances. - [[transaction-programmatic-ptm]] ==== Using the PlatformTransactionManager @@ -1908,9 +1912,9 @@ transactions, roll back, and commit. - [[tx-decl-vs-prog]] === Choosing between programmatic and declarative transaction management + Programmatic transaction management is usually a good idea only if you have a small number of transactional operations. For example, if you have a web application that require transactions only for certain update operations, you may not want to set up @@ -1925,6 +1929,8 @@ management out of business logic, and is not difficult to configure. When using Spring Framework, rather than EJB CMT, the configuration cost of declarative transaction management is greatly reduced. + + [[transaction-event]] === Transaction bound event @@ -1963,8 +1969,11 @@ If no transaction is running, the listener is not invoked at all since we can't semantics. It is however possible to override that behaviour by setting the `fallbackExecution` attribute of the annotation to `true`. + + [[transaction-application-server-integration]] === Application server-specific integration + Spring's transaction abstraction generally is application server agnostic. Additionally, Spring's `JtaTransactionManager` class, which can optionally perform a JNDI lookup for the JTA `UserTransaction` and `TransactionManager` objects, autodetects the location for @@ -1989,9 +1998,9 @@ explicitly; rather, they are chosen automatically, with the standard `JtaTransactionManager` as default fallback. - [[transaction-application-server-integration-websphere]] ==== IBM WebSphere + On WebSphere 6.1.0.9 and above, the recommended Spring JTA transaction manager to use is `WebSphereUowTransactionManager`. This special adapter leverages IBM's `UOWManager` API, which is available in WebSphere Application Server 6.1.0.9 and later. With this adapter, @@ -1999,9 +2008,9 @@ Spring-driven transaction suspension (suspend/resume as initiated by `PROPAGATION_REQUIRES_NEW`) is officially supported by IBM. - [[transaction-application-server-integration-weblogic]] ==== Oracle WebLogic Server + On WebLogic Server 9.0 or above, you typically would use the `WebLogicJtaTransactionManager` instead of the stock `JtaTransactionManager` class. This special WebLogic-specific subclass of the normal `JtaTransactionManager` supports the @@ -2011,12 +2020,10 @@ per-transaction isolation levels, and proper resuming of transactions in all cas - [[transaction-solutions-to-common-problems]] === Solutions to common problems - [[transaction-solutions-to-common-problems-wrong-ptm]] ==== Use of the wrong transaction manager for a specific DataSource @@ -2033,9 +2040,9 @@ treats them as errors. - [[transaction-resources]] -=== Further Resources +=== Further resources + For more information about the Spring Framework's transaction support: * http://www.javaworld.com/javaworld/jw-01-2009/jw-01-spring-transactions.html[Distributed @@ -2049,12 +2056,15 @@ For more information about the Spring Framework's transaction support: + [[dao]] == DAO support + [[dao-introduction]] === Introduction + The Data Access Object (DAO) support in Spring is aimed at making it easy to work with data access technologies like JDBC, Hibernate, JPA or JDO in a consistent way. This allows one to switch between the aforementioned persistence technologies fairly easily @@ -2063,9 +2073,9 @@ specific to each technology. - [[dao-exceptions]] === Consistent exception hierarchy + Spring provides a convenient translation from technology-specific exceptions like `SQLException` to its own exception class hierarchy with the `DataAccessException` as the root exception. These exceptions wrap the original exception so there is never any @@ -2098,9 +2108,9 @@ image::images/DataAccessException.gif[width=400] - [[dao-annotations]] === Annotations used for configuring DAO or Repository classes + The best way to guarantee that your Data Access Objects (DAOs) or repositories provide exception translation is to use the `@Repository` annotation. This annotation also allows the component scanning support to find and configure your DAOs and repositories @@ -2187,12 +2197,15 @@ configure the application context to take advantage of these annotations. + [[jdbc]] == Data access with JDBC + [[jdbc-introduction]] === Introduction to Spring Framework JDBC + The value-add provided by the Spring Framework JDBC abstraction is perhaps best shown by the sequence of actions outlined in the table below. The table shows what actions Spring will take care of and which actions are the responsibility of you, the application @@ -2248,9 +2261,9 @@ The Spring Framework takes care of all the low-level details that can make JDBC tedious API to develop with. - [[jdbc-choose-style]] ==== Choosing an approach for JDBC database access + You can choose among several approaches to form the basis for your JDBC database access. In addition to three flavors of the JdbcTemplate, a new SimpleJdbcInsert and SimplejdbcCall approach optimizes database metadata, and the RDBMS Object style takes a @@ -2277,9 +2290,9 @@ advanced features require a JDBC 3.0 driver. can be called multiple times with various parameter values passed in. - [[jdbc-packages]] ==== Package hierarchy + The Spring Framework's JDBC abstraction framework consists of four different packages, namely `core`, `datasource`, `object`, and `support`. @@ -2314,12 +2327,10 @@ exceptions to be propagated to the caller. See <>. - [[jdbc-core]] === Using the JDBC core classes to control basic JDBC processing and error handling - [[jdbc-JdbcTemplate]] ==== JdbcTemplate @@ -2358,12 +2369,14 @@ corresponding to the fully qualified class name of the template instance (typica [[jdbc-JdbcTemplate-examples]] ===== Examples of JdbcTemplate class usage + This section provides some examples of `JdbcTemplate` class usage. These examples are not an exhaustive list of all of the functionality exposed by the `JdbcTemplate`; see the attendant javadocs for that. [[jdbc-JdbcTemplate-examples-query]] ====== Querying (SELECT) + Here is a simple query for getting the number of rows in a relation: [source,java,indent=0] @@ -2451,7 +2464,8 @@ last code snippet as follows: ---- [[jdbc-JdbcTemplate-examples-update]] -====== Updating (INSERT/UPDATE/DELETE) with jdbcTemplate +====== Updating (INSERT/UPDATE/DELETE) with JdbcTemplate + You use the `update(..)` method to perform insert, update and delete operations. Parameter values are usually provided as var args or alternatively as an object array. @@ -2480,7 +2494,8 @@ Parameter values are usually provided as var args or alternatively as an object ---- [[jdbc-JdbcTemplate-examples-other]] -====== Other jdbcTemplate operations +====== Other JdbcTemplate operations + You can use the `execute(..)` method to execute any arbitrary SQL, and as such the method is often used for DDL statements. It is heavily overloaded with variants taking callback interfaces, binding variable arrays, and so on. @@ -2502,7 +2517,6 @@ procedure support is <>. Long.valueOf(unionId)); ---- - [[jdbc-JdbcTemplate-idioms]] ===== JdbcTemplate best practices @@ -2629,7 +2643,6 @@ databases, which requires multiple `DataSources`, and subsequently multiple diff configured `JdbcTemplates`. - [[jdbc-NamedParameterJdbcTemplate]] ==== NamedParameterJdbcTemplate @@ -2763,7 +2776,6 @@ See also <> for guidelines on using the `NamedParameterJdbcTemplate` class in the context of an application. - [[jdbc-SQLExceptionTranslator]] ==== SQLExceptionTranslator @@ -2857,9 +2869,9 @@ The custom translator is passed a data source in order to look up the error code `sql-error-codes.xml`. - [[jdbc-statements-executing]] ==== Executing statements + Executing an SQL statement requires very little code. You need a `DataSource` and a `JdbcTemplate`, including the convenience methods that are provided with the `JdbcTemplate`. The following example shows what you need to include for a minimal but @@ -2886,9 +2898,9 @@ fully functional class that creates a new table: ---- - [[jdbc-statements-querying]] ==== Running queries + Some query methods return a single value. To retrieve a count or a specific value from one row, use `queryForObject(..)`. The latter converts the returned JDBC `Type` to the Java class that is passed in as an argument. If the type conversion is invalid, then an @@ -2948,9 +2960,9 @@ The list returned would look something like this: ---- - [[jdbc-updates]] ==== Updating the database + The following example shows a column updated for a certain primary key. In this example, an SQL statement has placeholders for row parameters. The parameter values can be passed in as varargs or alternatively as an array of objects. Thus primitives should be wrapped @@ -2978,9 +2990,9 @@ in the primitive wrapper classes explicitly or using auto-boxing. ---- - [[jdbc-auto-genereted-keys]] ==== Retrieving auto-generated keys + An `update()` convenience method supports the retrieval of primary keys generated by the database. This support is part of the JDBC 3.0 standard; see Chapter 13.6 of the specification for details. The method takes a `PreparedStatementCreator` as its first @@ -3012,12 +3024,10 @@ following example works on Oracle but may not work on other platforms: - [[jdbc-connections]] === Controlling database connections - [[jdbc-datasource]] ==== DataSource @@ -3110,7 +3120,6 @@ C3P0 configuration: ---- - [[jdbc-DataSourceUtils]] ==== DataSourceUtils @@ -3119,7 +3128,6 @@ The `DataSourceUtils` class is a convenient and powerful helper class that provi supports thread-bound connections with, for example, `DataSourceTransactionManager`. - [[jdbc-SmartDataSource]] ==== SmartDataSource @@ -3129,7 +3137,6 @@ classes using it to query whether the connection should be closed after a given operation. This usage is efficient when you know that you will reuse a connection. - [[jdbc-AbstractDataSource]] ==== AbstractDataSource @@ -3139,7 +3146,6 @@ You extend the `AbstractDataSource` class if you are writing your own `DataSourc implementation. - [[jdbc-SingleConnectionDataSource]] ==== SingleConnectionDataSource @@ -3158,7 +3164,6 @@ application server, in conjunction with a simple JNDI environment. In contrast t excessive creation of physical connections. - [[jdbc-DriverManagerDataSource]] ==== DriverManagerDataSource @@ -3175,7 +3180,6 @@ environment, that it is almost always preferable to use such a connection pool o `DriverManagerDataSource`. - [[jdbc-TransactionAwareDataSourceProxy]] ==== TransactionAwareDataSourceProxy @@ -3223,9 +3227,9 @@ both is just a matter of configuration, if you stick to the required connection pattern. JTA does not support custom isolation levels! - [[jdbc-NativeJdbcExtractor]] ==== NativeJdbcExtractor + Sometimes you need to access vendor specific JDBC methods that differ from the standard JDBC API. This can be problematic if you are running in an application server or with a `DataSource` that wraps the `Connection`, `Statement` and `ResultSet` objects with its @@ -3248,17 +3252,17 @@ object in most environments. See the javadocs for more details. - [[jdbc-advanced-jdbc]] === JDBC batch operations + Most JDBC drivers provide improved performance if you batch multiple calls to the same prepared statement. By grouping updates into batches you limit the number of round trips to the database. - [[jdbc-batch-classic]] ==== Basic batch operations with the JdbcTemplate + You accomplish `JdbcTemplate` batch processing by implementing two methods of a special interface, `BatchPreparedStatementSetter`, and passing that in as the second parameter in your `batchUpdate` method call. Use the `getBatchSize` method to provide the size of @@ -3305,9 +3309,9 @@ you to interrupt a batch once the input source is exhausted. The `isBatchExhaust allows you to signal the end of the batch. - [[jdbc-batch-list]] ==== Batch operations with a List of objects + Both the `JdbcTemplate` and the `NamedParameterJdbcTemplate` provides an alternate way of providing the batch update. Instead of implementing a special batch interface, you provide all parameter values in the call as a list. The framework loops over these @@ -3375,7 +3379,6 @@ The same example using classic JDBC "?" placeholders: } // ... additional methods - } ---- @@ -3384,9 +3387,9 @@ affected rows for each batch entry. This count is reported by the JDBC driver. I count is not available, the JDBC driver returns a -2 value. - [[jdbc-batch-multi]] ==== Batch operations with multiple batches + The last example of a batch update deals with batches that are so large that you want to break them up into several smaller batches. You can of course do this with the methods mentioned above by making multiple calls to the `batchUpdate` method, but there is now a @@ -3425,7 +3428,6 @@ This example shows a batch update using a batch size of 100: } // ... additional methods - } ---- @@ -3440,18 +3442,18 @@ available, the JDBC driver returns a -2 value. - [[jdbc-simple-jdbc]] === Simplifying JDBC operations with the SimpleJdbc classes + The `SimpleJdbcInsert` and `SimpleJdbcCall` classes provide a simplified configuration by taking advantage of database metadata that can be retrieved through the JDBC driver. This means there is less to configure up front, although you can override or turn off the metadata processing if you prefer to provide all the details in your code. - [[jdbc-simple-jdbc-insert-1]] ==== Inserting data using SimpleJdbcInsert + Let's start by looking at the `SimpleJdbcInsert` class with the minimal amount of configuration options. You should instantiate the `SimpleJdbcInsert` in the data access layer's initialization method. For this example, the initializing method is the @@ -3492,9 +3494,9 @@ names of the table as defined in the database. This is because we read the metad order to construct the actual insert statement. - [[jdbc-simple-jdbc-insert-2]] ==== Retrieving auto-generated keys using SimpleJdbcInsert + This example uses the same insert as the preceding, but instead of passing in the id it retrieves the auto-generated key and sets it on the new Actor object. When you create the `SimpleJdbcInsert`, in addition to specifying the table name, you specify the name @@ -3536,9 +3538,9 @@ multiple auto-generated columns, or the generated values are non-numeric, then y use a `KeyHolder` that is returned from the `executeAndReturnKeyHolder` method. - [[jdbc-simple-jdbc-insert-3]] ==== Specifying columns for a SimpleJdbcInsert + You can limit the columns for an insert by specifying a list of column names with the `usingColumns` method: @@ -3567,7 +3569,6 @@ You can limit the columns for an insert by specifying a list of column names wit } // ... additional methods - } ---- @@ -3575,9 +3576,9 @@ The execution of the insert is the same as if you had relied on the metadata to which columns to use. - [[jdbc-simple-jdbc-parameters]] ==== Using SqlParameterSource to provide parameter values + Using a `Map` to provide parameter values works fine, but it's not the most convenient class to use. Spring provides a couple of implementations of the `SqlParameterSource` interface that can be used instead.The first one is `BeanPropertySqlParameterSource`, @@ -3607,7 +3608,6 @@ values. Here is an example: } // ... additional methods - } ---- @@ -3638,7 +3638,6 @@ convenient `addValue` method that can be chained. } // ... additional methods - } ---- @@ -3646,9 +3645,9 @@ As you can see, the configuration is the same; only the executing code has to ch use these alternative input classes. - [[jdbc-simple-jdbc-call-1]] ==== Calling a stored procedure with SimpleJdbcCall + The `SimpleJdbcCall` class leverages metadata in the database to look up names of `in` and `out` parameters, so that you do not have to declare them explicitly. You can declare parameters if you prefer to do that, or if you have parameters such as `ARRAY` @@ -3710,7 +3709,6 @@ of the stored procedure. } // ... additional methods - } ---- @@ -3751,7 +3749,6 @@ the constructor of your `SimpleJdbcCall`. Here is an example of this configurati } // ... additional methods - } ---- @@ -3759,9 +3756,9 @@ By taking this action, you avoid conflicts in the case used for the names of you returned `out` parameters. - [[jdbc-simple-jdbc-call-2]] ==== Explicitly declaring parameters to use for a SimpleJdbcCall + You have seen how the parameters are deduced based on metadata, but you can declare then explicitly if you wish. You do this by creating and configuring `SimpleJdbcCall` with the `declareParameters` method, which takes a variable number of `SqlParameter` objects @@ -3817,9 +3814,9 @@ The execution and end results of the two examples are the same; this one specifi details explicitly rather than relying on metadata. - [[jdbc-params]] ==== How to define SqlParameters + To define a parameter for the SimpleJdbc classes and also for the RDBMS operations classes, covered in <>, you use an `SqlParameter` or one of its subclasses. You typically specify the parameter name and SQL type in the constructor. The SQL type @@ -3856,9 +3853,9 @@ option is to specify an `SqlReturnType` that provides an opportunity to define customized handling of the return values. - [[jdbc-simple-jdbc-call-3]] ==== Calling a stored function using SimpleJdbcCall + You call a stored function in almost the same way as you call a stored procedure, except that you provide a function name rather than a procedure name. You use the `withFunctionName` method as part of the configuration to indicate that we want to make @@ -3910,7 +3907,6 @@ To call this function we again create a `SimpleJdbcCall` in the initialization m } // ... additional methods - } ---- @@ -3918,9 +3914,9 @@ The execute method used returns a `String` containing the return value from the call. - [[jdbc-simple-jdbc-call-4]] ==== Returning ResultSet/REF Cursor from a SimpleJdbcCall + Calling a stored procedure or function that returns a result set is a bit tricky. Some databases return result sets during the JDBC results processing while others require an explicitly registered `out` parameter of a specific type. Both approaches need @@ -3970,7 +3966,6 @@ created by passing in the required class to map to in the `newInstance` method. } // ... additional methods - } ---- @@ -3979,9 +3974,9 @@ The list of Actors is then retrieved from the results map and returned to the ca - [[jdbc-object]] === Modeling JDBC operations as Java objects + The `org.springframework.jdbc.object` package contains classes that allow you to access the database in a more object-oriented manner. As an example, you can execute queries and get the results back as a list containing business objects with the relational @@ -4001,7 +3996,6 @@ continue using these classes. ==== - [[jdbc-SqlQuery]] ==== SqlQuery @@ -4014,7 +4008,6 @@ mapping rows to Java classes. Other implementations that extend `SqlQuery` are `MappingSqlQueryWithParameters` and `UpdatableSqlQuery`. - [[jdbc-MappingSqlQuery]] ==== MappingSqlQuery @@ -4089,7 +4082,6 @@ methods that takes an array of parameter values passed in as varargs. ---- - [[jdbc-SqlUpdate]] ==== SqlUpdate @@ -4133,7 +4125,6 @@ class since it can easily be parameterized by setting SQL and declaring paramete ---- - [[jdbc-StoredProcedure]] ==== StoredProcedure @@ -4354,16 +4345,16 @@ delegate to the superclass' untyped `execute(Map parameters)` method (which has - [[jdbc-parameter-handling]] === Common problems with parameter and data value handling + Common problems with parameters and data values exist in the different approaches provided by the Spring Framework JDBC. - [[jdbc-type-information]] ==== Providing SQL type information for parameters + Usually Spring determines the SQL type of the parameters based on the type of parameter passed in. It is possible to explicitly provide the SQL type to be used when setting parameter values. This is sometimes necessary to correctly set NULL values. @@ -4383,9 +4374,9 @@ You can provide SQL type information in several ways: for registering the SQL type for any of the named parameter values. - [[jdbc-lob]] ==== Handling BLOB and CLOB objects + You can store images, other binary data, and large chunks of text in the database. These large objects are called BLOBs (Binary Large OBject) for binary data and CLOBs (Character Large OBject) for character data. In Spring you can handle these large objects by using @@ -4477,9 +4468,9 @@ with the same instance variable `lobHandler` and a reference to a `DefaultLobHan <2> Using the method `getBlobAsBytes`, retrieve the contents of the BLOB. - [[jdbc-in-clause]] ==== Passing in lists of values for IN clause + The SQL standard allows for selecting rows based on an expression that includes a variable list of values. A typical example would be `select * from T_ACTOR where id in (1, 2, 3)`. This variable list is not directly supported for prepared statements by the @@ -4505,9 +4496,9 @@ clause such as `select * from T_ACTOR where (id, last_name) in \((1, 'Johnson'), 'Harrop'\))`. This of course requires that your database supports this syntax. - [[jdbc-complex-types]] ==== Handling complex types for stored procedure calls + When you call stored procedures you can sometimes use complex types specific to the database. To accommodate these types, Spring provides a `SqlReturnType` for handling them when they are returned from the stored procedure call and `SqlTypeValue` when they @@ -4588,9 +4579,9 @@ it with values from the Java `ARRAY`. - [[jdbc-embedded-database-support]] === Embedded database support + The `org.springframework.jdbc.datasource.embedded` package provides support for embedded Java database engines. Support for http://www.hsqldb.org[HSQL], http://www.h2database.com[H2], and http://db.apache.org/derby[Derby] is provided @@ -4598,15 +4589,14 @@ natively. You can also use an extensible API to plug in new embedded database ty `DataSource` implementations. - [[jdbc-why-embedded-database]] ==== Why use an embedded database? + An embedded database is useful during the development phase of a project because of its lightweight nature. Benefits include ease of configuration, quick startup time, testability, and the ability to rapidly evolve SQL during development. - [[jdbc-embedded-database-xml]] ==== Creating an embedded database using Spring XML @@ -4629,7 +4619,6 @@ embedded database is made available to the Spring container as a bean of type `javax.sql.DataSource` which can then be injected into data access objects as needed. - [[jdbc-embedded-database-java]] ==== Creating an embedded database programmatically @@ -4680,12 +4669,13 @@ public class DataSourceConfig { } ---- + [[jdbc-embedded-database-types]] ==== Selecting the embedded database type - [[jdbc-embedded-database-using-HSQL]] ===== Using HSQL + Spring supports HSQL 1.8.0 and above. HSQL is the default embedded database if no type is specified explicitly. To specify HSQL explicitly, set the `type` attribute of the `embedded-database` tag to `HSQL`. If you are using the builder API, call the @@ -4694,6 +4684,7 @@ specified explicitly. To specify HSQL explicitly, set the `type` attribute of th [[jdbc-embedded-database-using-H2]] ===== Using H2 + Spring supports the H2 database as well. To enable H2, set the `type` attribute of the `embedded-database` tag to `H2`. If you are using the builder API, call the `setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.H2`. @@ -4701,12 +4692,12 @@ Spring supports the H2 database as well. To enable H2, set the `type` attribute [[jdbc-embedded-database-using-Derby]] ===== Using Derby + Spring also supports Apache Derby 10.5 and above. To enable Derby, set the `type` attribute of the `embedded-database` tag to `DERBY`. If you are using the builder API, call the `setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.DERBY`. - [[jdbc-embedded-database-dao-testing]] ==== Testing data access logic with an embedded database @@ -4782,7 +4773,6 @@ the following options. * `` - [[jdbc-embedded-database-extension]] ==== Extending the embedded database support @@ -4799,15 +4789,16 @@ https://jira.spring.io/browse/SPR[jira.spring.io]. [[jdbc-initializing-datasource]] === Initializing a DataSource + The `org.springframework.jdbc.datasource.init` package provides support for initializing an existing `DataSource`. The embedded database support provides one option for creating and initializing a `DataSource` for an application, but sometimes you need to initialize an instance running on a server somewhere. - [[jdbc-initializing-datasource-xml]] ==== Initializing a database using Spring XML + If you want to initialize a database and you can provide a reference to a `DataSource` bean, use the `initialize-database` tag in the `spring-jdbc` namespace: @@ -4889,11 +4880,9 @@ In this example, the two `test-data` scripts use `@@` as statement separator and the `db-schema.sql` uses `;`. This configuration specifies that the default separator is `@@` and override that default for the `db-schema` script. - If you need more control than you get from the XML namespace, you can simply use the `DataSourceInitializer` directly and define it as a component in your application. - [[jdbc-client-component-initialization]] ===== Initialization of other components that depend on the database @@ -4949,8 +4938,10 @@ The second option can also be easy. Some suggestions on how to implement this in == Object Relational Mapping (ORM) Data Access + [[orm-introduction]] === Introduction to ORM with Spring + The Spring Framework supports integration with Hibernate, Java Persistence API (JPA) and Java Data Objects (JDO) for resource management, data access object (DAO) implementations, and transaction strategies. For example, for Hibernate there is @@ -5022,6 +5013,7 @@ Data with JPA] guide from https://spring.io provides a great introduction. [[orm-general]] === General ORM integration considerations + This section highlights considerations that apply to all ORM technologies. The <> section provides more details and also show these features and configurations in a concrete context. @@ -5040,9 +5032,9 @@ transaction managers, business services that use the data access objects and tra managers, web view resolvers, web controllers that use the business services,and so on. - [[orm-resource-mngmnt]] ==== Resource and transaction management + Typical business applications are cluttered with repetitive resource management code. Many projects try to invent their own solutions, sometimes sacrificing proper handling of failures for programming convenience. Spring advocates simple solutions for proper @@ -5065,9 +5057,9 @@ JPA and JDO support through the Hibernate, JPA, and JDO transaction managers as JTA support. For details on transaction support, see the <> chapter. - [[orm-exception-translation]] ==== Exception translation + When you use Hibernate, JPA, or JDO in a DAO, you must decide how to handle the persistence technology's native exception classes. The DAO throws a subclass of a `HibernateException`, `PersistenceException` or `JDOException` depending on the @@ -5117,9 +5109,9 @@ exception hierarchies. - [[orm-hibernate]] === Hibernate + We will start with a coverage of http://www.hibernate.org/[Hibernate 5] in a Spring environment, using it to demonstrate the approach that Spring takes towards integrating O/R mappers. This section will cover many issues in detail and show different variations @@ -5135,7 +5127,6 @@ in late 2015. We therefore recommend Hibernate 5.0 and higher from a 2016+ persp ==== - [[orm-session-factory-setup]] ==== SessionFactory setup in a Spring container @@ -5194,9 +5185,9 @@ You can also access a JNDI-located `SessionFactory`, using Spring's is typically not common outside of an EJB context. - [[orm-hibernate-straight]] ==== Implementing DAOs based on plain Hibernate API + Hibernate has a feature called contextual sessions, wherein Hibernate itself manages one current `Session` per transaction. This is roughly equivalent to Spring's synchronization of one Hibernate `Session` per transaction. A corresponding DAO @@ -5270,9 +5261,9 @@ In summary: you can implement DAOs based on the plain Hibernate API, while still able to participate in Spring-managed transactions. - [[orm-hibernate-tx-declarative]] ==== Declarative transaction demarcation + We recommend that you use Spring's declarative transaction support, which enables you to replace explicit transaction demarcation API calls in your Java code with an AOP transaction interceptor. This transaction interceptor can be configured in a Spring @@ -5352,9 +5343,9 @@ opting into `@Transactional` processing at runtime. ---- - [[orm-hibernate-tx-programmatic]] ==== Programmatic transaction demarcation + You can demarcate transactions in a higher level of the application, on top of such lower-level data access services spanning any number of operations. Nor do restrictions exist on the implementation of the surrounding business service; it just needs a Spring @@ -5416,9 +5407,9 @@ application (via `TransactionStatus`). `TransactionInterceptor` behaves the same default but allows configurable rollback policies per method. - [[orm-hibernate-tx-strategies]] ==== Transaction management strategies + Both `TransactionTemplate` and `TransactionInterceptor` delegate the actual transaction handling to a `PlatformTransactionManager` instance, which can be a `HibernateTransactionManager` (for a single Hibernate `SessionFactory`, using a @@ -5454,9 +5445,9 @@ exposes the Hibernate transaction as a JDBC transaction if you have set up the p `dataSource` property of the `HibernateTransactionManager` class. - [[orm-hibernate-resources]] ==== Comparing container-managed and locally defined resources + You can switch between a container-managed JNDI `SessionFactory` and a locally defined one, without having to change a single line of application code. Whether to keep resource definitions in the container or locally within the application is mainly a @@ -5500,9 +5491,9 @@ Hibernate `SessionFactory` through the JCA connector only adds value when used i conjunction with EJBs. - [[orm-hibernate-invalid-jdbc-access-error]] ==== Spurious application server warnings with Hibernate + In some JTA environments with very strict `XADataSource` implementations -- currently only some WebLogic Server and WebSphere versions -- when Hibernate is configured without regard to the JTA `PlatformTransactionManager` object for that environment, it is @@ -5569,15 +5560,14 @@ following events occur when a JTA transaction commits: - [[orm-jdo]] === JDO + Spring supports the standard JDO 2.0 and 2.1 APIs as data access strategy, following the same style as the Hibernate support. The corresponding integration classes reside in the `org.springframework.orm.jdo` package. - [[orm-jdo-setup]] ==== PersistenceManagerFactory setup @@ -5634,9 +5624,9 @@ choose such a setup for a good reason. See <> for a dis the arguments there apply to JDO as well. - [[orm-jdo-daos-straight]] ==== Implementing DAOs based on the plain JDO API + DAOs can also be written directly against plain JDO API, without any Spring dependencies, by using an injected `PersistenceManagerFactory`. The following is an example of a corresponding DAO implementation: @@ -5771,9 +5761,9 @@ familiar with JDO. However, such DAOs throw plain `JDOException`, and you would convert explicitly to Spring's `DataAccessException` (if desired). - [[orm-jdo-tx]] ==== Transaction management + [NOTE] ==== You are __strongly__ encouraged to read <> if you have not done @@ -5839,7 +5829,6 @@ supports retrieval of the underlying JDBC `Connection`. This is the case for JDB JDO 2.0 implementations by default. - [[orm-jdo-dialect]] ==== JdoDialect @@ -5862,9 +5851,9 @@ within Spring's JDO support. - [[orm-jpa]] === JPA + The Spring JPA, available under the `org.springframework.orm.jpa` package, offers comprehensive support for the http://www.oracle.com/technetwork/articles/javaee/jpa-137156.html[Java Persistence @@ -5872,13 +5861,12 @@ API] in a similar manner to the integration with Hibernate or JDO, while being a the underlying implementation in order to provide additional features. - [[orm-jpa-setup]] ==== Three options for JPA setup in a Spring environment + The Spring JPA support offers three ways of setting up the JPA `EntityManagerFactory` that will be used by the application to obtain an entity manager. - [[orm-jpa-setup-lemfb]] ===== LocalEntityManagerFactoryBean @@ -5911,7 +5899,6 @@ provider-specific, often requiring a specific JVM agent to specified on startup. option is sufficient only for stand-alone applications and test environments, for which the JPA specification is designed. - [[orm-jpa-setup-jndi]] ===== Obtaining an EntityManagerFactory from JNDI @@ -5951,7 +5938,6 @@ JNDI-retrieved persistence units should match the persistence unit names that th application uses to refer to them, for example, in `@PersistenceUnit` and `@PersistenceContext` annotations. - [[orm-jpa-setup-lcemfb]] ===== LocalContainerEntityManagerFactoryBean @@ -6085,9 +6071,9 @@ This is important especially when the hosting applications rely on different JPA implementations because the JPA transformers are applied only at class loader level and thus are isolated from each other. - [[orm-jpa-multiple]] ===== Dealing with multiple persistence units + For applications that rely on multiple persistence units locations, stored in various JARS in the classpath, for example, Spring offers the `PersistenceUnitManager` to act as a central repository and to avoid the persistence units discovery process, which can be @@ -6130,9 +6116,9 @@ affect __all__ hosted units, or programmatically, through the `LocalContainerEntityManagerFactoryBean`. - [[orm-jpa-dao]] ==== Implementing DAOs based on JPA: EntityManagerFactory and EntityManager + [NOTE] ==== Although `EntityManagerFactory` instances are thread-safe, `EntityManager` instances are @@ -6269,7 +6255,6 @@ the injections are applied automatically by the Spring container. This is appeal a non-invasiveness perspective, and might feel more natural to JPA developers. - [[orm-jpa-tx]] ==== Spring-driven JPA transactions @@ -6291,7 +6276,6 @@ Spring provides dialects for the EclipseLink, Hibernate and OpenJPA JPA implemen See the next section for details on the `JpaDialect` mechanism. - [[orm-jpa-dialect]] ==== JpaDialect and JpaVendorAdapter @@ -6325,7 +6309,6 @@ See the `JpaDialect` and `JpaVendorAdapter` javadocs for more details of its ope and how they are used within Spring's JPA support. - [[orm-jpa-jta]] ==== Setting up JPA with JTA transaction management @@ -6367,8 +6350,10 @@ less portable, but will be set up for the server's JTA environment out of the bo == Marshalling XML using O/X Mappers + [[oxm-introduction]] === Introduction + In this chapter, we will describe Spring's Object/XML Mapping support. Object/XML Mapping, or O/X mapping for short, is the act of converting an XML document to and from an object. This conversion process is also known as XML Marshalling, or XML @@ -6382,17 +6367,17 @@ stream, or a SAX handler. Some of the benefits of using Spring for your O/X mapping needs are: - ==== Ease of configuration + Spring's bean factory makes it easy to configure marshallers, without needing to construct JAXB context, JiBX binding factories, etc. The marshallers can be configured -as any other bean in your application context. Additionally, XML Schema-based +as any other bean in your application context. Additionally, XML namespace-based configuration is available for a number of marshallers, making the configuration even simpler. +==== Consistent interfaces -==== Consistent Interfaces Spring's O/X mapping operates through two global interfaces: the `Marshaller` and `Unmarshaller` interface. These abstractions allow you to switch O/X mapping frameworks with relative ease, with little or no changes required on the classes that do the @@ -6402,25 +6387,25 @@ other using XMLBeans) in a non-intrusive fashion, leveraging the strength of eac technology. +==== Consistent exception hierarchy -==== Consistent Exception Hierarchy Spring provides a conversion from exceptions from the underlying O/X mapping tool to its own exception hierarchy with the `XmlMappingException` as the root exception. As can be expected, these runtime exceptions wrap the original exception so no information is lost. - [[oxm-marshaller-unmarshaller]] === Marshaller and Unmarshaller + As stated in the introduction, a __marshaller__ serializes an object to XML, and an __unmarshaller__ deserializes XML stream to an object. In this section, we will describe the two Spring interfaces used for this purpose. - [[oxm-marshaller]] ==== Marshaller + Spring abstracts all marshalling operations behind the `org.springframework.oxm.Marshaller` interface, the main method of which is shown below. @@ -6465,9 +6450,9 @@ to determine how your O/X technology of choice manages this. ==== - [[oxm-unmarshaller]] ==== Unmarshaller + Similar to the `Marshaller`, there is the `org.springframework.oxm.Unmarshaller` interface. @@ -6508,9 +6493,9 @@ This means that you can wire up one marshaller class and refer to it both as a marshaller and an unmarshaller in your `applicationContext.xml`. - [[oxm-xmlmappingexception]] ==== XmlMappingException + Spring converts exceptions from the underlying O/X mapping tool to its own exception hierarchy with the `XmlMappingException` as the root exception. As can be expected, these runtime exceptions wrap the original exception so no information will be lost. @@ -6527,9 +6512,9 @@ O/X Mapping exception hierarchy - [[oxm-usage]] === Using Marshaller and Unmarshaller + Spring's OXM can be used for a wide variety of situations. In the following example, we will use it to marshal the settings of a Spring-managed application as an XML file. We will use a simple JavaBean to represent the settings: @@ -6652,9 +6637,9 @@ This sample application produces the following `settings.xml` file: - [[oxm-schema-based-config]] -=== XML Schema-based Configuration +=== XML configuration namespace + Marshallers could be configured more concisely using tags from the OXM namespace. To make these tags available, the appropriate schema has to be referenced first in the preamble of the XML configuration file. Note the 'oxm' related text below: @@ -6686,9 +6671,9 @@ here is how the configuration of a JAXB2 marshaller might look like: - [[oxm-jaxb]] === JAXB + The JAXB binding compiler translates a W3C XML Schema into one or more Java classes, a `jaxb.properties` file, and possibly some resource files. JAXB also offers a way to generate a schema from annotated Java classes. @@ -6699,9 +6684,9 @@ The corresponding integration classes reside in the `org.springframework.oxm.jax package. - [[oxm-jaxb2]] ==== Jaxb2Marshaller + The `Jaxb2Marshaller` class implements both the Spring `Marshaller` and `Unmarshaller` interface. It requires a context path to operate, which you can set using the `contextPath` property. The context path is a list of colon (:) separated Java package @@ -6728,9 +6713,9 @@ validation is performed by specifying one or more schema resource to the bean, l ---- - [[oxm-jaxb2-xsd]] -===== XML Schema-based Configuration +===== XML configuration namespace + The `jaxb2-marshaller` tag configures a `org.springframework.oxm.jaxb.Jaxb2Marshaller`. Here is an example: @@ -6769,9 +6754,9 @@ Available attributes are: - [[oxm-castor]] === Castor + Castor XML mapping is an open source XML binding framework. It allows you to transform the data contained in a java object model into/from an XML document. By default, it does not require any further configuration, though a mapping file can be used to have more @@ -6782,9 +6767,9 @@ http://castor-data-binding.github.io/castor[__Castor web site__]. The Spring integration classes reside in the `org.springframework.oxm.castor` package. - [[oxm-castor-marshaller]] ==== CastorMarshaller + As with JAXB, the `CastorMarshaller` implements both the `Marshaller` and `Unmarshaller` interface. It can be wired up as follows: @@ -6798,9 +6783,9 @@ interface. It can be wired up as follows: ---- - [[oxm-castor-mapping]] ==== Mapping + Although it is possible to rely on Castor's default marshalling behavior, it might be necessary to have more control over it. This can be accomplished using a Castor mapping file. For more information, refer to http://castor-data-binding.github.io/castor/reference-guides/1.3.3/html-single/index.html#xml.mapping[Castor @@ -6819,9 +6804,9 @@ with a classpath resource. ---- - [[oxm-castor-xsd]] -===== XML Schema-based Configuration +===== XML configuration namespace + The `castor-marshaller` tag configures a `org.springframework.oxm.castor.CastorMarshaller`. Here is an example: @@ -6868,9 +6853,9 @@ Available attributes are: - [[oxm-xmlbeans]] === XMLBeans + XMLBeans is an XML binding tool that has full XML Schema support, and offers full XML Infoset fidelity. It takes a different approach to that of most other O/X mapping frameworks, in that all classes that are generated from an XML Schema are all derived @@ -6881,9 +6866,9 @@ web site __]. The Spring-WS integration classes reside in the `org.springframework.oxm.xmlbeans` package. - [[oxm-xmlbeans-marshaller]] ==== XmlBeansMarshaller + The `XmlBeansMarshaller` implements both the `Marshaller` and `Unmarshaller` interfaces. It can be configured as follows: @@ -6904,9 +6889,9 @@ Note that the `XmlBeansMarshaller` can only marshal objects of type `XmlObject`, every `java.lang.Object`. ==== - [[oxm-xmlbeans-xsd]] -===== XML Schema-based Configuration +===== XML configuration namespace + The `xmlbeans-marshaller` tag configures a `org.springframework.oxm.xmlbeans.XmlBeansMarshaller`. Here is an example: @@ -6933,9 +6918,9 @@ Available attributes are: - [[oxm-jibx]] === JiBX + The JiBX framework offers a solution similar to that which JDO provides for ORM: a binding definition defines the rules for how your Java objects are converted to or from XML. After preparing the binding and compiling the classes, a JiBX binding compiler @@ -6947,9 +6932,9 @@ site__]. The Spring integration classes reside in the `org.springframework.oxm.j package. - [[oxm-jibx-marshaller]] ==== JibxMarshaller + The `JibxMarshaller` class implements both the `Marshaller` and `Unmarshaller` interface. To operate, it requires the name of the class to marshal in, which you can set using the `targetClass` property. Optionally, you can set the binding name using the @@ -6970,9 +6955,9 @@ A `JibxMarshaller` is configured for a single class. If you want to marshal mult classes, you have to configure multiple ``JibxMarshaller``s with different `targetClass` property values. - [[oxm-jibx-xsd]] -===== XML Schema-based Configuration +===== XML configuration namespace + The `jibx-marshaller` tag configures a `org.springframework.oxm.jibx.JibxMarshaller`. Here is an example: @@ -7002,9 +6987,9 @@ Available attributes are: - [[oxm-xstream]] === XStream + XStream is a simple library to serialize objects to XML and back again. It does not require any mapping, and generates clean XML. @@ -7013,9 +6998,9 @@ web site__]. The Spring integration classes reside in the `org.springframework.oxm.xstream` package. - [[oxm-xstream-marshaller]] ==== XStreamMarshaller + The `XStreamMarshaller` does not require any configuration, and can be configured in an application context directly. To further customize the XML, you can set an__alias map__, which consists of string aliases mapped to classes: diff --git a/src/asciidoc/integration.adoc b/src/asciidoc/integration.adoc index 132261a44d..78a3830291 100644 --- a/src/asciidoc/integration.adoc +++ b/src/asciidoc/integration.adoc @@ -18,12 +18,16 @@ a number of Java EE (and related) technologies. -- + + [[remoting]] == Remoting and web services using Spring + [[remoting-introduction]] === Introduction + Spring features integration classes for remoting support using various technologies. The remoting support eases the development of remote-enabled services, implemented by your usual (Spring) POJOs. Currently, Spring supports the following remoting technologies: @@ -104,9 +108,9 @@ protocol. - [[remoting-rmi]] === Exposing services using RMI + Using Spring's support for RMI, you can transparently expose your services through the RMI infrastructure. After having this set up, you basically have a configuration similar to remote EJBs, except for the fact that there is no standard support for security @@ -115,7 +119,6 @@ such additional invocation context when using the RMI invoker, so you can for ex plug in security frameworks or custom security credentials here. - [[remoting-rmi-server]] ==== Exporting the service using the RmiServiceExporter @@ -162,9 +165,9 @@ anonymous port will be used to communicate with the service. ==== - [[remoting-rmi-client]] ==== Linking in the service at the client + Our client is a simple object using the `AccountService` to manage accounts: [source,java,indent=0] @@ -205,14 +208,13 @@ will transparently create an invoker and remotely enable the account service thr - [[remoting-caucho-protocols]] === Using Hessian or Burlap to remotely call services via HTTP + Hessian offers a binary HTTP-based remoting protocol. It is developed by Caucho and more information about Hessian itself can be found at http://www.caucho.com[]. - [[remoting-caucho-protocols-hessian]] ==== Wiring up the DispatcherServlet for Hessian and co. @@ -248,7 +250,6 @@ pointing to specific exporter beans. Each servlet name needs to match the bean n its target exporter in this case. - [[remoting-caucho-protocols-hessian-server]] ==== Exposing your beans by using the HessianServiceExporter @@ -306,9 +307,9 @@ the target exporter. ---- - [[remoting-caucho-protocols-hessian-client]] ==== Linking in the service on the client + Using the `HessianProxyFactoryBean` we can link in the service at the client. The same principles apply as with the RMI example. We'll create a separate bean factory or application context and mention the following beans where the `SimpleObject` is using @@ -328,7 +329,6 @@ the `AccountService` to manage accounts: ---- - [[remoting-caucho-protocols-burlap]] ==== Using Burlap We won't discuss Burlap, the XML-based equivalent of Hessian, in detail here, since it @@ -336,9 +336,9 @@ is configured and set up in exactly the same way as the Hessian variant explaine Just replace the word `Hessian` with `Burlap` and you're all set to go. - [[remoting-caucho-protocols-security]] ==== Applying HTTP basic authentication to a service exposed through Hessian or Burlap + One of the advantages of Hessian and Burlap is that we can easily apply HTTP basic authentication, because both protocols are HTTP-based. Your normal HTTP server security mechanism can easily be applied through using the `web.xml` security features, for @@ -372,9 +372,9 @@ at http://projects.spring.io/spring-security/[]. - [[remoting-httpinvoker]] === Exposing services using HTTP invokers + As opposed to Burlap and Hessian, which are both lightweight protocols using their own slim serialization mechanisms, Spring HTTP invokers use the standard Java serialization mechanism to expose services through HTTP. This has a huge advantage if your arguments @@ -404,9 +404,9 @@ http://openjdk.java.net/jeps/290 ==== - [[remoting-httpinvoker-server]] ==== Exposing the service object + Setting up the HTTP invoker infrastructure for a service object resembles closely the way you would do the same using Hessian or Burlap. Just as Hessian support provides the `HessianServiceExporter`, Spring's HttpInvoker support provides the @@ -483,9 +483,9 @@ shown in this example: ---- - [[remoting-httpinvoker-client]] ==== Linking in the service at the client + Again, linking in the service from the client much resembles the way you would do it when using Hessian or Burlap. Using a proxy, Spring will be able to translate your calls to HTTP POST requests to the URL pointing to the exported service. @@ -513,9 +513,9 @@ As mentioned before, you can choose what HTTP client you want to use. By default - [[remoting-web-services]] === Web services + Spring provides full support for standard Java web services APIs: * Exposing web services using JAX-WS @@ -527,9 +527,9 @@ contract-first, document-driven web services - highly recommended for building m future-proof web services. - [[remoting-web-services-jaxws-export-servlet]] ==== Exposing servlet-based web services using JAX-WS + Spring provides a convenient base class for JAX-WS servlet endpoint implementations - `SpringBeanAutowiringSupport`. To expose our `AccountService` we extend Spring's `SpringBeanAutowiringSupport` class and implement our business logic here, usually @@ -582,13 +582,13 @@ EE 5 environments, using the standard contract for JAX-WS servlet endpoint deplo See Java EE 5 web service tutorials for details. - [[remoting-web-services-jaxws-export-standalone]] ==== Exporting standalone web services using JAX-WS -The built-in JAX-WS provider that comes with Oracle's JDK 1.6 supports exposure of web -services using the built-in HTTP server that's included in JDK 1.6 as well. Spring's + +The built-in JAX-WS provider that comes with Oracle's JDK supports exposure of web +services using the built-in HTTP server that's included in the JDK as well. Spring's `SimpleJaxWsServiceExporter` detects all `@WebService` annotated beans in the Spring -application context, exporting them through the default JAX-WS server (the JDK 1.6 HTTP +application context, exporting them through the default JAX-WS server (the JDK HTTP server). In this scenario, the endpoint instances are defined and managed as Spring beans @@ -639,9 +639,9 @@ and Spring's `@Autowired` configuration annotation still being honored: ---- - [[remoting-web-services-jaxws-export-ri]] ==== Exporting web services using the JAX-WS RI's Spring support + Oracle's JAX-WS RI, developed as part of the GlassFish project, ships Spring support as part of its JAX-WS Commons project. This allows for defining JAX-WS endpoints as Spring-managed beans, similar to the standalone mode discussed in the previous section - @@ -660,9 +660,9 @@ Check out https://jax-ws-commons.java.net/spring/[https://jax-ws-commons.java.ne for details on setup and usage style. - [[remoting-web-services-jaxws-access]] ==== Accessing web services using JAX-WS + Spring provides two factory beans to create JAX-WS web service proxies, namely `LocalJaxWsServiceFactoryBean` and `JaxWsPortProxyFactoryBean`. The former can only return a JAX-WS service class for us to work with. The latter is the full-fledged @@ -729,9 +729,9 @@ accordingly first. Check the JAX-WS documentation for details on those requireme - [[remoting-jms]] === JMS + It is also possible to expose services transparently using JMS as the underlying communication protocol. The JMS remoting support in the Spring Framework is pretty basic - it sends and receives on the `same thread` and in the __same non-transactional__ @@ -794,9 +794,9 @@ the client and server. ---- - [[remoting-jms-server]] ==== Server-side configuration + On the server, you just need to expose the service object using the `JmsInvokerServiceExporter`. @@ -844,9 +844,9 @@ On the server, you just need to expose the service object using the ---- - [[remoting-jms-client]] ==== Client-side configuration + The client merely needs to create a client-side proxy that will implement the agreed upon interface ( `CheckingAccountService`). The resulting object created off the back of the following bean definition can be injected into other client side objects, and the @@ -893,7 +893,6 @@ proxy will take care of forwarding the call to the server-side object via JMS. - [[remoting-amqp]] === AMQP Refer to the {doc-spring-amqp}/html/_reference.html#remoting[Spring AMQP Reference Document @@ -901,9 +900,9 @@ Refer to the {doc-spring-amqp}/html/_reference.html#remoting[Spring AMQP Referen - [[remoting-autodection-remote-interfaces]] === Auto-detection is not implemented for remote interfaces + The main reason why auto-detection of implemented interfaces does not occur for remote interfaces is to avoid opening too many doors to remote callers. The target object might implement internal callback interfaces like `InitializingBean` or `DisposableBean` which @@ -922,9 +921,9 @@ effort, and puts you on the safe side regarding controlled exposure of specific - [[remoting-considerations]] === Considerations when choosing a technology + Each and every technology presented here has its drawbacks. You should carefully consider your needs, the services you are exposing and the objects you'll be sending over the wire when choosing a technology. @@ -961,9 +960,9 @@ plugging in third-party or custom solutions here. - [[rest-client-access]] -=== Accessing RESTful services on the Client +=== Accessing RESTful services on the client + The `RestTemplate` is the core class for client-side access to RESTful services. It is conceptually similar to other template classes in Spring, such as `JdbcTemplate` and `JmsTemplate` and other template classes found in other Spring portfolio projects. @@ -978,9 +977,9 @@ This section describes how to use the `RestTemplate` and its associated `HttpMessageConverters`. - [[rest-resttemplate]] ==== RestTemplate + Invoking RESTful services in Java is typically done using a helper class such as Apache HttpComponents `HttpClient`. For common REST operations this approach is too low level as shown below. @@ -1182,9 +1181,9 @@ template will always close the request and handle any errors. Refer to the API documentation for more information on using the execute method and the meaning of its other method arguments. - [[rest-resttemplate-uri]] ===== Working with the URI + For each of the main HTTP methods, the `RestTemplate` provides variants that either take a String URI or `java.net.URI` as the first argument. @@ -1232,9 +1231,9 @@ Or specify each URI component individually: URI uri = uriComponents.toUri(); ---- - [[rest-template-headers]] ===== Dealing with request and response headers + Besides the methods described above, the `RestTemplate` also has the `exchange()` method, which can be used for arbitrary HTTP method execution based on the `HttpEntity` class. @@ -1278,7 +1277,8 @@ to serialize only a subset of the object properties. For example: [[rest-message-conversion]] -==== HTTP Message Conversion +==== HTTP message conversion + Objects passed to and returned from the methods `getForObject()`, `postForLocation()`, and `put()` are converted to HTTP requests and from HTTP responses by `HttpMessageConverters`. The `HttpMessageConverter` interface is shown below to give you @@ -1309,47 +1309,47 @@ a better feel for its functionality Concrete implementations for the main media (mime) types are provided in the framework and are registered by default with the `RestTemplate` on the client-side and with -`AnnotationMethodHandlerAdapter` on the server-side. +`RequestMethodHandlerAdapter` on the server-side. The implementations of ``HttpMessageConverter``s are described in the following sections. For all converters a default media type is used but can be overridden by setting the `supportedMediaTypes` bean property - [[rest-string-converter]] ===== StringHttpMessageConverter + An `HttpMessageConverter` implementation that can read and write Strings from the HTTP request and response. By default, this converter supports all text media types ( `text/{asterisk}`), and writes with a `Content-Type` of `text/plain`. - [[rest-form-converter]] ===== FormHttpMessageConverter + An `HttpMessageConverter` implementation that can read and write form data from the HTTP request and response. By default, this converter reads and writes the media type `application/x-www-form-urlencoded`. Form data is read from and written into a `MultiValueMap`. - [[rest-byte-converter]] ===== ByteArrayHttpMessageConverter + An `HttpMessageConverter` implementation that can read and write byte arrays from the HTTP request and response. By default, this converter supports all media types ( `{asterisk}/{asterisk}`), and writes with a `Content-Type` of `application/octet-stream`. This can be overridden by setting the `supportedMediaTypes` property, and overriding `getContentType(byte[])`. - [[rest-marhsalling-converter]] ===== MarshallingHttpMessageConverter + An `HttpMessageConverter` implementation that can read and write XML using Spring's `Marshaller` and `Unmarshaller` abstractions from the `org.springframework.oxm` package. This converter requires a `Marshaller` and `Unmarshaller` before it can be used. These can be injected via constructor or bean properties. By default this converter supports ( `text/xml`) and ( `application/xml`). - [[rest-mapping-json-converter]] ===== MappingJackson2HttpMessageConverter + An `HttpMessageConverter` implementation that can read and write JSON using Jackson's `ObjectMapper`. JSON mapping can be customized as needed through the use of Jackson's provided annotations. When further control is needed, a custom `ObjectMapper` can be @@ -1357,9 +1357,9 @@ injected through the `ObjectMapper` property for cases where custom JSON serializers/deserializers need to be provided for specific types. By default this converter supports ( `application/json`). - [[rest-mapping-xml-converter]] ===== MappingJackson2XmlHttpMessageConverter + An `HttpMessageConverter` implementation that can read and write XML using https://github.com/FasterXML/jackson-dataformat-xml[Jackson XML] extension's `XmlMapper`. XML mapping can be customized as needed through the use of JAXB @@ -1368,21 +1368,22 @@ can be injected through the `ObjectMapper` property for cases where custom XML serializers/deserializers need to be provided for specific types. By default this converter supports ( `application/xml`). - [[rest-source-converter]] ===== SourceHttpMessageConverter + An `HttpMessageConverter` implementation that can read and write `javax.xml.transform.Source` from the HTTP request and response. Only `DOMSource`, `SAXSource`, and `StreamSource` are supported. By default, this converter supports ( `text/xml`) and ( `application/xml`). - [[rest-buffered-image-converter]] ===== BufferedImageHttpMessageConverter + An `HttpMessageConverter` implementation that can read and write `java.awt.image.BufferedImage` from the HTTP request and response. This converter reads and writes the media type supported by the Java I/O API. + [[rest-async-resttemplate]] ==== Async RestTemplate @@ -1457,9 +1458,9 @@ for more details. - [[ejb-introduction]] === Introduction + As a lightweight container, Spring is often considered an EJB replacement. We do believe that for many if not most applications and use cases, Spring as a container, combined with its rich supporting functionality in the area of transactions, ORM and JDBC access, @@ -1479,14 +1480,13 @@ by discussing this. - [[ejb-access]] === Accessing EJBs - [[ejb-access-concepts]] ==== Concepts + To invoke a method on a local or remote stateless session bean, client code must normally perform a JNDI lookup to obtain the (local or remote) EJB Home object, then use a 'create' method call on that object to obtain the actual (local or remote) EJB object. @@ -1512,9 +1512,9 @@ not need to write another Service Locator, another JNDI lookup, or duplicate met a hand-coded Business Delegate unless you are actually adding real value in such code. - [[ejb-access-local]] ==== Accessing local SLSBs + Assume that we have a web controller that needs to use a local EJB. We'll follow best practice and use the EJB Business Methods Interface pattern, so that the EJB's local interface extends a non EJB-specific business methods interface. Let's call this @@ -1620,9 +1620,9 @@ Although this will not be of interest to the majority of Spring users, those doi programmatic AOP work with EJBs may want to look at `LocalSlsbInvokerInterceptor`. - [[ejb-access-remote]] ==== Accessing remote SLSBs + Accessing remote EJBs is essentially identical to accessing local EJBs, except that the `SimpleRemoteStatelessSessionProxyFactoryBean` or `` configuration element is used. Of course, with or without Spring, remote invocation semantics apply; a @@ -1650,9 +1650,9 @@ the client code knowing or caring. Of course, this is optional; there is nothing stopping you from declaring `RemoteExceptions` in your business interface. - [[ejb-access-ejb2-ejb3]] ==== Accessing EJB 2.x SLSBs versus EJB 3 SLSBs + Accessing EJB 2.x Session Beans and EJB 3 Session Beans via Spring is largely transparent. Spring's EJB accessors, including the `` and `` facilities, transparently adapt to the actual component at runtime. @@ -1666,14 +1666,13 @@ lookups simply provides consistent and more explicit EJB access configuration. - [[ejb-implementation]] === Using Spring's EJB implementation support classes - [[ejb-implementation-ejb3]] ==== EJB 3 injection interceptor + For EJB 3 Session Beans and Message-Driven Beans, Spring provides a convenient interceptor that resolves Spring's `@Autowired` annotation in the EJB component class: `org.springframework.ejb.interceptor.SpringBeanAutowiringInterceptor`. This @@ -1721,9 +1720,9 @@ method, e.g. obtaining a shared `ApplicationContext` from a custom holder class. - [[jms-introduction]] === Introduction + Spring provides a JMS integration framework that simplifies the use of the JMS API much like Spring's integration does for the JDBC API. @@ -1772,12 +1771,10 @@ resource into Spring's transaction management mechanisms. - [[jms-using]] === Using Spring JMS - [[jms-jmstemplate]] ==== JmsTemplate @@ -1828,6 +1825,7 @@ send in generic manner. [[jms-connections]] ==== Connections + The `JmsTemplate` requires a reference to a `ConnectionFactory`. The `ConnectionFactory` is part of the JMS specification and serves as the entry point for working with JMS. It is used by the client application as a factory to create connections with the JMS @@ -1842,9 +1840,9 @@ the EJB or servlet deployment descriptors. To ensure the use of these features w `JmsTemplate` inside an EJB, the client application should ensure that it references the managed implementation of the `ConnectionFactory`. - [[jms-caching-resources]] ===== Caching Messaging Resources + The standard API involves creating many intermediate objects. To send a message the following 'API' walk is performed @@ -1858,9 +1856,9 @@ Between the ConnectionFactory and the Send operation there are three intermediat objects that are created and destroyed. To optimise the resource usage and increase performance two implementations of `ConnectionFactory` are provided. - [[jms-connection-factory]] ===== SingleConnectionFactory + Spring provides an implementation of the `ConnectionFactory` interface, `SingleConnectionFactory`, that will return the same `Connection` on all `createConnection()` calls and ignore calls to `close()`. This is useful for testing and @@ -1868,9 +1866,9 @@ standalone environments so that the same connection can be used for multiple `JmsTemplate` calls that may span any number of transactions. `SingleConnectionFactory` takes a reference to a standard `ConnectionFactory` that would typically come from JNDI. - [[jdbc-connection-factory-caching]] ===== CachingConnectionFactory + The `CachingConnectionFactory` extends the functionality of `SingleConnectionFactory` and adds the caching of Sessions, MessageProducers, and MessageConsumers. The initial cache size is set to 1, use the property `sessionCacheSize` to increase the number of @@ -1884,9 +1882,9 @@ MessageConsumers are cached based on a key composed of the destination, selector noLocal delivery flag, and the durable subscription name (if creating durable consumers). - [[jms-destinations]] ==== Destination Management + Destinations, like ConnectionFactories, are JMS administered objects that can be stored and retrieved in JNDI. When configuring a Spring application context you can use the JNDI factory class `JndiObjectFactoryBean` / `` to perform dependency @@ -1929,9 +1927,9 @@ You can also configure the `JmsTemplate` with a default destination via the prop operations that do not refer to a specific destination. - [[jms-mdp]] ==== Message Listener Containers + One of the most common uses of JMS messages in the EJB world is to drive message-driven beans (MDBs). Spring offers a solution to create message-driven POJOs (MDPs) in a way that does not tie a user to an EJB container. (See <> @@ -1952,9 +1950,9 @@ boilerplate JMS infrastructure concerns to the framework. There are two standard JMS message listener containers packaged with Spring, each with its specialised feature set. - [[jms-mdp-simple]] ===== SimpleMessageListenerContainer + This message listener container is the simpler of the two standard flavors. It creates a fixed number of JMS sessions and consumers at startup, registers the listener using the standard JMS `MessageConsumer.setMessageListener()` method, and leaves it up the JMS @@ -1975,9 +1973,9 @@ Sessions and therefore does not include any other Session operations (such as se response messages) in the transaction protocol. ==== - [[jms-mdp-default]] ===== DefaultMessageListenerContainer + This message listener container is the one used in most cases. In contrast to `SimpleMessageListenerContainer`, this container variant allows for dynamic adaptation to runtime demands and is able to participate in externally managed transactions. Each @@ -2015,6 +2013,7 @@ message listener (including database operations etc). [[jms-tx]] ==== Transaction management + Spring provides a `JmsTransactionManager` that manages transactions for a single JMS `ConnectionFactory`. This allows JMS applications to leverage the managed transaction features of Spring as described in <>. The `JmsTransactionManager` performs @@ -2047,7 +2046,6 @@ transactional JMS `Session`. - [[jms-sending]] === Sending a Message @@ -2108,9 +2106,9 @@ If you created the `JmsTemplate` and specified a default destination, the `send(MessageCreator c)` sends a message to that destination. - [[jms-msg-conversion]] ==== Using Message Converters + In order to facilitate the sending of domain model objects, the `JmsTemplate` has various send methods that take a Java object as an argument for a message's data content. The overloaded methods `convertAndSend()` and `receiveAndConvert()` in @@ -2171,7 +2169,6 @@ MapMessage={ ---- - [[jms-callbacks]] ==== SessionCallback and ProducerCallback @@ -2183,14 +2180,13 @@ these callback methods. - [[jms-receiving]] === Receiving a message - [[jms-receiving-sync]] -==== Synchronous Reception +==== Synchronous reception + While JMS is typically associated with asynchronous processing, it is possible to consume messages synchronously. The overloaded `receive(..)` methods provide this functionality. During a synchronous receive, the calling thread blocks until a message @@ -2199,9 +2195,8 @@ potentially be blocked indefinitely. The property `receiveTimeout` specifies how the receiver should wait before giving up waiting for a message. - [[jms-asynchronousMessageReception]] -==== Asynchronous Reception - Message-Driven POJOs +==== Asynchronous reception: Message-Driven POJOs [NOTE] ==== @@ -2271,9 +2266,8 @@ Please refer to the Spring javadocs of the various message listener containers f description of the features supported by each implementation. - [[jms-receiving-async-session-aware-message-listener]] -==== the SessionAwareMessageListener interface +==== SessionAwareMessageListener interface The `SessionAwareMessageListener` interface is a Spring-specific interface that provides a similar contract to the JMS `MessageListener` interface, but also provides the message @@ -2307,9 +2301,8 @@ interface, when using the `SessionAwareMessageListener` interface, it is the responsibility of the client code to handle any exceptions thrown. - [[jms-receiving-async-message-listener-adapter]] -==== the MessageListenerAdapter +==== MessageListenerAdapter The `MessageListenerAdapter` class is the final component in Spring's asynchronous messaging support: in a nutshell, it allows you to expose almost __any__ class as a MDP @@ -2445,9 +2438,9 @@ please note that this exception __will not__ be swallowed and __will__ propagate call stack). - [[jms-tx-participation]] ==== Processing messages within transactions + Invoking a message listener within a transaction only requires reconfiguration of the listener container. @@ -2505,9 +2498,9 @@ take care of the rest. - [[jms-jca-message-endpoint-manager]] === Support for JCA Message Endpoints + Beginning with version 2.5, Spring also provides support for a JCA-based `MessageListener` container. The `JmsMessageEndpointManager` will attempt to automatically determine the `ActivationSpec` class name from the provider's @@ -2599,6 +2592,7 @@ contract. [[jms-annotated]] === Annotation-driven listener endpoints + The easiest way to receive a message asynchronously is to use the annotated listener endpoint infrastructure. In a nutshell, it allows you to expose a method of a managed bean as a JMS listener endpoint. @@ -2632,6 +2626,7 @@ several JMS destinations to the same method by adding additional `@JmsListener` declarations to it. On Java 6 and 7, you can use the `@JmsListeners` annotation. ==== + [[jms-annotated-support]] ==== Enable listener endpoint annotations @@ -2683,6 +2678,7 @@ element. ---- + [[jms-annotated-programmatic-registration]] ==== Programmatic endpoints registration @@ -2717,6 +2713,7 @@ describing a custom invocation mechanism. It should be noted that you could just as well skip the use of `@JmsListener` altogether and only register your endpoints programmatically through `JmsListenerConfigurer`. + [[jms-annotated-method-signature]] ==== Annotated endpoint method signature @@ -2794,6 +2791,7 @@ annotate the payload with `@Valid` and configure the necessary validator as foll } ---- + [[jms-annotated-response]] ==== Response management @@ -2863,6 +2861,7 @@ example can be rewritten as follows: [[jms-namespace]] === JMS namespace support + Spring provides an XML namespace for simplifying JMS configuration. To use the JMS namespace elements you will need to reference the JMS schema: @@ -3163,14 +3162,15 @@ table: + [[jmx]] == JMX - [[jmx-introduction]] === Introduction + The JMX support in Spring provides you with the features to easily and transparently integrate your Spring application into a JMX infrastructure. @@ -3195,9 +3195,9 @@ Spring JMX features. - [[jmx-exporting]] === Exporting your beans to JMX + The core class in Spring's JMX framework is the `MBeanExporter`. This class is responsible for taking your Spring beans and registering them with a JMX `MBeanServer`. For example, consider the following class: @@ -3334,7 +3334,6 @@ supplied to the `MBeanExporter` via the server property. When you supply your ow correctly, you must (of course) have a JMX implementation on your classpath. - [[jmx-mbean-server]] ==== Reusing an existing MBeanServer @@ -3382,9 +3381,9 @@ For platforms/cases where the existing `MBeanServer` has a dynamic (or unknown) ---- - [[jmx-exporting-lazy]] ==== Lazy-initialized MBeans + If you configure a bean with the `MBeanExporter` that is also configured for lazy initialization, then the `MBeanExporter` will __not__ break this contract and will avoid instantiating the bean. Instead, it will register a proxy with the `MBeanServer` and @@ -3392,9 +3391,9 @@ will defer obtaining the bean from the container until the first invocation on t occurs. - [[jmx-exporting-auto]] ==== Automatic registration of MBeans + Any beans that are exported through the `MBeanExporter` and are already valid MBeans are registered as-is with the `MBeanServer` without further intervention from Spring. MBeans can be automatically detected by the `MBeanExporter` by setting the `autodetect` @@ -3416,9 +3415,9 @@ registration have their bean name used as the `ObjectName`. This behavior can be overridden as detailed in <>. - [[jmx-exporting-registration-behavior]] ==== Controlling the registration behavior + Consider the scenario where a Spring `MBeanExporter` attempts to register an `MBean` with an `MBeanServer` using the `ObjectName` `'bean:name=testBean1'`. If an `MBean` instance has already been registered under that same `ObjectName`, the default behavior @@ -3488,9 +3487,9 @@ behavior to the `REGISTRATION_REPLACE_EXISTING` behavior: - [[jmx-interface]] === Controlling the management interface of your beans + In the previous example, you had little control over the management interface of your bean; __all__ of the __public__ properties and methods of each exported bean was exposed as JMX attributes and operations respectively. To exercise finer-grained control over @@ -3499,9 +3498,8 @@ attributes and operations, Spring JMX provides a comprehensive and extensible me for controlling the management interfaces of your beans. - [[jmx-interface-assembler]] -==== the MBeanInfoAssembler Interface +==== MBeanInfoAssembler interface Behind the scenes, the `MBeanExporter` delegates to an implementation of the `org.springframework.jmx.export.assembler.MBeanInfoAssembler` interface which is @@ -3514,9 +3512,9 @@ saw in the previous examples). Spring provides two additional implementations of interface using either source-level metadata or any arbitrary interface. - [[jmx-interface-metadata]] -==== Using Source-Level Metadata (Java annotations) +==== Using source-level metadata: Java annotations + Using the `MetadataMBeanInfoAssembler` you can define the management interfaces for your beans using source level metadata. The reading of metadata is encapsulated by the `org.springframework.jmx.export.metadata.JmxAttributeSource` interface. Spring JMX @@ -3657,9 +3655,9 @@ through the assembler property. This is all that is required to take advantage o metadata-driven management interfaces for your Spring-exposed MBeans. - [[jmx-interface-metadata-types]] -==== Source-Level Metadata Types +==== Source-Level metadata types + The following source level metadata types are available for use in Spring JMX: [[jmx-metadata-types]] @@ -3688,7 +3686,7 @@ The following configuration parameters are available for use on these source-lev metadata types: [[jmx-metadata-parameters]] -.Source-Level Metadata Parameters +.Source-Level metadata parameters [cols="1,3,1"] |=== | Parameter| Description| Applies to @@ -3743,9 +3741,8 @@ metadata types: |=== - [[jmx-interface-autodetect]] -==== the AutodetectCapableMBeanInfoAssembler interface +==== AutodetectCapableMBeanInfoAssembler interface To simplify configuration even further, Spring introduces the `AutodetectCapableMBeanInfoAssembler` interface which extends the `MBeanInfoAssembler` @@ -3791,9 +3788,9 @@ meaning. You can address this issue by changing the default behavior for `Object creation as defined in <>. - [[jmx-interface-java]] ==== Defining management interfaces using Java interfaces + In addition to the `MetadataMBeanInfoAssembler`, Spring also includes the `InterfaceBasedMBeanInfoAssembler` which allows you to constrain the methods and properties that are exposed based on the set of methods defined in a collection of @@ -3878,7 +3875,6 @@ on the bean and use all of the interfaces implemented by that bean to create the management interface. - [[jmx-interface-methodnames]] ==== Using MethodNameBasedMBeanInfoAssembler @@ -3914,7 +3910,6 @@ lists of method names. - [[jmx-naming]] === Controlling the ObjectNames for your beans @@ -3929,7 +3924,6 @@ of the `beans` `Map` to an entry in a `Properties` file (or files) to resolve th uses source level metadata to obtain the `ObjectName`. - [[jmx-naming-properties]] ==== Reading ObjectNames from Properties @@ -3985,7 +3979,6 @@ If no entry in the `Properties` instance can be found then the bean key name is the `ObjectName`. - [[jmx-naming-metadata]] ==== Using the MetadataNamingStrategy @@ -4035,9 +4028,9 @@ __com.foo:type=MyClass,name=myBean__. ---- - [[jmx-context-mbeanexport]] ==== Configuring annotation based MBean export + If you prefer using <> to define your management interfaces, then a convenience subclass of `MBeanExporter` is available: `AnnotationMBeanExporter`. When defining an instance of this subclass, the @@ -4099,17 +4092,17 @@ startup... - [[jmx-jsr160]] === JSR-160 Connectors + For remote access, Spring JMX module offers two `FactoryBean` implementations inside the `org.springframework.jmx.support` package for creating both server- and client-side connectors. - [[jmx-jsr160-server]] -==== Server-side Connectors +==== Server-side connectors + To have Spring JMX create, start and expose a JSR-160 `JMXConnectorServer` use the following configuration: @@ -4178,9 +4171,9 @@ snippet of configuration: ---- - [[jmx-jsr160-client]] -==== Client-side Connectors +==== Client-side connectors + To create an `MBeanServerConnection` to a remote JSR-160 enabled `MBeanServer` use the `MBeanServerConnectionFactoryBean` as shown below: @@ -4193,9 +4186,9 @@ To create an `MBeanServerConnection` to a remote JSR-160 enabled `MBeanServer` u ---- - [[jmx-jsr160-protocols]] ==== JMX over Burlap/Hessian/SOAP + JSR-160 permits extensions to the way in which communication is done between the client and the server. The examples above are using the mandatory RMI-based implementation required by the JSR-160 specification (IIOP and JRMP) and the (optional) JMXMP. By using @@ -4217,9 +4210,9 @@ documentation for more information. - [[jmx-proxy]] -=== Accessing MBeans via Proxies +=== Accessing MBeans via proxies + Spring JMX allows you to create proxies that re-route calls to MBeans registered in a local or remote `MBeanServer`. These proxies provide you with a standard Java interface through which you can interact with your MBeans. The code below shows how to configure a @@ -4268,15 +4261,15 @@ created will forward all invocations to the `MBeanServer` via this - [[jmx-notifications]] === Notifications + Spring's JMX offering includes comprehensive support for JMX notifications. - [[jmx-notifications-listeners]] -==== Registering Listeners for Notifications +==== Registering listeners for notifications + Spring's JMX support makes it very easy to register any number of `NotificationListeners` with any number of MBeans (this includes MBeans exported by Spring's `MBeanExporter` and MBeans registered via some other mechanism). By way of an @@ -4495,9 +4488,9 @@ specification (1.2) entitled 'The JMX Notification Model'.) ---- - [[jmx-notifications-publishing]] ==== Publishing Notifications + Spring provides support not just for registering to receive `Notifications`, but also for publishing `Notifications`. @@ -4579,9 +4572,9 @@ you can accept the coupling to both Spring and JMX, then do so. - [[jmx-resources]] -=== Further Resources +=== Further resources + This section contains links to further resources about JMX. * The http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html[JMX @@ -4595,14 +4588,15 @@ homepage] at Oracle + [[cci]] == JCA CCI - [[cci-introduction]] === Introduction + Java EE provides a specification to standardize access to enterprise information systems (EIS): the JCA (Java EE Connector Architecture). This specification is divided into several different parts: @@ -4632,14 +4626,13 @@ special support for such connector-specific APIs. - [[cci-config]] === Configuring CCI - [[cci-config-connector]] ==== Connector configuration + The base resource to use JCA CCI is the `ConnectionFactory` interface. The connector used must provide an implementation of this interface. @@ -4670,7 +4663,6 @@ might be running. ==== - [[cci-config-connectionfactory]] ==== ConnectionFactory configuration in Spring @@ -4714,9 +4706,9 @@ connector. This interface is part of the JCA SPI specification. ==== - [[cci-config-cci-connections]] ==== Configuring CCI connections + JCA CCI allow the developer to configure the connections to the EIS using the `ConnectionSpec` implementation of your connector. In order to configure its properties, you need to wrap the target connection factory with a dedicated adapter, @@ -4771,9 +4763,9 @@ with the `ConnectionSpec` argument, otherwise the variant without argument. ---- - [[cci-config-single-connection]] ==== Using a single CCI connection + If you want to use a single CCI connection, Spring provides a further `ConnectionFactory` adapter to manage this. The `SingleConnectionFactory` adapter class will open a single connection lazily and close it when this bean is destroyed at @@ -4811,14 +4803,13 @@ Use an intermediary `ConnectionSpecConnectionFactoryAdapter` that the - [[cci-using]] === Using Spring's CCI access support - [[cci-record-creator]] ==== Record conversion + One of the aims of the JCA CCI support is to provide convenient facilities for manipulating CCI records. The developer can specify the strategy to create records and extract datas from records, for use with Spring's `CciTemplate`. The following @@ -4891,9 +4882,8 @@ The following sample shows how to use the `RecordExtractor` interface. ---- - [[cci-using-template]] -==== the CciTemplate +==== CciTemplate The `CciTemplate` is the central class of the core CCI support package ( `org.springframework.jca.cci.core`). It simplifies the use of CCI since it handles the @@ -4999,9 +4989,9 @@ output `Record` as return value. ---- - [[cci-using-dao]] ==== DAO support + Spring's CCI support provides a abstract class for DAOs, supporting injection of a `ConnectionFactory` or a `CciTemplate` instances. The name of the class is `CciDaoSupport`: It provides simple `setConnectionFactory` and `setCciTemplate` methods. @@ -5033,9 +5023,9 @@ Internally, this class will create a `CciTemplate` instance for a passed-in ---- - [[automatic-output-generation]] ==== Automatic output record generation + If the connector used only supports the `Interaction.execute(..)` method with input and output records as parameters (that is, it requires the desired output record to be passed in instead of returning an appropriate output record), you can set the @@ -5075,9 +5065,9 @@ instance. ==== - [[template-summary]] ==== Summary + The following table summarizes the mechanisms of the `CciTemplate` class and the corresponding methods called on the CCI `Interaction` interface: @@ -5129,7 +5119,6 @@ corresponding methods called on the CCI `Interaction` interface: |=== - [[cci-straight]] ==== Using a CCI Connection and Interaction directly @@ -5175,7 +5164,6 @@ created inside every callback method. This is completely up to the DAO implement ==== - [[cci-template-example]] ==== Example for CciTemplate usage @@ -5320,9 +5308,9 @@ follows: - [[cci-object]] === Modeling CCI access as operation objects + The `org.springframework.jca.cci.object` package contains support classes that allow you to access the EIS in a different style: through reusable operation objects, analogous to Spring's JDBC operation objects (see JDBC chapter). This will usually encapsulate the @@ -5338,7 +5326,6 @@ CCI support. ==== - [[cci-object-mapping-record]] ==== MappingRecordOperation @@ -5407,7 +5394,6 @@ with a specific `InteractionSpec`: ---- - [[cci-object-mapping-comm-area]] ==== MappingCommAreaOperation @@ -5438,18 +5424,18 @@ input COMMAREA and the output COMMAREA into an output object. ---- - [[cci-automatic-record-gen]] ==== Automatic output record generation + As every `MappingRecordOperation` subclass is based on CciTemplate internally, the same way to automatically generate output records as with `CciTemplate` is available. Every operation object provides a corresponding `setOutputRecordCreator(..)` method. For further information, see <>. - [[cci-object-summary]] ==== Summary + The operation object approach uses records in the same manner as the `CciTemplate` class. [[cci-interaction-methods]] @@ -5468,7 +5454,6 @@ The operation object approach uses records in the same manner as the `CciTemplat |=== - [[cci-objects-mappring-record-example]] ==== Example for MappingRecordOperation usage @@ -5595,7 +5580,6 @@ follows: ---- - [[cci-objects-mapping-comm-area-example]] ==== Example for MappingCommAreaOperation usage @@ -5696,9 +5680,9 @@ follows: - [[cci-tx]] === Transactions + JCA specifies several levels of transaction support for resource adapters. The kind of transactions that your resource adapter supports is specified in its `ra.xml` file. There are essentially three options: none (for example with CICS EPI connector), local @@ -5754,6 +5738,7 @@ For more information on Spring's transaction facilities, see the chapter entitle == Email + [[mail-introduction]] === Introduction @@ -5789,9 +5774,9 @@ of JavaMail MIME messages, called - [[mail-usage]] === Usage + Let's assume there is a business interface called `OrderManager`: [source,java,indent=0] @@ -5808,7 +5793,6 @@ Let us also assume that there is a requirement stating that an email message wit order number needs to be generated and sent to a customer placing the relevant order. - [[mail-usage-simple]] ==== Basic MailSender and SimpleMailMessage usage @@ -5880,7 +5864,6 @@ Find below the bean definitions for the above code: ---- - [[mail-usage-mime]] ==== Using the JavaMailSender and the MimeMessagePreparator @@ -5954,7 +5937,6 @@ Please refer to the relevant javadocs for more information. - [[mail-javamail-mime]] === Using the JavaMail MimeMessageHelper @@ -5979,16 +5961,16 @@ to create a `MimeMessage`: ---- - [[mail-javamail-mime-attachments]] ==== Sending attachments and inline resources + Multipart email messages allow for both attachments and inline resources. Examples of inline resources would be images or a stylesheet you want to use in your message, but that you don't want displayed as an attachment. - [[mail-javamail-mime-attachments-attachment]] ===== Attachments + The following example shows you how to use the `MimeMessageHelper` to send an email along with a single JPEG image attachment. @@ -6013,9 +5995,9 @@ along with a single JPEG image attachment. sender.send(message); ---- - [[mail-javamail-mime-attachments-inline]] ===== Inline resources + The following example shows you how to use the `MimeMessageHelper` to send an email along with an inline image. @@ -6050,9 +6032,9 @@ the resources. If you are doing it the other way around, it won't work! ==== - [[mail-templates]] ==== Creating email content using a templating library + The code in the previous examples explicitly created the content of the email message, using methods calls such as `message.setText(..)`. This is fine for simple cases, and it is okay in the context of the aforementioned examples, where the intent was to show you @@ -6188,14 +6170,15 @@ Velocity template to create email content and send email(s). + [[scheduling]] == Task Execution and Scheduling - [[scheduling-introduction]] === Introduction + The Spring Framework provides abstractions for asynchronous execution and scheduling of tasks with the `TaskExecutor` and `TaskScheduler` interfaces, respectively. Spring also features implementations of those interfaces that support thread pools or delegation to @@ -6213,21 +6196,19 @@ operation). - [[scheduling-task-executor]] === The Spring TaskExecutor abstraction -Spring 2.0 introduces a new abstraction for dealing with executors. Executors are the -Java 5 name for the concept of thread pools. The "executor" naming is due to the fact -that there is no guarantee that the underlying implementation is actually a pool; an -executor may be single-threaded or even synchronous. Spring's abstraction hides -implementation details between Java SE 1.4, Java SE 5 and Java EE environments. +Executors are the JDK name for the concept of thread pools. The "executor" naming is +due to the fact that there is no guarantee that the underlying implementation is +actually a pool; an executor may be single-threaded or even synchronous. Spring's +abstraction hides implementation details between Java SE and Java EE environments. Spring's `TaskExecutor` interface is identical to the `java.util.concurrent.Executor` -interface. In fact, its primary reason for existence was to abstract away the need for -Java 5 when using thread pools. The interface has a single method `execute(Runnable -task)` that accepts a task for execution based on the semantics and configuration of the -thread pool. +interface. In fact, originally, its primary reason for existence was to abstract away +the need for Java 5 when using thread pools. The interface has a single method +`execute(Runnable task)` that accepts a task for execution based on the semantics +and configuration of the thread pool. The `TaskExecutor` was originally created to give other Spring components an abstraction for thread pooling where needed. Components such as the `ApplicationEventMulticaster`, @@ -6236,7 +6217,6 @@ JMS's `AbstractMessageListenerContainer`, and Quartz integration all use the behavior, it is possible to use this abstraction for your own needs. - [[scheduling-task-executor-types]] ==== TaskExecutor types @@ -6286,7 +6266,6 @@ context. Similar to the `SimpleThreadPoolTaskExecutor`, this class implements th `WorkManager` interface and therefore can be used directly as a `WorkManager` as well. - [[scheduling-task-executor-usage]] ==== Using a TaskExecutor @@ -6353,7 +6332,6 @@ been exposed. - [[scheduling-task-scheduler]] === The Spring TaskScheduler abstraction @@ -6387,9 +6365,8 @@ methods are for simple, periodic execution, but the method that accepts a Trigge much more flexible. - [[scheduling-trigger-interface]] -==== the Trigger interface +==== Trigger interface The `Trigger` interface is essentially inspired by JSR-236, which, as of Spring 3.0, has not yet been officially implemented. The basic idea of the `Trigger` is that execution @@ -6428,7 +6405,6 @@ default). Here you can see what methods are available for `Trigger` implementati ---- - [[scheduling-trigger-implementations]] ==== Trigger implementations @@ -6455,7 +6431,6 @@ Such a component could take advantage of dependency injection so that such `Trig could be configured externally and therefore easily modified or extended. - [[scheduling-task-scheduler-implementations]] ==== TaskScheduler implementations @@ -6476,16 +6451,16 @@ recurring, executions. - [[scheduling-annotation-support]] === Annotation Support for Scheduling and Asynchronous Execution + Spring provides annotation support for both task scheduling and asynchronous method execution. - [[scheduling-enable-annotation-support]] ==== Enable scheduling annotations + To enable support for `@Scheduled` and `@Async` annotations add `@EnableScheduling` and `@EnableAsync` to one of your `@Configuration` classes: @@ -6518,10 +6493,18 @@ Notice with the above XML that an executor reference is provided for handling th tasks that correspond to methods with the `@Async` annotation, and the scheduler reference is provided for managing those methods annotated with `@Scheduled`. +[NOTE] +==== +The default advice mode for processing `@Async` annotations is "proxy" which allows +for interception of calls through the proxy only; local calls within the same class +cannot get intercepted that way. For a more advanced mode of interception, consider +switching to "aspectj" mode in combination with compile-time or load-time weaving. +==== [[scheduling-annotation-support-scheduled]] ==== The @Scheduled annotation + 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, meaning that the period will be measured from the completion time of each preceding @@ -6597,9 +6580,9 @@ container and once through the `@Configurable` aspect, with the consequence of e ==== - [[scheduling-annotation-support-async]] ==== The @Async annotation + The `@Async` annotation can be provided on a method so that invocation of that method will occur asynchronously. In other words, the caller will return immediately upon invocation and the actual execution of the method will occur in a task that has been @@ -6693,9 +6676,9 @@ in combination with a custom pointcut. ==== - [[scheduling-annotation-support-qualification]] ==== Executor qualification with @Async + By default when specifying `@Async` on a method, the executor that will be used is the one supplied to the 'annotation-driven' element as described above. However, the `value` attribute of the `@Async` annotation can be used when needing to indicate that an @@ -6715,9 +6698,9 @@ container, or may be the name of a __qualifier__ associated with any `Executor`, specified with the `` element or Spring's `@Qualifier` annotation. - [[scheduling-annotation-support-exception]] ==== Exception management with @Async + When an `@Async` method has a `Future` typed return value, it is easy to manage an exception that was thrown during the method execution as this exception will be thrown when calling `get` on the `Future` result. With a void return type @@ -6741,17 +6724,17 @@ be defined _via_ `AsyncConfigurer` or the `task:annotation-driven` XML element. - [[scheduling-task-namespace]] === The task namespace + Beginning with Spring 3.0, there is an XML namespace for configuring `TaskExecutor` and `TaskScheduler` instances. It also provides a convenient way to configure tasks to be scheduled with a trigger. - [[scheduling-task-namespace-scheduler]] ==== The 'scheduler' element + The following element will create a `ThreadPoolTaskScheduler` instance with the specified thread pool size. @@ -6767,9 +6750,9 @@ provide a 'pool-size' attribute, the default thread pool will only have a single There are no other configuration options for the scheduler. - [[scheduling-task-namespace-executor]] ==== The 'executor' element + The following will create a `ThreadPoolTaskExecutor` instance: [source,xml,indent=0] @@ -6861,9 +6844,9 @@ immediately after executing a task without remaining follow-up work in the task ---- - [[scheduling-task-namespace-scheduled-tasks]] ==== The 'scheduled-tasks' element + The most powerful feature of Spring's task namespace is the support for configuring tasks to be scheduled within a Spring Application Context. This follows an approach similar to other "method-invokers" in Spring, such as that provided by the JMS namespace @@ -6905,18 +6888,18 @@ provided instead. Here is an example demonstrating these other options. - [[scheduling-quartz]] === Using the Quartz Scheduler + Quartz uses `Trigger`, `Job` and `JobDetail` objects to realize scheduling of all kinds of jobs. For the basic concepts behind Quartz, have a look at http://quartz-scheduler.org[]. For convenience purposes, Spring offers a couple of classes that simplify the usage of Quartz within Spring-based applications. - [[scheduling-quartz-jobdetail]] ==== Using the JobDetailFactoryBean + Quartz `JobDetail` objects contain all information needed to run a job. Spring provides a `JobDetailFactoryBean` which provides bean-style properties for XML configuration purposes. Let's have a look at an example: @@ -6975,7 +6958,6 @@ of the `JobDetailFactoryBean` (in the example above, this is `exampleJob`). ==== - [[scheduling-quartz-method-invoking-job]] ==== Using the MethodInvokingJobDetailFactoryBean @@ -7041,7 +7023,6 @@ By default, jobs will run in a concurrent fashion. ==== - [[scheduling-quartz-cron]] ==== Wiring up jobs using triggers and the SchedulerFactoryBean @@ -7102,14 +7083,15 @@ javadocs] for more information. + [[dynamic-language]] == Dynamic language support - [[dynamic-language-introduction]] === Introduction + Spring 2.0 introduces comprehensive support for using classes and objects that have been defined using a dynamic language (such as JRuby) with Spring. This support allows you to write any number of classes in a supported dynamic language, and have the Spring @@ -7135,9 +7117,9 @@ are described in <>. - [[dynamic-language-a-first-example]] === A first example + This bulk of this chapter is concerned with describing the dynamic language support in detail. Before diving into all of the ins and outs of the dynamic language support, let's look at a quick example of a bean defined in a dynamic language. The dynamic @@ -7253,9 +7235,9 @@ configuration. - [[dynamic-language-beans]] === Defining beans that are backed by dynamic languages + This section describes exactly how you define Spring managed beans in any of the supported dynamic languages. @@ -7266,9 +7248,9 @@ you need further details about the dynamic languages themselves, please consult <> at the end of this chapter. - [[dynamic-language-beans-concepts]] ==== Common concepts + The steps involved in using dynamic-language-backed beans are as follows: * Write the test for the dynamic language source code (naturally) @@ -7288,9 +7270,9 @@ source files. You __will__ first want to read the rest of this chapter though, a Spring's dynamic language support does make some (small) assumptions about the contents of your dynamic language source files. - [[dynamic-language-beans-concepts-xml-language-element]] ===== The element + The final step involves defining dynamic-language-backed bean definitions, one for each bean that you want to configure (this is no different from normal JavaBean configuration). However, instead of specifying the fully qualified classname of the @@ -7307,9 +7289,9 @@ The exact attributes and child elements that are available for configuration dep exactly which language the bean has been defined in (the language-specific sections below provide the full lowdown on this). - [[dynamic-language-refreshable-beans]] ===== Refreshable beans + One of the (if not __the__) most compelling value adds of the dynamic language support in Spring is the__'refreshable bean'__ feature. @@ -7441,9 +7423,9 @@ changes to the underlying source file can actually be detected; for example, by that checks the last modified date of a dynamic language source file that exists on the filesystem. - [[dynamic-language-beans-inline]] ===== Inline dynamic language source files + The dynamic language support can also cater for dynamic language source files that are embedded directly in Spring bean definitions. More specifically, the `` element allows you to define dynamic language source immediately @@ -7508,9 +7490,9 @@ a `` region might be better.) ---- - [[dynamic-language-beans-ctor-injection]] ===== Understanding Constructor Injection in the context of dynamic-language-backed beans + There is one __very__ important thing to be aware of with regard to Spring's dynamic language support. Namely, it is not (currently) possible to supply constructor arguments to dynamic-language-backed beans (and hence constructor-injection is not available for @@ -7562,7 +7544,6 @@ injection is the injection style favored by the overwhelming majority of develop anyway (let's leave the discussion as to whether that is a good thing to another day). - [[dynamic-language-beans-jruby]] ==== JRuby beans @@ -7691,7 +7672,6 @@ See <> for some scenarios where you might want to us JRuby-based beans. - [[dynamic-language-beans-groovy]] ==== Groovy beans @@ -7784,9 +7764,9 @@ While this is perfectly legal in Groovy, it is (arguably) a bad practice: in the interests of a consistent approach, you should (in the opinion of this author) respect the standard Java conventions of one (public) class per source file. - [[dynamic-language-beans-groovy-customizer]] ===== Customizing Groovy objects via a callback + The `GroovyObjectCustomizer` interface is a callback that allows you to hook additional creation logic into the process of creating a Groovy-backed bean. For example, implementations of this interface could invoke any required initialization method(s), or @@ -7869,7 +7849,6 @@ in the same place as Spring's `GroovyObjectCustomizer`. ==== - [[dynamic-language-beans-bsh]] ==== BeanShell beans @@ -7949,17 +7928,17 @@ BeanShell-based beans. - [[dynamic-language-scenarios]] === Scenarios + The possible scenarios where defining Spring managed beans in a scripting language would be beneficial are, of course, many and varied. This section describes two possible use cases for the dynamic language support in Spring. - [[dynamic-language-scenarios-controllers]] ==== Scripted Spring MVC Controllers + One group of classes that may benefit from using dynamic-language-backed beans is that of Spring MVC controllers. In pure Spring MVC applications, the navigational flow through a web application is to a large extent determined by code encapsulated within @@ -8024,9 +8003,9 @@ using the Groovy dynamic language. ---- - [[dynamic-language-scenarios-validators]] ==== Scripted Validators + Another area of application development with Spring that may benefit from the flexibility afforded by dynamic-language-backed beans is that of validation. It __may__ be easier to express complex validation logic using a loosely typed dynamic language @@ -8074,15 +8053,15 @@ using the Groovy dynamic language. (See <> for a discussion of the - [[dynamic-language-final-notes]] === Bits and bobs -This last section contains some bits and bobs related to the dynamic language support. +This last section contains some bits and bobs related to the dynamic language support. [[dynamic-language-final-notes-aop]] ==== AOP - advising scripted beans + It is possible to use the Spring AOP framework to advise scripted beans. The Spring AOP framework actually is unaware that a bean that is being advised might be a scripted bean, so all of the AOP use cases and functionality that you may be using or aim to use @@ -8096,9 +8075,9 @@ Spring beans. This really would be an advanced use of the dynamic language suppo though. - [[dynamic-language-final-notes-scopes]] ==== Scoping + In case it is not immediately obvious, scripted beans can of course be scoped just like any other bean. The `scope` attribute on the various `` elements allows you to control the scope of the underlying scripted bean, just as it does with a regular @@ -8134,9 +8113,9 @@ in the Spring Framework. - [[dynamic-language-resources]] -=== Further Resources +=== Further resources + Find below links to further resources about the various dynamic languages described in this chapter. @@ -8145,6 +8124,8 @@ this chapter. * The http://www.beanshell.org/[BeanShell] homepage + + [[cache]] == Cache Abstraction @@ -8152,6 +8133,7 @@ this chapter. [[cache-introduction]] === Introduction + Since version 3.1, Spring Framework provides support for transparently adding caching into an existing Spring application. Similar to the <> support, the caching abstraction allows consistent use of various caching solutions with minimal @@ -8164,6 +8146,7 @@ support of <> and more customization options. [[cache-strategies]] === Understanding the cache abstraction + .Cache vs Buffer **** @@ -8245,8 +8228,10 @@ To use the cache abstraction, the developer needs to take care of two aspects: * cache configuration - the backing cache where the data is stored and read from + [[cache-annotations]] === Declarative annotation-based caching + For caching declaration, the abstraction provides a set of Java annotations: * `@Cacheable` triggers cache population @@ -8257,6 +8242,7 @@ For caching declaration, the abstraction provides a set of Java annotations: Let us take a closer look at each annotation: + [[cache-annotations-cacheable]] ==== @Cacheable annotation @@ -8294,9 +8280,9 @@ the cached method was not actually executed. public Book findBook(ISBN isbn) {...} ---- - [[cache-annotations-cacheable-default-key]] ===== Default Key Generation + Since caches are essentially key-value stores, each invocation of a cached method needs to be translated into a suitable key for cache access. Out of the box, the caching abstraction uses a simple `KeyGenerator` based on the following algorithm: @@ -8326,9 +8312,9 @@ If you want to keep using the previous key strategy, you can configure the depre hash-based 'KeyGenerator' implementation. ==== - [[cache-annotations-cacheable-key]] ===== Custom Key Generation Declaration + Since caching is generic, it is quite likely the target methods have various signatures that cannot be simply mapped on top of the cache structure. This tends to become obvious when the target method has multiple arguments out of which only some are suitable for @@ -8384,7 +8370,6 @@ this, specify the name of the `KeyGenerator` bean implementation to use: public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) ---- - [NOTE] ==== The `key` and `keyGenerator` parameters are mutually exclusive and an operation @@ -8401,7 +8386,6 @@ retrieves the cache(s) defined at the operation level using the configured To provide a different __default__ cache resolver, one needs to implement the `org.springframework.cache.interceptor.CacheResolver` interface. - [[cache-annotations-cacheable-cache-resolver]] ===== Custom cache resolution @@ -8445,6 +8429,7 @@ result in an exception as a custom `CacheManager` will be ignored by the [[cache-annotations-cacheable-synchronized]] ===== Synchronized caching + In a multi-threaded environment, certain operations might be concurrently invoked for the same argument (typically on startup). By default, the cache abstraction does not lock anything and the same value may be computed several times, defeating the purpose @@ -8458,7 +8443,7 @@ entry is updated in the cache. [source,java,indent=0] [subs="verbatim,quotes"] ---- - @Cacheable(cacheNames="foos", **sync="true"**) + @Cacheable(cacheNames="foos", **sync=true**) public Foo executeExpensiveOperation(String id) {...} ---- @@ -8469,9 +8454,9 @@ This is an optional feature and your favorite cache library may not support it. documentation of your cache provider for more details. ==== - [[cache-annotations-cacheable-condition]] ===== Conditional caching + Sometimes, a method might not be suitable for caching all the time (for example, it might depend on the given arguments). The cache annotations support such functionality through the `condition` parameter which takes a `SpEL` expression that is evaluated to @@ -8590,7 +8575,6 @@ than method flow optimization: public Book updateBook(ISBN isbn, BookDescriptor descriptor) ---- - [IMPORTANT] ==== Note that using `@CachePut` and `@Cacheable` annotations on the same method is generally @@ -8645,7 +8629,6 @@ cache) - this is not the case with `@Cacheable` which adds/updates data into the and thus requires a result. - [[cache-annotations-caching]] ==== @Caching annotation @@ -8694,8 +8677,10 @@ gives therefore three levels of customizations per cache operation: * At class level, using `@CacheConfig` * At the operation level + [[cache-annotation-enable]] ==== Enable caching annotations + It is important to note that even though declaring the cache annotations does not automatically trigger their actions - like many things in Spring, the feature has to be declaratively enabled (which means if you ever suspect caching is to blame, you can @@ -8738,8 +8723,16 @@ application through AOP. The configuration is intentionally similar with that of [NOTE] ==== -Advanced customizations using Java config require to implement `CachingConfigurer`, refer -to {api-spring-framework}/cache/annotation/CachingConfigurer.html[the +The default advice mode for processing caching annotations is "proxy" which allows +for interception of calls through the proxy only; local calls within the same class +cannot get intercepted that way. For a more advanced mode of interception, consider +switching to "aspectj" mode in combination with compile-time or load-time weaving. +==== + +[NOTE] +==== +Advanced customizations using Java config require to implement `CachingConfigurer`: +Please refer to {api-spring-framework}/cache/annotation/CachingConfigurer.html[the javadoc for more details]. ==== @@ -8848,7 +8841,6 @@ code, i.e. `@PostConstruct`. ==== - [[cache-annotation-stereotype]] ==== Using custom annotations @@ -8906,6 +8898,7 @@ up its declaration at runtime and understands its meaning. Note that as mentione <>, the annotation-driven behavior needs to be enabled. + [[cache-jsr-107]] === JCache (JSR-107) annotations @@ -8919,8 +8912,9 @@ compliant with the specification. In other words, if you are already using Sprin caching abstraction, you can switch to these standard annotations without changing your cache storage (or configuration, for that matter). + [[cache-jsr-107-summary]] -==== Features summary +==== Feature summary For those who are familiar with Spring's caching annotations, the following table describes the main differences between the Spring annotations and the JSR-107 @@ -9035,8 +9029,10 @@ caches, a consistent and identical key generation implementation should be used. ==== + [[cache-declarative-xml]] === Declarative XML-based caching + If annotations are not an option (no access to the sources or no external code), one can use XML for declarative caching. So instead of annotating the methods for caching, one specifies the target method and the caching directives externally (similar to the @@ -9089,9 +9085,9 @@ we did in the example above by defining the target cache through the `cache:defi - [[cache-store-configuration]] === Configuring the cache storage + 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 controls and manages ``Cache``s and can be used to retrieve these for storage. @@ -9128,7 +9124,6 @@ very fast but it does not provide any management or persistence capabilities nor eviction contracts. - [[cache-store-configuration-ehcache]] ==== Ehcache-based Cache @@ -9152,6 +9147,7 @@ This setup bootstraps the ehcache library inside Spring IoC (through the `ehcach is then wired into the dedicated `CacheManager` implementation. Note the entire ehcache-specific configuration is read from `ehcache.xml`. + [[cache-store-configuration-caffeine]] ==== Caffeine Cache @@ -9188,6 +9184,7 @@ The Caffeine `CacheManager` also supports customs `Caffeine` and `CacheLoader`. the https://github.com/ben-manes/caffeine/wiki[Caffeine documentation] for more information about those. + [[cache-store-configuration-guava]] ==== Guava Cache @@ -9223,6 +9220,7 @@ The Guava `CacheManager` also supports customs `CacheBuilder` and `CacheLoader`. the https://code.google.com/p/guava-libraries/wiki/CachesExplained[Guava documentation] for more information about those. + [[cache-store-configuration-gemfire]] ==== GemFire-based Cache @@ -9232,6 +9230,7 @@ database and provides fully-featured edge caching. For further information on ho GemFire as a CacheManager (and more), please refer to the {doc-spring-gemfire}/html/[Spring Data GemFire reference documentation]. + [[cache-store-configuration-jsr107]] ==== JSR-107 Cache @@ -9254,6 +9253,7 @@ Again, to use it, one simply needs to declare the appropriate `CacheManager`: [[cache-store-configuration-noop]] ==== Dealing with caches without a backing store + Sometimes when switching environments or doing testing, one might have cache declarations without an actual backing cache configured. As this is an invalid configuration, at runtime an exception will be thrown since the caching infrastructure @@ -9284,9 +9284,9 @@ method to be executed every time. - [[cache-plug]] === Plugging-in different back-end caches + Clearly there are plenty of caching products out there that can be used as a backing store. To plug them in, one needs to provide a `CacheManager` and `Cache` implementation since unfortunately there is no available standard that we can use instead. This may @@ -9300,13 +9300,12 @@ that provide integration with Spring can fill in this small configuration gap. - [[cache-specific-config]] === How can I set the TTL/TTI/Eviction policy/XXX feature? + Directly through your cache provider. The cache abstraction is... well, an abstraction not a cache implementation. The solution you are using might support various data policies and different topologies which other solutions do not (take for example the JDK `ConcurrentHashMap`) - exposing that in the cache abstraction would be useless simply because there would no backing support. Such functionality should be controlled directly through the backing cache, when configuring it or through its native API. -