.. only:: html

 .. contents:: Index
    :depth: 2
    :local:

Major changes in 5.3.0 are as follows.

• Migrate to Maven Central repository
• Update Spring Framework to 4.3
• Update Spring Security to 4.1
• Update Spring IO Platform to Athens
• Update MyBatis to 3.4
• Update Hibernate ORM to 5.0
• Changes in some of the specifications of common library
• Blank project changed

Remote repository was migrated from 5.3.0 to Maven Central repository.

• [#664] Modify pom.xml related to "Maven Central" migration

5.3.0 was updated to Spring Framework 4.3.5.RELEASE.

5.3.0 was updated to Spring Security 4.1.4.RELEASE.

Spring IO Platform was updated from 5.3.0 to Athens-SR2.

5.3.0 was updated to MyBatis 3.4.2. In accordance with this update, MyBatis Spring was updated to 1.3.0.

5.3.0 was updated to Hibernate ORM 5.0.11.

Some of the specifications of common library were changed from 5.3.0, in accordance with the bug fixing.

• [#634] @Compare don't display error message for left property in certain cases

Some of the configuration files of blank project were changed from 5.3.0.

Changes as per the migration to Maven Central repository

• [single#264] [multi#298] Modify pom.xml related to "Maven Central" migration

Changes as per version-up of Spring IO Platform

• [single#245] [multi#279] Selenium version mixed in Spring IO Platform Athens-SR1

Changes as per version-up of Spring Framework

• [single#270] [multi#304] Exclude NestedServletException from handling target of SystemExceptionResolver

Changes as per version-up of MyBatis

• [single#261] [multi#295] Since Mybatis 3.4.2, setting of aggressiveLazyLoading = false becomes unnecessary

Other changes

• [single#259] [multi#293] Using DataSourceTransactionManager may be committed on error of commit phase

Migration procedure is as follows.

Note

Notes

Required : Applying the procedure is mandatory

Required by case : Applying the procedure is mandatory under certain conditions

Optional : Applying the procedure is recommended (Procedure to be implemented when required)

- : Applying the procedure is not necessary

[Overall]

.. tabularcolumns:: |p{0.10\linewidth}|p{0.30\linewidth}|p{0.20\linewidth}|p{0.20\linewidth}|p{0.20\linewidth}|

[Spring Framework]

.. tabularcolumns:: |p{0.10\linewidth}|p{0.30\linewidth}|p{0.20\linewidth}|p{0.20\linewidth}|p{0.20\linewidth}|

[Spring Security]

.. tabularcolumns:: |p{0.10\linewidth}|p{0.30\linewidth}|p{0.20\linewidth}|p{0.20\linewidth}|p{0.20\linewidth}|

[Spring MVC]

.. tabularcolumns:: |p{0.10\linewidth}|p{0.30\linewidth}|p{0.20\linewidth}|p{0.20\linewidth}|p{0.20\linewidth}|

[MyBatis]

.. tabularcolumns:: |p{0.10\linewidth}|p{0.30\linewidth}|p{0.20\linewidth}|p{0.20\linewidth}|p{0.20\linewidth}|

[Hibernate ORM]

.. tabularcolumns:: |p{0.10\linewidth}|p{0.30\linewidth}|p{0.20\linewidth}|p{0.20\linewidth}|p{0.20\linewidth}|

pom.xml settings are changed as per the migration to Maven Central repository

[When procedure is required]

Application of this procedure is mandatory.

[Modification method]

• ($YOUR_SINGLE_PROJECT_ROOT/pom.xml)
• ($YOUR_MULTIPLE_PROJECT_ROOT/pom.xml)
• ($YOUR_ECLIPSE_WTP_PROJECT_ROOT/pom.xml)

Delete the settings of terasoluna-gfw-releases and terasoluna-gfw-snapshots.

<repositories>
    <!-- omitted -->
    <!-- ### Deletion part From here ### -->
    <repository>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>terasoluna-gfw-releases</id>
        <url>http://repo.terasoluna.org/nexus/content/repositories/terasoluna-gfw-releases/</url>
    </repository>
    <!-- ### Deletion part Till here ### -->
    <!-- omitted -->
    <!-- ### Deletion part From here ### -->
    <repository>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
        <id>terasoluna-gfw-snapshots</id>
        <url>http://repo.terasoluna.org/nexus/content/repositories/terasoluna-gfw-snapshots/</url>
    </repository>
    <!-- ### Deletion part Till here ### -->
    <!-- omitted -->
</repositories>

Add the settings, when library of SNAPSHOT version is to be used. (Setting example of sonatype-nexus-snapshots is given below).

<repositories>
    <!-- omitted -->
    <!-- ### Addition part From here ### -->
    <repository>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
        <id>sonatype-nexus-snapshots</id>
        <name>Sonatype Nexus Snapshots</name>
        <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </repository>
    <!-- ### Addition part Till here ### -->
    <!-- omitted -->
</repositories>

Update common library and dependent library of TERASOLUNA Server Framework for Java (5.x).

.. tabularcolumns:: |p{0.35\linewidth}|p{0.25\linewidth}|p{0.25\linewidth}|p{0.15\linewidth}|

[When procedure is required]

Application of this procedure is mandatory.

This update procedure is for the project created by using mvn archetype.

Modify the version of pom file of parent project to 5.3.0.RELEASE.

• ($YOUR_MULTIPLE_PROJECT_ROOT/pom.xml)

<!-- omitted -->
<parent>
    <groupId>org.terasoluna.gfw</groupId>
    <artifactId>terasoluna-gfw-parent</artifactId>
    <version>5.3.0.RELEASE</version>                    <!-- ### Modification part ### -->
</parent>
<!-- omitted -->

This update procedure is for the project created by using mvn archetype, or for the project downloaded from release site.

Change the version of pom file of project to 5.3.0.RELEASE.

• ($YOUR_SINGLE_PROJECT/pom.xml)

<!-- omitted -->
<parent>
    <groupId>org.terasoluna.gfw</groupId>
    <artifactId>terasoluna-gfw-parent</artifactId>
    <version>5.3.0.RELEASE</version>                    <!-- ### Modification part ### -->
</parent>
<!-- omitted -->

This update procedure is for the Eclipse WTP project downloaded from release site .

Refer to [Update library while using Eclipse WTP Project] for the update procedure.

Selenium related artifacts are added to version control from Spring IO Platform Athens and version 2.53.1 is specified in Athens - SR2.

Since the dependency on selenium-java 2.46.0 is set in blank project of 5.2.0, versions of Selenium related Artifacts may co-exist if the application created from blank project of 5.2.0 is updated to 5.3.0.

[When procedure is required]

When the version other than 2.53.1 is specified in Selenium related artifacts, it needs to be modified. Modification example is given below for matching the settings with the blank project.

[Modification method]

• ($YOUR_MULTIPLE_PROJECT_ROOT/pom.xml)
• ($YOUR_SINGLE_PROJECT/pom.xml)
• ($YOUR_ECLIPSE_WTP_PROJECT/pom.xml)

Add the following settings.

<!-- omitted -->
<dependency>
   <groupId>org.seleniumhq.selenium</groupId>
   <artifactId>selenium-chrome-driver</artifactId>
   <version>${selenium.version}</version>
</dependency>
<dependency>
   <groupId>org.seleniumhq.selenium</groupId>
   <artifactId>selenium-remote-driver</artifactId>
   <version>${selenium.version}</version>
</dependency>
<dependency>
   <groupId>org.seleniumhq.selenium</groupId>
   <artifactId>selenium-api</artifactId>
   <version>${selenium.version}</version>
</dependency>
<dependency>
   <groupId>org.seleniumhq.selenium</groupId>
   <artifactId>selenium-firefox-driver</artifactId>
   <version>${selenium.version}</version>
</dependency>
<dependency>
   <groupId>org.seleniumhq.selenium</groupId>
   <artifactId>selenium-ie-driver</artifactId>
   <version>${selenium.version}</version>
</dependency>
<dependency>
   <groupId>org.seleniumhq.selenium</groupId>
   <artifactId>selenium-safari-driver</artifactId>
   <version>${selenium.version}</version>
</dependency>
<dependency>
   <groupId>org.seleniumhq.selenium</groupId>
   <artifactId>selenium-support</artifactId>
   <version>${selenium.version}</version>
</dependency>
<!-- omitted -->

[Remarks]

2.46.0 may not work depending on Firefox version. Select the Selenium version to be used according to the browser version supported by project.

When error occurs in the commit phase while using DataSourceTransactionManager, it is likely to be committed in case of default settings.

[When procedure is required]

Application of this procedure is required when DataSourceTransactionManager is being used.

[Modification method]

• ($YOUR_MULTIPLE_PROJECT_ROOT/projectName-env/src/main/resources/META-INF/spring/projectName-env.xml)
• ($YOUR_SINGLE_PROJECT/src/main/resources/META-INF/spring/projectName-env.xml)
• ($YOUR_ECLIPSE_WTP_PROJECT/src/main/resources/META-INF/spring/projectName-env.xml)

rollbackOnCommitFailure property must be changed to true.

<bean id="transactionManager"
    class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
    <property name="dataSource" ref="dataSource" />
    <property name="rollbackOnCommitFailure" value="true" />    <!-- ### Addition part ### -->
</bean>

When object is received as an argument of handler method, the request parameter is likely to be bound to that argument. In case of version before Spring Framework 4.2, binding was prevented by fetching from Model type argument, however it can be specified whether the request parameter is bound in argument by adding binding attribute into @ Model Attribute annotation in the Spring Framework 4.3.

[When procedure is required]

Application of this procedure is optional. Make the following modifications whenever required.

[Modification method]

Binding of request parameters can be avoided and objects stored in session scope can be obtained with type-safety by specifying false in binding attribute of @ ModelAttribute annotation assigned in the argument.

Example)

@RequestMapping(value = "save", method = RequestMethod.POST)
public String save(@Validated({ Wizard1.class, Wizard2.class,
        Wizard3.class }) WizardForm form,
        BindingResult result,
        @ModelAttribute(binding = false) Entity entity,  // Setting part
        RedirectAttributes redirectAttributes) {
    // ...
    return "redirect:/wizard/save?complete";
}

In Spring Security 4.1, the path matching specifications of AntPathRequestMatcher in which Spring Security is being used by default are case-sensitive.

[When procedure is required]

Application of this procedure is required when uppercase and lowercase characters of the path pattern described in @RequestMapping of Controller and the path pattern described in <sec:intercept-url> of spring-security.xml do not match.

Example showing that application of procedure is required)

@RequestMapping(value="/Todo/List")
   public String viewTodoList(){
   //...
}

<sec:http>
    <sec:intercept-url pattern="/todo/list" access="isAuthenticated()" />  <!-- ### Path pattern has lowercase characters ### -->
    <!-- omitted -->
</sec:http>

[Modification method]

When access policy is defined for the endpoint of Spring MVC, uppercase and lowercase characters such as /Todo/List and /Todo/* should be arranged for the values specified in pattern attribute of <sec:intercept-url> tag.

• ($YOUR_MULTIPLE_PROJECT_ROOT/projectName-web/src/main/resources/META-INF/spring/spring-security.xml)
• ($YOUR_SINGLE_PROJECT/src/main/resources/META-INF/spring/spring-security.xml)
• ($YOUR_ECLIPSE_WTP_PROJECT/src/main/resources/META-INF/spring/spring-security.xml)

<sec:http>
    <sec:intercept-url pattern="/Todo/List" access="isAuthenticated()" />  <!-- ### Modification part ### -->
    <!-- omitted -->
</sec:http>

[Remarks]

When specification of wildcards such as * and ** is not included in pattern attribute, add the access policy for the pattern with an extension and for the pattern with / at the end of request path.

Setting example given below shows that only access from users with "ROLE_ADMIN" role of Todo/List is allowed.

<sec:http>
    <sec:intercept-url pattern="/Todo/List.*" access="hasRole('ADMIN')" />
    <sec:intercept-url pattern="/Todo/List/" access="hasRole('ADMIN')" />
    <sec:intercept-url pattern="/Todo/List" access="hasRole('ADMIN')" />
    <!-- omitted -->
</sec:http>

In Spring Framework 4.3, Exception handler of (HandlerExceptionResolver) of Spring MVC captures the org.springframework.web.util.NestedServletException where fatal errors (java.lang.Errorand its subclass), and java.lang.Throwable are wrapped. In accordance with this change, fatal errors may be handled unintentionally and it may not be notified to servlet container.

[When procedure is required]

Application of this procedure is mandatory, when fatal error needs to be notified to servlet container.

[Modification method]

• ($YOUR_MULTIPLE_PROJECT_ROOT/projectName-web/src/main/resources/META-INF/spring/spring-mvc.xml)
• ($YOUR_SINGLE_PROJECT/src/main/resources/META-INF/spring/spring-mvc.xml)
• ($YOUR_ECLIPSE_WTP_PROJECT/src/main/resources/META-INF/spring/spring-mvc.xml)

Specify NestedServletException in the excludedExceptions property of SystemExceptionResolver , in order to avoid handling of NestedServletException.

<bean id="systemExceptionResolver"
    class="org.terasoluna.gfw.web.exception.SystemExceptionResolver">
    <!-- omitted -->
    <property name="excludedExceptions">
        <array>
            <value>org.springframework.web.util.NestedServletException</value>  <!-- ### Addition part ### -->
        </array>
    </property>
    <!-- omitted -->
</bean>

When the super class of NestedServletException such as java.lang.Exception is handled by @ ExceptionHandler , in such case, NestedServletException is handled unintentionally, hence implement the ExceptionHandler method to be thrown again by handling NestedServletException .

@ExceptionHandler(NestedServletException.class)
public void handleNestedServletException(NestedServletException e) throws NestedServletException {
    throw e;
}

In Spring Framework 4.3, it was not possible to access by the method of update system such as POST, in the path defined by <mvc:view-controller>.

[When procedure is required]

When the pages accessed by method of update system such as POST and the HTTP method of forward source cannot be restricted (such as transition to error page), modify this in order to implement Controller instead of <mvc: view - controller>.

[Modification method]

When <mvc:view-controller> is being used, replace with Controller class.

Example)

[Before modification]

<!-- omitted -->
<mvc:view-controller path="/login" view-name="login/form" />   <!-- ### Deletion part ### -->
<!-- omitted -->

[After modification]

Implement Controllerclass.

@Controller
@RequestMapping("/login")
public class LoginController {

   @RequestMapping
   public String loginForm() {
       return "login/form";
   }

}

Delete <mvc:view-controller> line of the created Controller class from spring-mvc.xml.

When checkbox was sent empty as it is in Spring Framework 4.3, Collection object with empty element was bound instead of null .

[When procedure is required]

Application of this procedure is mandatory when the mandatory check of checkbox items is performed based on whether it is null.

[Modification method]

Change mandatory check of checkbox items in order to use @Size and @NotEmpty instead of @NotNull.

Example)

[Before modification]

public class SampleForm {
    @NotNull
    private List<String> list;
    // ...
}

[After modification]

public class SampleForm {
    @NotEmpty // Modification part
    private List<String> list;
    // ...
}

In MyBatis 3.4.2, the default value of aggressiveLazyLoading has been changed to false which is recommended by the guidelines.

[When procedure is required]

Make the following modifications, depending on whether it is an application for which default value (true) of aggressiveLazyLoading before MyBatis 3.4.1 is assumed.

[Modification method]

• ($YOUR_MULTIPLE_PROJECT_ROOT/projectName-domain/src/main/resources/META-INF/mybatis/mybatis-config.xml)
• ($YOUR_SINGLE_PROJECT/src/main/resources/META-INF/mybatis/mybatis-config.xml)
• ($YOUR_ECLIPSE_WTP_PROJECT/src/main/resources/META-INF/mybatis/mybatis-config.xml)

[When setting of aggressiveLazyLoading is omitted (When default value true is applied)]

Set the value of aggressiveLazyLoading to true .

<settings>
    <setting name="aggressiveLazyLoading" value="true"/>  <!-- ### Update part ### -->
</settings>

[When false is being set in aggressiveLazyLoading]

Following settings can be deleted. (Application of this procedure is mandatory).

<settings>
    <setting name="aggressiveLazyLoading" value="false"/>  <!-- ### Deletion part ### -->
</settings>

In MyBatis 3.4, type handlers for converting BLOB �� InputStream and CLOB �� Reader are valid by default, in case of JDBC driver with JDBC 4.0 support.

[When procedure is required]

Application of this procedure is mandatory. Make the following modifications, when TypeHandler is implemented independently and when the requirements are satisfied with TypeHandler provided by MyBatis.

[Modification method]

• ($YOUR_MULTIPLE_PROJECT_ROOT/projectName-domain/src/main/resources/META-INF/mybatis/mybatis-config.xml)
• ($YOUR_SINGLE_PROJECT/src/main/resources/META-INF/mybatis/mybatis-config.xml)
• ($YOUR_ECLIPSE_WTP_PROJECT/src/main/resources/META-INF/mybatis/mybatis-config.xml)

Delete the settings of independently implemented TypeHandler.

Example)

<typeHandlers>
    <!-- omitted -->
    <typeHandler handler="xxx.yyy.zzz.CustomTypeHandler" /> <!-- ### Deletion part ### -->
    <!-- omitted -->
</typeHandlers>

Since the TypeHandler for JSR-310 is registered automatically in MyBatis 3.4, the settings of TypeHandler of JSR-310 are not required.

[When procedure is required]

Application of this procedure is optional. Modify as given below whenever required.

[Modification part]

• ($YOUR_MULTIPLE_PROJECT_ROOT/projectName-domain/src/main/resources/META-INF/mybatis/mybatis-config.xml)
• ($YOUR_SINGLE_PROJECT/src/main/resources/META-INF/mybatis/mybatis-config.xml)
• ($YOUR_ECLIPSE_WTP_PROJECT/src/main/resources/META-INF/mybatis/mybatis-config.xml)

<typeHandlers>
    <!-- omitted -->
    <!-- ### Deletion part From here ### -->
    <typeHandler handler="org.apache.ibatis.type.InstantTypeHandler" />
    <typeHandler handler="org.apache.ibatis.type.LocalDateTimeTypeHandler" />
    <typeHandler handler="org.apache.ibatis.type.LocalDateTypeHandler" />
    <typeHandler handler="org.apache.ibatis.type.LocalTimeTypeHandler" />
    <typeHandler handler="org.apache.ibatis.type.OffsetDateTimeTypeHandler" />
    <typeHandler handler="org.apache.ibatis.type.OffsetTimeTypeHandler" />
    <typeHandler handler="org.apache.ibatis.type.ZonedDateTimeTypeHandler" />
    <typeHandler handler="org.apache.ibatis.type.YearTypeHandler" />
    <typeHandler handler="org.apache.ibatis.type.MonthTypeHandler" />
    <!-- ### Deletion part Till here ### -->
    <!-- omitted -->
</typeHandlers>

In Hibernate ORM 5.0.X, nowait clause may not be added in the SQL to be issued, even if the settings are done in order to use nowait in PostgreSQL (HHH-10797).

[When procedure is required]

As given in the following example, when the pessimistic lock specifying 0 in timeout is set in order to issue nowait clause for PostgreSQL from JPA (Hibernate ORM) and when JPQL is being used, review the measures etc. described in [Modification method].

@Lock(LockModeType.PESSIMISTIC_WRITE)
@QueryHints(@QueryHint(name = "javax.persistence.lock.timeout", value = "0"))
@Query("SELECT t FROM Todo t WHERE t.id = :id")
Todo findOneForUpdate(@Param("id") Integer id);

[Modification method]

Review the following measures and determine the necessity of handling the project status and its handling method.

• Apply and then use the patch to Dialect class provided by Hibernate ORM
• Upgrade the version to Hibernate ORM 5.2.1 or above

This update procedure is for Eclipse WTP project downloaded from release site.

Note

Notes

[Table header]

Non : Blank project which is not dependent on O/R Mapper

MB3 : Blank project for MyBatis3

JPA : Blank project for JPA

[Remarks column]

* : Operation target

Download Eclipse WTP Project of 5.3.0.RELEASE .

Terminate Eclipse, if it is activated.

Update jar file (Delete and then add) of $YOUR_ECLIPSE_WTP_PROJECT/src/main/webapp/WEB-INF/lib.

.. tabularcolumns:: |p{0.25\linewidth}|p{0.30\linewidth}|p{0.30\linewidth}|p{0.05\linewidth}|p{0.05\linewidth}|p{0.05\linewidth}|

Update jar file (delete and then add) of $YOUR_ECLIPSE_WTP_PROJECT/testlib.

.. tabularcolumns:: |p{0.25\linewidth}|p{0.30\linewidth}|p{0.30\linewidth}|p{0.05\linewidth}|p{0.05\linewidth}|p{0.05\linewidth}|

Update jar file (Delete and then add) for storing sources of $YOUR_ECLIPSE_WTP_PROJECT/libsrc .

.. tabularcolumns:: |p{0.25\linewidth}|p{0.30\linewidth}|p{0.30\linewidth}|p{0.05\linewidth}|p{0.05\linewidth}|p{0.05\linewidth}|

Use the substitution string and update the reference library.

• $YOUR_ECLIPSE_WTP_PROJECT/.classpath
• $YOUR_ECLIPSE_WTP_PROJECT/build.xml

.. tabularcolumns:: |p{0.25\linewidth}|p{0.30\linewidth}|p{0.30\linewidth}|p{0.05\linewidth}|p{0.05\linewidth}|p{0.05\linewidth}|

Delete the reference library (following jar file) from settings of Eclipse WTP project.

• $YOUR_ECLIPSE_WTP_PROJECT/.classpath
• $YOUR_ECLIPSE_WTP_PROJECT/build.xml

.. tabularcolumns:: |p{0.30\linewidth}|p{0.55\linewidth}|p{0.05\linewidth}|p{0.05\linewidth}|p{0.05\linewidth}|

[Modification method]

.classpath

<!-- ### Following class path entry needs to be deleted ### -->

<!-- omitted -->

<classpathentry kind="lib"
    path="testlib/commons-logging-1.2.jar"
    sourcepath="libsrc/commons-logging-1.2-sources.jar" />

<classpathentry kind="lib"
    path="src/main/webapp/WEB-INF/lib/jboss-logging-annotations-1.2.0.Final.jar"
    sourcepath="libsrc/jboss-logging-annotations-1.2.0.Final-sources.jar" />

<classpathentry kind="lib"
    path="src/main/webapp/WEB-INF/lib/jboss-transaction-api_1.2_spec-1.0.0.Final.jar"
    sourcepath="libsrc/jboss-transaction-api_1.2_spec-1.0.0.Final-sources.jar" />

build.xml

<!-- ### Following class path entry needs to be deleted ### -->

<path id="build.classpath">
    <!-- omitted -->
    <pathelement location="${testlib.dir}/commons-logging-1.2.jar"/>
    <pathelement location="${lib.dir}/jboss-logging-annotations-1.2.0.Final.jar"/>
    <pathelement location="${lib.dir}/jboss-transaction-api_1.2_spec-1.0.0.Final.jar"/>
    <!-- omitted -->
</path>

Add the reference library (following jar file) to the settings of Eclipse WTP project.

• $YOUR_ECLIPSE_WTP_PROJECT/.classpath
• $YOUR_ECLIPSE_WTP_PROJECT/build.xml

.. tabularcolumns:: |p{0.30\linewidth}|p{0.55\linewidth}|p{0.05\linewidth}|p{0.05\linewidth}|p{0.05\linewidth}|

[Modification method]

.classpath

<!-- ### Following class path entry needs to be added ### -->

<!-- omitted -->

 <classpathentry kind="lib"
    path="src/main/webapp/WEB-INF/lib/geronimo-jta_1.1_spec-1.1.1.jar"
    sourcepath="libsrc/geronimo-jta_1.1_spec-1.1.1-sources.jar" />

 <classpathentry kind="lib"
    path="testlib/htmlunit-2.21.jar"
    sourcepath="libsrc/htmlunit-2.21-sources.jar" />

<!-- omitted -->

build.xml

<!-- ### Following class path entry needs to be added ### -->

<path id="build.classpath">
    <!-- omitted -->
    <pathelement location="${lib.dir}/geronimo-jta_1.1_spec-1.1.1.jar"/>
    <pathelement location="${testlib.dir}/htmlunit-2.21.jar"/>
    <!-- omitted -->
</path>