You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
359 lines
19 KiB
359 lines
19 KiB
<?xml version="1.0" encoding="UTF-8"?> |
|
<appendix xml:id="migration-3.2" |
|
xmlns="http://docbook.org/ns/docbook" version="5.0" |
|
xmlns:xl="http://www.w3.org/1999/xlink" |
|
xmlns:xi="http://www.w3.org/2001/XInclude" |
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
|
xsi:schemaLocation=" |
|
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd |
|
http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"> |
|
<title>Migrating to Spring Framework 3.2</title> |
|
|
|
<para>In this appendix we discuss what users will want to know when upgrading to |
|
Spring Framework 3.2. For a general overview of features, please see |
|
<xref linkend="new-in-3.2"/></para> |
|
|
|
<section xml:id="migration-3.2-new-optional-deps"> |
|
<title>Newly optional dependencies</title> |
|
<para>Certain inter-module dependencies are now <literal>optional</literal> at the |
|
Maven POM level where they were once required. For example, <literal>spring-tx</literal> |
|
and its dependence on <literal>spring-context</literal>. This may result in <literal> |
|
ClassNotFoundErrors</literal> or other similar problems for users that have been relying |
|
on transitive dependency management to pull in affected downstream <literal>spring-* |
|
</literal>. To resolve this problem, simply add the appropriate missing jars to your |
|
build configuration.</para> |
|
</section> |
|
|
|
<section xml:id="migration-3.2-ehcache-support"> |
|
<title>EHCache support moved to spring-context-support</title> |
|
<para>Along with Spring's new JCache support, the EHCache support classes in the |
|
<literal>org.springframework.cache.ehcache</literal> package moved from the |
|
<literal>spring-context</literal> module to <literal>spring-context-support</literal>.</para> |
|
</section> |
|
|
|
<section xml:id="migration-3.2-inline-asm"> |
|
<title>Inlining of spring-asm jar</title> |
|
<para>In versions 3.0 and 3.1, we published a discrete <literal>spring-asm</literal> |
|
containing repackaged <literal>org.objectweb.asm</literal> 3.x sources. As of Spring |
|
Framework 3.2, we have upgraded to <literal>org.objectweb.asm</literal> 4.0 and done |
|
away with the separate module jar, favoring inlining these classes directly within |
|
<literal>spring-core</literal>. This should cause no migration issue for most users; |
|
but on the off chance that you have <literal>spring-asm</literal> declared directly |
|
within your project's build script, you'll want to remove it when upgrading to |
|
Spring Framework 3.2.</para> |
|
</section> |
|
|
|
<section xml:id="migration-3.2-inline-cglib"> |
|
<title>Explicit CGLIB dependency no longer required</title> |
|
<para>In prior versions, users of Spring's subclass-based AOP proxies (e.g. via |
|
<literal>proxy-target-class="true"</literal>) and <literal>@Configuration</literal> |
|
class support were required to declare an explicit dependency on CGLIB 2.2. As of |
|
Spring Framework 3.2, we now repackage and inline the newly-released CGLIB 3.0.</para> |
|
<para>This means greater convenience for users, as well as correct functionality for |
|
Java 7 users who are creating subclass proxies of types that contain <literal> |
|
invokedynamic</literal> bytecode instructions. Repackaging CGLIB internally ensures |
|
no classpath conflicts with other third party frameworks that may depend on other |
|
versions of CGLIB.</para> |
|
</section> |
|
|
|
<section xml:id="migration-3.2-osgi-users"> |
|
<title>For OSGi users</title> |
|
<para>OSGi metadata is no longer published within individual Spring Framework |
|
jar MANIFEST.MF files. Please see this |
|
<link xl:href="http://www.springsource.org/springframework-ebr">announcement</link> |
|
for more information about how users can get OSGi-ready versions of Spring |
|
Framework 3.2 jars.</para> |
|
</section> |
|
|
|
<section xml:id="migration-3.2-compatibility-mvc-config"> |
|
<title>MVC Java Config and MVC Namespace</title> |
|
|
|
<para>As explained in <xref linkend="mvc-config-content-negotiation"/>, both |
|
the MVC Java config and the MVC namespace register extensions such as |
|
<filename>.json</filename> and <filename>.xml</filename> if the |
|
corresponding classpath dependencies are present. That means controller |
|
methods may now return JSON or XML formatted content if those |
|
extensions are present in the request URI, |
|
even if the 'Accept' header doesn't request those media types.</para> |
|
|
|
<para>The newly added support for matrix variables is explained in |
|
<xref linkend="mvc-ann-matrix-variables"/>. To preserve backward |
|
compatibility, by default, semicolon content is removed from incoming |
|
request URIs and therefore <interfacename>@MatrixVariable</interfacename> |
|
cannot be used without additional configuration. However, when using |
|
the MVC Java config and the MVC namespace, semicolon content is left |
|
in the URI so that matrix variables are automatically supported. |
|
The removal of semicolon content is controlled through the |
|
<classname>UrlPathHelper</classname> property of |
|
<classname>RequestMappingHandlerMapping</classname>.</para> |
|
</section> |
|
|
|
<section xml:id="migration-3.2-compatibility-uri-variable-values"> |
|
<title>Decoding of URI Variable Values</title> |
|
<para>URI variable values now get decoded when |
|
<code>UrlPathHelper.setUrlDecode</code> is set to <code>false</code>. |
|
See <link xl:href="https://jira.springsource.org/browse/SPR-9098">SPR-9098</link>.</para> |
|
</section> |
|
|
|
<section xml:id="migration-3.2-compatibility-http-patch"> |
|
<title>HTTP PATCH method</title> |
|
<para>The <classname>DispatcherServlet</classname> now allows the |
|
HTTP PATCH method where previously it didn't.</para> |
|
</section> |
|
|
|
<section xml:id="migration-3.2-compatibility-tiles3"> |
|
<title>Tiles 3</title> |
|
|
|
<para>Besides the version number change, the set of Tiles |
|
dependencies has also changed. You will need to have a subset or all of |
|
<filename>tiles-request-api</filename>, <filename>tiles-api</filename>, |
|
<filename>tiles-core</filename>, <filename>tiles-servlet</filename>, |
|
<filename>tiles-jsp</filename>, <filename>tiles-el</filename>. |
|
</para> |
|
</section> |
|
|
|
<section xml:id="migration-3.2-compatibility-spring-mvc-test"> |
|
<title>Spring MVC Test standalone project</title> |
|
|
|
<para>If migrating from the |
|
<link xl:href="https://github.com/SpringSource/spring-test-mvc">spring-test-mvc</link> |
|
standalone project to the <filename>spring-test</filename> module in |
|
Spring Framework 3.2, you will need to adjust the root package |
|
to be <classname>org.springframework.test.web.servlet</classname>.</para> |
|
|
|
<para>You will no longer be able to use the |
|
<classname>MockMvcBuilders</classname> <code>annotationConfigSetup</code> |
|
and <code>xmlConfigSetup</code> options. Instead you'll need to switch |
|
to using the <interfacename>@WebApplicationContext</interfacename> support |
|
of <filename>spring-test</filename> for loading Spring configuration, |
|
then inject a <interfacename>WebApplicationContext</interfacename> into |
|
the test and use it to create a <classname>MockMvc</classname>. |
|
<xref linkend="spring-mvc-test-framework" /> for details.</para> |
|
</section> |
|
|
|
<section xml:id="migration-3.2-compatibility-spring-test"> |
|
<title>Spring Test Dependencies</title> |
|
|
|
<para>The <literal>spring-test</literal> module has been upgraded to |
|
depend on JUnit 4.11 (<literal>junit:junit</literal>), TestNG 6.5.2 |
|
(<literal>org.testng:testng</literal>), and Hamcrest Core 1.3 |
|
(<literal>org.hamcrest:hamcrest-core</literal>). Each of these |
|
dependencies is declared as an <emphasis>optional</emphasis> dependency |
|
in the Maven POM. Furthermore, it is important to note that the JUnit |
|
team has stopped inlining Hamcrest Core within the |
|
<literal>junit:junit</literal> Maven artifact as of JUnit 4.11. Thus, if |
|
your existing JUnit-based tests make use of Hamcrest matchers that were |
|
previously available directly within the <literal>junit:junit</literal> |
|
JAR, you will now need to explicitly declare a dependency on |
|
<literal>org.hamcrest:hamcrest-core</literal>, |
|
<literal>org.hamcrest:hamcrest-library</literal>, or |
|
<literal>org.hamcrest:hamcrest-all</literal>.</para> |
|
</section> |
|
|
|
<section xml:id="migration-3.2-changes"> |
|
<title>Public API changes</title> |
|
|
|
<section xml:id="migration-3.2-api-changes"> |
|
<title>JDiff reports</title> |
|
<para> |
|
Select JDiff reports are now being published to provide users with a convenient |
|
means of understanding what's changed between versions. Going forward these will be |
|
published between each minor version, e.g. from 3.1.3.RELEASE to 3.1.4.RELEASE; from |
|
the latest maintenance version to the latest GA release, e.g. |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/3.1.3.RELEASE_to_3.2.0.RELEASE"> |
|
3.1.3.RELEASE to 3.2.0.RELEASE</link>; and in between each milestone |
|
and/or RC for users who are tracking next-generation development, e.g. |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/3.2.0.RC2_to_3.2.0.RELEASE"> |
|
3.2.0.RC2 to 3.2.0.RELEASE</link>. |
|
</para> |
|
</section> |
|
|
|
<section xml:id="migration-3.2-removals-and-deprecations"> |
|
<title>Deprecations</title> |
|
<para>The following packages and types have been wholly or partially deprecated |
|
in Spring Framework 3.2 and may be removed in a future version. Click through |
|
to the linked Javadoc for each item for exact details. See also the |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/deprecated-list.html"> |
|
complete list of deprecations</link> in the framework.</para> |
|
<itemizedlist> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/orm/ibatis/package-summary.html"> |
|
org.springframework.orm.ibatis</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/backportconcurrent/package-summary.html"> |
|
org.springframework.scheduling.backportconcurrent</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/ejb/support/package-summary.html"> |
|
org.springframework.ejb.support</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/http/converter/xml/XmlAwareFormHttpMessageConverter.html"> |
|
org.springframework.http.converter.xml.XmlAwareFormHttpMessageConverter</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/web/jsf/DelegatingVariableResolver.html"> |
|
org.springframework.web.jsf.DelegatingVariableResolver</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/web/jsf/SpringBeanVariableResolver.html"> |
|
org.springframework.web.jsf.SpringBeanVariableResolver</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/ui/velocity/CommonsLoggingLogSystem.html"> |
|
org.springframework.ui.velocity.CommonsLoggingLogSystem</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/ui/velocity/VelocityEngineUtils.html"> |
|
org.springframework.ui.velocity.VelocityEngineUtils</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/beans/factory/config/BeanReferenceFactoryBean.html"> |
|
org.springframework.beans.factory.config.BeanReferenceFactoryBean</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/beans/factory/config/CommonsLogFactoryBean.html"> |
|
org.springframework.beans.factory.config.CommonsLogFactoryBean</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/instrument/classloading/oc4j/OC4JLoadTimeWeaver.html"> |
|
org.springframework.beans.instrument.classloading.oc4j.OC4JLoadTimeWeaver</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/transaction/jta/OC4JJtaTransactionManager.html"> |
|
org.springframework.transaction.jta.OC4JJtaTransactionManager</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/web/util/ExpressionEvaluationUtils.html"> |
|
org.springframework.web.util.ExpressionEvaluationUtils</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/mvc/annotation/AnnotationMethodHandlerAdapter.html"> |
|
org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/mvc/annotation/AnnotationMethodHandlerExceptionResolver.html"> |
|
org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerExceptionResolver</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/mvc/annotation/DefaultAnnotationHandlerMapping.html"> |
|
org.springframework.web.servlet.mvc.annotation.DefaultAnnotationHandlerMapping</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/mvc/annotation/ServletAnnotationMappingUtils.html"> |
|
org.springframework.web.servlet.mvc.annotation.ServletAnnotationMappingUtils</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/jmx/support/MBeanRegistrationSupport.html"> |
|
org.springframework.jmx.support.MBeanRegistrationSupport</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/test/context/ContextConfigurationAttributes.html"> |
|
org.springframework.test.context.ContextConfigurationAttributes</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/test/context/junit4/AbstractTransactionalJUnit4SpringContextTests.html"> |
|
org.springframework.test.context.junit4.AbstractTransactionalJUnit4SpringContextTests</link>: |
|
use of the <varname>simpleJdbcTemplate</varname> instance variable has been deprecated |
|
in favor of the new <varname>jdbcTemplate</varname> instance variable.</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/test/context/testng/AbstractTransactionalTestNGSpringContextTests.html"> |
|
org.springframework.test.context.testng.AbstractTransactionalTestNGSpringContextTests</link>: |
|
use of the <varname>simpleJdbcTemplate</varname> instance variable has been deprecated |
|
in favor of the new <varname>jdbcTemplate</varname> instance variable.</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/test/jdbc/SimpleJdbcTestUtils.html"> |
|
org.springframework.test.jdbc.SimpleJdbcTestUtils</link> has been deprecated in |
|
favor of <classname>JdbcTestUtils</classname> which now contains all of the |
|
functionality previously available in <classname>SimpleJdbcTestUtils</classname>.</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/view/ContentNegotiatingViewResolver.html"> |
|
org.springframework.web.servlet.view.ContentNegotiatingViewResolver</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/transaction/interceptor/TransactionAspectUtils.html"> |
|
org.springframework.transaction.interceptor.TransactionAspectUtils</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/http/HttpStatus.html"> |
|
org.springframework.http.HttpStatus</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/web/util/UriUtils.html"> |
|
org.springframework.web.util.UriUtils</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/orm/jpa/vendor/TopLinkJpaDialect.html"> |
|
org.springframework.orm.jpa.vendor.TopLinkJpaDialect</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/orm/jpa/vendor/TopLinkJpaVendorAdapter.html"> |
|
org.springframework.orm.jpa.vendor.TopLinkJpaVendorAdapter</link> |
|
</para> |
|
</listitem> |
|
<listitem> |
|
<para> |
|
<link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/util/CachingMapDecorator.html"> |
|
org.springframework.orm.util.CachingMapDecorator</link> |
|
</para> |
|
</listitem> |
|
</itemizedlist> |
|
</section> |
|
</section> |
|
</appendix>
|
|
|