.. only:: html

 .. contents:: Table of contents
    :depth: 2
    :local:

Main changes in 5.4.1 are as follows.

• Update Spring Framework to 4.3.14
• Update Spring Security to 4.2.4
• Update Spring IO Platform to Brussels-SR5
• Update MyBatis to 3.4.5
• Update Hibernate ORM to 5.0.12
• Changes in some of the common library specifications
• Changes in blank project

From 5.4.1, Spring IO Platform was updated to Brussels-SR5.

From 5.4.1, Spring Framework was updated to 4.3.14.RELEASE.

Note

Spring Framework 4.3.11.RELEASE is used in Spring IO Platform Brussels-SR5 however, version control is performed independently in the common library.

From 5.4.1, Spring Security was updated to 4.2.4.RELEASE.

Note

Spring Framework 4.2.3.RELEASE is used in Spring IO Platform Brussels-SR5 however, version control is performed independently in the common library.

From 5.4.1, MyBatis was updated to 3.4.5. In this update, Mybatis TypeHandlers JSR-310 was deleted.

From 5.4.1, Hibernate ORM was updated to 5.0.12.

From 5.4.1, some of the common library specifications were changed .

• [#702] Log level specification method is not unified
• [#715] Drop dependency for mybatis-typehandlers-jsr310 when upgrade to MyBatis 3.4.5+
• [#741] Update tomcat.version for cargo
• [#747] Wrong full width string in DefaultFullHalf
• [#772] Upgrade to Spring IO Platform Brussels-SR5
• [#797] Update spring and spring security version

From 5.4.1, some of the configuration files of blank project were changed.

• [single#287] [multi#324] fix ojdbc group ID in pom.xml, match officially group ID
• [single#299] [multi#332] Warning about Logback.xml appears in Eclipse.
• [single#315] [multi#333] Should define the dependency to older version Selenium in blank project
• [single#300] [multi#334] Remove definition of trimTokens
• [single#305] [multi#341] Unification of line feed codes
• [single#343] [multi#361] Add library for Test in pom.xml
• [multi#371] define maven-surefire-plugin version

Note

Regarding linefeed code

The line feed codes of blank project were unified with LF.

When source code of blank project is to be used, take care not to mix the line feed code with CRLF.

The migration procedure is as follows.

Note

Legend

Required : This procedure is required

Required by case : This procedure is required with conditions

Optional : This procedure is recommended (Implement it whenever required)

- : This procedure is not required

[General]

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

[Common library]

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

[Blank project]

.. 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}|

Update common libraries and dependent libraries 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}|

[Case where procedure is required]

This procedure is required

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

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

• ($YOUR_MULTIPLE_PROJECT_ROOT/pom.xml)

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

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

Update the version of pom file of project to 5.4.1.RELEASE.

• ($YOUR_SINGLE_PROJECT/pom.xml)

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

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

Refer to Update library at the time of using Eclipse WTP Project for update procedure.

In ExceptionLoggingFilter, log level was determined by exception code however, it is now fixed to ERROR level.

[Case where procedure is required]

When exception code is defined for the exception (※) wherein log is output by ExceptionLoggingFilterand the log other than ERROR level is output intentionally.

Exception that occurs in (※) View(JSP) and Filter and exception to be captured by servlet container without processing in SpringMVC such as java.lang.Error etc.

When exception code is defined for either IOException, ServletException and RuntimeException and its subclass as shown in the following example with the purpose of defining log level of the log output specifically by ExceptionLoggingFilter.

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

<!-- Exception Code Resolver. -->
<bean id="exceptionCodeResolver"
  class="org.terasoluna.gfw.common.exception.SimpleMappingExceptionCodeResolver">
  <!-- Setting and Customization by project. -->
  <property name="exceptionMappings">
    <map>
      <!-- omitted -->
      <entry key="IOException" value="w.xx.fw.9999" /> <!-- IOException and exception code of WARN level in its subclass is defined. -->
    </map>
  </property>
  <property name="defaultExceptionCode" value="e.xx.9999" />
</bean>

[How to modify]

Create a new class that inherits ExceptionLoggingFilterand change to log output process of the version previous to 5.3.1.RELEASE.

• Implementation example of logIOExceptionmethod

@Override
protected void logIOException(IOException ex, ServletRequest request,
        ServletResponse response) {
    getExceptionLogger().log(ex);
}

Log of INFO level and WARN level corresponding to exception code can be output by implementing logServletExceptionas well as logRuntimeExceptionin the same way.

Define the created class in Bean in applicationContext.xml as shown below.

<!-- Filter. -->
<bean id="exceptionLoggingFilter"
    class="com.example.web.exception.ExpansionExceptionLoggingFilter" >
    <property name="exceptionLogger" ref="exceptionLogger" />
</bean>

[Case where procedure is required]

Confirm the following if it matches with any of the following cases.

• org.terasoluna.gfw.common.fullhalf.DefaultFullHalfis used.
• Independent FullHalfConverterclass is created by referring to Development Guidelines.

[Specifications change contents]

Since there is a bug wherein Katakana "ベ" is not converted, the implementation example of org.terasoluna.gfw.common.fullhalf.DefaultFullHalf and Creation of FullHalfConverter class where pair definition of original full width and half width characters is registeredis modified as follows.

Confirm whether there is any impact due to this modification.

【Before modification】

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

【After modification】

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

[Case where procedure is required]

Confirm the following if it matches with any of the following cases.

• Execute test using cargo-maven2-plugin.

[Specifications change contents]

Tomcat version to be used in cargo-maven2-plugin is updated to 8.5.20 on which Spring IO Platform Brussels-SR5 depends.

Since the settings are different in Tomcat8.0 and Tomcat8.5, it is necessary to confirm whether configuration file depends on Tomcat8.0.

In Spring Framework 4.3, the default value of trimTokensproperty of org.springframework.util.AntPathMatcheris false, the definition of AntPathMatcherwhere falseis specifically set, is not required.

Till 5.3.1 version of blank project, AntPathMatcher wherein falseis set in trimTokensproperty, is defined and applied in mvc:path-matchingof mvc:annotation-driven.

From 5.4.1 version, the definition of AntPathMatcheris deleted and it is changed to use the default settings of Spring MVC.

[Case where procedure is required]

This procedure is optional. Perform the following modifications whenever required.

[How to modify]

• ($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)

Please delete the following settings.

<mvc:annotation-driven>
   <!-- omitted -->
   <!-- ### Delete location From here ### -->
   <!-- workaround to CVE-2016-5007. -->
   <mvc:path-matching path-matcher="pathMatcher" />
   <!-- ### Delete location Till here ### -->
</mvc:annotation-driven>

<!-- omitted -->

<!-- ### Delete location From here ### -->
<!-- Setting PathMatcher. -->
<bean id="pathMatcher" class="org.springframework.util.AntPathMatcher">
    <property name="trimTokens" value="false" />
</bean>
<!-- ### Delete location Till here ### -->

DOCTYPE declaration is added to logback.xmlof blank project. There is no problem in the operations even if there is no DOCTYPE declaration, however, it is recommended to add it as a warning of XML syntax violation is displayed in IDE such as Eclipse."

[Case where procedure is required]

This procedure is optional. Perform the following modifications whenever required.

[How to modify]

Perform the following modifications in logback.xmlof project.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE configuration> <!-- ### Add location ### -->
<configuration>

<!-- omitted -->

It is modified as group ID of ojdbc7mentioned in pom.xmlof blank project as it differs when fetched from the official repository (Oracle Maven Repository).

[Case where procedure is required]

This procedure is optional. Perform the following modifications whenever required.

[How to modify]

Change group ID from com.oracleto com.oracle.jdbcas shown below.

【Before modification】

<dependency>
    <groupId>com.oracle</groupId>
    <artifactId>ojdbc7</artifactId>
    <version>${ojdbc.version}</version>
</dependency>

【After modification】

<dependency>
    <groupId>com.oracle.jdbc</groupId>
    <artifactId>ojdbc7</artifactId>
    <version>${ojdbc.version}</version>
</dependency>

Make proper changes in not only pom.xmlbut also Sonatype NEXUS that installs library in com.oracle.

Selenium version to be used in blank project in compliance with Spring IO Platform. Selenium 2.53.1 is used in Spring IO Platform Brussels-SR5.

[Case where procedure is required]

This procedure is optional however, it is recommended to do the following modifications if it matches with the following cases.

• Use Selenium of the version complied with Spring IO Platform.

[How to modify]

Delete Selenium dependent library settings from dependencyManagementtag of pom.xmlof project.

<dependencyManagement>
   <dependencies>

   <!--omitted-->
      <dependency>
          <groupId>org.seleniumhq.selenium</groupId>
          <artifactId>selenium-java</artifactId>
          <version>${selenium.version}</version>  <!-- ### Delete locations ### -->
          <scope>test</scope>
      </dependency>
   <!-- ### Delete locations Start ### -->
      <dependency>
          <groupId>org.seleniumhq.selenium</groupId>
          <artifactId>selenium-chrome-driver</artifactId>
          <version>${selenium.version}</version>
          <scope>test</scope>
      </dependency>
      <dependency>
          <groupId>org.seleniumhq.selenium</groupId>
          <artifactId>selenium-remote-driver</artifactId>
          <version>${selenium.version}</version>
          <scope>test</scope>
      </dependency>
      <dependency>
          <groupId>org.seleniumhq.selenium</groupId>
          <artifactId>selenium-api</artifactId>
          <version>${selenium.version}</version>
          <scope>test</scope>
      </dependency>
      <dependency>
          <groupId>org.seleniumhq.selenium</groupId>
          <artifactId>selenium-firefox-driver</artifactId>
          <version>${selenium.version}</version>
          <scope>test</scope>
      </dependency>
      <dependency>
          <groupId>org.seleniumhq.selenium</groupId>
          <artifactId>selenium-ie-driver</artifactId>
          <version>${selenium.version}</version>
          <scope>test</scope>
      </dependency>
      <dependency>
          <groupId>org.seleniumhq.selenium</groupId>
          <artifactId>selenium-safari-driver</artifactId>
          <version>${selenium.version}</version>
          <scope>test</scope>
      </dependency>
      <dependency>
          <groupId>org.seleniumhq.selenium</groupId>
          <artifactId>selenium-support</artifactId>
          <version>${selenium.version}</version>
          <scope>test</scope>
      </dependency>
   <!-- ### Delete locations End ### -->
   <!--omitted-->

   </dependencies>
</dependencyManagement>
<properties>
   <!--omitted-->
   <selenium.version>2.46.0</selenium.version> <!-- ### Delete locations ### -->
   <!--omitted-->
</properties>

[Remarks]

When setting your own version of Selenium, define the above-mentioned deletion target in pom.xmland specify the version to be used in selenium.version.

The definition having only selenium-javais insufficient and it is necessary to have all versions of Selenium library such as selenium-remote-driver.

The definition of version since Warning indicating version of maven-surefire-plugin not defined occurs at the time of build of blank project.

Version is specified in order to match with common library definition (2.17).

[Case where procedure is required]

Perform the following modifications if it matches with the following cases.

• Version of maven-surefire-plugin is not defined uniquely and Warning is displayed at the time of build.

[How to modify]

Add the following definition in pom.xmlof project.

<build>
   <pluginManagement>
       <plugins>
           <!--omitted-->
           <plugin>
               <groupId>org.apache.maven.plugins</groupId>
               <artifactId>maven-surefire-plugin</artifactId>
               <version>${maven-surefire-plugin.version}</version>
           </plugin>
           <!--omitted-->
       </plugins>
   </pluginManagement>
</build>
<properties>
   <!--omitted-->
   <maven-surefire-plugin.version>2.17</maven-surefire-plugin.version>
   <!--omitted-->
</properties>

If the version used actually at the time of build is other than 2.17, it can be specified.

The implementation example of Path variable reference in authorization control (<sec:intercept-url>) by Spring Security is modified.

This modification was done because the contents mentioned in the Warning of specification of Web resource that applies access policy were not included in the implementation example.

In the earlier implementation example, if extension is included in the URL, it is considered as a part of the path variable and unintended authorization control is performed. Also, it is not considered that if the URL ends with extension or /, it will be interpreted differently in Spring MVC and Spring Security.

[Case where procedure is required]

Perform the following modifications if it matches with the following cases.

• Authorization control(<sec:intercept-url>) is implemented by Spring Security and path variables are used in path pattern (pattern).

[How to modify]

• Change the definition of access policy of spring-security.xml.

Example）

【Before modification】

<sec:http>
   <sec:intercept-url pattern="/users/{userName}" access="isAuthenticated() and #userName == principal.username"/>
   <!-- omitted -->
</sec:http>

【After modification】

[When wild cards are to be used]

<sec:http>
   <sec:intercept-url pattern="/users/{userName}.*"  access="isAuthenticated() and #userName == principal.username"/>
   <sec:intercept-url pattern="/users/{userName}/**" access="isAuthenticated() and #userName == principal.username"/>
   <!-- omitted -->
</sec:http>

[When wild cards are not to be used]

<sec:http>
   <sec:intercept-url pattern="/users/{userName}.*"  access="isAuthenticated() and #userName == principal.username"/>
   <sec:intercept-url pattern="/users/{userName}/"   access="isAuthenticated() and #userName == principal.username"/>
   <sec:intercept-url pattern="/users/{userName}"    access="isAuthenticated() and #userName == principal.username"/>
   <!-- omitted -->
</sec:http>

It is confirmed that when using @Injectin SOAP Web Service implementation, it does not work properly on a specific AP server. This is because the processing on SOAP server has the characteristics to operate on the servlet provided by JAX-WS engine and not on the servlet provided by Spring, and it impacts CDI function of each AP server (AP server of Java EE support) of execution environment if it is implemented to inject Bean of Spring management using @Inject.

[Case where procedure is required]

It may have the above-mentioned impact when DI function of AP server is not disabled. Perform the following modification whenever required.

[How to modify]

In the implementation of SOAP server, replace all the locations where @Injectis used, with @Autowired.

The default settings of timeout are changed in the implementation of client of SOAP Web Service.

Before change, Integertype was specified in value-typeattribute, however, when not specified, Stringtype is applied and specification of value-typeattribute is deleted, since it works normally with both Integerand String except for some servers.

[Case where procedure is required]

This procedure is optional. If it matches with the following cases and if required, perform the following modification.

• The used AP server is not weblogic.（※）

For （※） weblogic, the handling method differs. Refer to timeout settings of SOAP client.

[How to modify]

Modify custom property of org.springframework.remoting.jaxws.JaxWsPortProxyFactoryBean.

• ($YOUR_PROJECT_ROOT/[projectName]-domain/src/main/resources/META-INF/spring/[projectName]-domain.xml)

【Before modification】

<property name="customProperties">
    <map>
        <entry key="com.sun.xml.internal.ws.connect.timeout" value-type="java.lang.Integer"  value="${webservice.connect.timeout}"/>
        <entry key="com.sun.xml.internal.ws.request.timeout" value-type="java.lang.Integer"  value="${webservice.request.timeout}"/>
    </map>
</property>

【After modification】

<property name="customProperties">
    <map>
        <entry key="com.sun.xml.internal.ws.connect.timeout" value="${webservice.connect.timeout}"/>
        <entry key="com.sun.xml.internal.ws.request.timeout" value="${webservice.request.timeout}"/>
    </map>
</property>

org.springframework.http.client.support.BasicAuthorizationInterceptor is added from Spring Framework 4.1 and it will no longer be required to implement request header setting process for Basic authorization independently.

[Case where procedure is required]

It is recommended to apply the following modification to implement request header setting process for Basic authorization independently.

[How to modify]

Delete request header setting process 9（BasicAuthInterceptor）) for Basic authorization implemented independently and modify applicationContext.xmlas shown below.

【Before modification】

<bean id="basicAuthInterceptor" class="com.example.restclient.BasicAuthInterceptor" />

【After modification】

<bean id="basicAuthInterceptor" class="org.springframework.http.client.support.BasicAuthorizationInterceptor">
    <constructor-arg index="0" value="${api.auth.username}" /><!-- Set username -->
    <constructor-arg index="1" value="${api.auth.password}" /><!-- Set password -->
</bean>

In MyBatis 3.4 and MyBatis-Spring 1.3 combination, timeoutattribute of @Transactional annotation is enabled.

[Case where procedure is required]

This procedure is optional, however, if it matches with any of the following cases, it is recommended to apply the following modifications.

• Information required for transaction management is declared in XML (bean definition).
• As a measure for non functioning of timeoutattribute, timeout is specified for each statement in MyBatis mapper XML.

[How to modify：When information required for transaction management is declared in XML (bean definition)]

Delete XML (Bean definition) and specify @Transactionalfor the class or class method intended for transaction management.

Example）

【Before modification】

<bean id="fooService" class="x.y.service.DefaultFooService"/>

<tx:advice id="txAdvice" transaction-manager="transactionManager">
    <tx:attributes>
        <tx:method name="*" timeout="10"/>
    </tx:attributes>
</tx:advice>

<aop:config>
    <aop:pointcut id="fooServiceOperation" expression="execution(* x.y.service.FooService.*(..))"/>
    <aop:advisor advice-ref="txAdvice" pointcut-ref="fooServiceOperation"/>
</aop:config>

<bean id="transactionManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
    <property name="dataSource" ref="dataSource"/>
</bean>

【After modification】

<bean id="fooService" class="x.y.service.DefaultFooService"/>

<tx:annotation-driven />

<bean id="transactionManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
    <property name="dataSource" ref="dataSource"/>
</bean>

@Transactional(timeout = "10")
public class DefaultFooService implements FooService {

   //omitted

}

Refer to About transaction management of development guidelines for the details.

[How to modify：When timeout is specified for each statement in MyBatis mapper XML]

Delete timeoutattribute from the statement in mapper XML and specify timeoutattribute for @Transactional.

Implementation example of error handling has been added in Implementation example of OAuth of development guidelines. In the implementation example of the development guidelines before addition, error handling is inadequate and hence it is necessary to make modifications.

[Case where procedure is required]

Perform the following modifications if it matches with any of the following cases.

• Implement based on the development guidelines, and do not add own error handling.
• Implement based on the development guidelines, and not add own error handling but it differs with the implementation policy of 5.4.1 version development guidelines.

[How to modify]

Check implementation example of OAuth error handling and carry out the implementation.

Implementation example of cancel access token at client has been added in Implementation example of OAuth of development guidelines.

[Case where procedure is required]

Implement as follows if it matches with the following case.

• Cancellation of access token is being implemented in authorization server.

[How to implement]

Check implementation example of Cancel token (Client server) and carry out the implementation.

In Spring Security 4.1.0, a bug wherein HTTP response header was not output correctly occurred due to the following Issues.

spring-project/spring-security#2953

In the following Issues, the above-mentioned bugs have been fixed and will no longer occur from Spring Security 4.2.0 onwards.

spring-project/spring-security#3975

[Case where procedure is required]

Confirm whether there is any impact due to the normal output of the Cache-Control header, if there is any impact, take appropriate measures according to Linkage with the security measure function of browser of the development guideline.

[How to modify]

Delete the implementation that was performed as a measure.

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

Note

Notes

[Table header]

Non : Blank project 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.4.1.RELEASE.

If Eclipse is running, close Eclipse.

Update (delete and add) the jar file 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 (delete and add) the jar file 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 (delete and add) the jar file for source storage 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}|

Update the reference library by using the replacement character string.

• $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}|