Migration Guide 1.0.1 - terasolunaorg/terasoluna-gfw GitHub Wiki

Migrating from 1.0.0 to 1.0.1

Overview of migration procedure

Migration procedure is as follows.

Step Procedure MavenMultiple Projects MavenSingle Project EclipseWTP Project
1 Update libraries Required Required Required
2 Apply the changes in specification of <t:messagesPanel> Required by case Required by case Required by case
3 Apply the changes in specification of <t:pagination> Required by case Required by case Required by case
4 Change the message code in dataAccessError.jsp Optional - -
5 Change the message code in businessError.jsp Optional - -
6 Change the order of import of bean files in xxx-domain.xml Optional - -
7 Add exception mappings into ExceptionCodeResolver Optional Optional Optional
8 Add messages of type mismatch - Optional Optional
9 Add <context:property-placeholder> in spring-mvc.xml - Optional Optional
10 Add dozer.properties - Optional Optional
11 Change URL of Maven repositories Optional Optional Optional
  • Required : This procedure is mandatory.
  • Required by case : This procedure is mandatory, if conditions match.
  • Optional : This procedure is recommended. Perform it if you feel the need.
  • - : This procedure is not required.

[Step1] Update libraries

Please update Common Libraries and Dependency Libraries.

  • Update Common Library version
Library Name From version To version
TERASOLUNA Global Framework 1.0.0.RELEASE 1.0.1.RELEASE
  • Update Dependency Library version
Library Name From version To version
Spring Framework 3.2.4.RELEASE 3.2.10.RELEASE
Spring Data Commons 1.6.1.RELEASE 1.6.4.RELEASE
Spring Data JPA 1.4.1.RELEASE 1.4.3.RELEASE
AspectJ 1.7.3 1.7.4
  • Delete Dependency Library
Library Name From version To version
Java Transaction API 1.1 This library had duplicated with jboss-transaction-api_1.1_spec-1.0.1.Final.jar.

Using Maven Multiple Projects

This update procedure is for the projects which are generated by using mvn archetype.

Update pom file in your parent project. ($YOUR_MULTIPLE_PROJECT_ROOT/pom.xml)

<parent>
    <groupId>org.terasoluna.gfw</groupId>
    <artifactId>terasoluna-gfw-parent</artifactId>
    <version>1.0.1.RELEASE</version> <!-- ### Need to edit ### -->
</parent>

Using Maven Single Project

This update procedure is for projects that are generated by using mvn archetype or downloaded from the release site.

Update pom file in your project. ($YOUR_SINGLE_PROJECT/pom.xml)

<parent>
    <groupId>org.terasoluna.gfw</groupId>
    <artifactId>terasoluna-gfw-parent</artifactId>
    <version>1.0.1.RELEASE</version> <!-- ### Need to edit ### -->
</parent>

Using Eclipse WTP Project

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

  1. Download the Eclipse WTP Project of 1.0.1.RELEASE.

  2. If Eclipse is running, please stop the Eclipse.

  3. Update(delete and add) jar files in $YOUR_ECLIPSE_WTP_PROJECT/src/main/webapp/WEB-INF/lib. ( * : target file for operation)

    Library Name

    Delete File

    Add File

    For none data access

    For JPA

    For Mybatis2

    TERASOLUNA Global Framework

    terasoluna-gfw-common-1.0.0.RELEASE.jar

    terasoluna-gfw-common-1.0.1.RELEASE.jar

    *

    *

    *
     

    terasoluna-gfw-web-1.0.0.RELEASE.jar

    terasoluna-gfw-web-1.0.1.RELEASE.jar

    *

    *

    *
     

    terasoluna-gfw-security-core-1.0.0.RELEASE.jar

    terasoluna-gfw-security-core-1.0.1.RELEASE.jar

    *

    *

    *
     

    terasoluna-gfw-security-web-1.0.0.RELEASE.jar

    terasoluna-gfw-security-web-1.0.1.RELEASE.jar

    *

    *

    *
     

    terasoluna-gfw-jpa-1.0.0.RELEASE.jar

    terasoluna-gfw-jpa-1.0.1.RELEASE.jar

    		  

    *

    		  
     

    terasoluna-gfw-mybatis2-1.0.0.RELEASE.jar

    terasoluna-gfw-mybatis2-1.0.1.RELEASE.jar

    		    

    *

    Spring Framework

    spring-aop-3.2.4.RELEASE.jar

    spring-aop-3.2.10.RELEASE.jar

    *

    *

    *
     

    spring-aspects-3.2.4.RELEASE.jar

    spring-aspects-3.2.10.RELEASE.jar

    *

    *

    *
     

    spring-beans-3.2.4.RELEASE.jar

    spring-beans-3.2.10.RELEASE.jar

    *

    *

    *
     

    spring-context-3.2.4.RELEASE.jar

    spring-context-3.2.10.RELEASE.jar

    *

    *

    *
     

    spring-context-support-3.2.4.RELEASE.jar

    spring-context-support-3.2.10.RELEASE.jar

    *

    *

    *
     

    spring-core-3.2.4.RELEASE.jar

    spring-core-3.2.10.RELEASE.jar

    *

    *

    *
     

    spring-expression-3.2.4.RELEASE.jar

    spring-expression-3.2.10.RELEASE.jar

    *

    *

    *
     

    spring-jdbc-3.2.4.RELEASE.jar

    spring-jdbc-3.2.10.RELEASE.jar

    *

    *

    *
     

    spring-orm-3.2.4.RELEASE.jar

    spring-orm-3.2.10.RELEASE.jar

    *

    *

    *
     

    spring-tx-3.2.4.RELEASE.jar

    spring-tx-3.2.10.RELEASE.jar

    *

    *

    *
     

    spring-web-3.2.4.RELEASE.jar

    spring-web-3.2.10.RELEASE.jar

    *

    *

    *
     

    spring-webmvc-3.2.4.RELEASE.jar

    spring-webmvc-3.2.10.RELEASE.jar

    *

    *

    *

    Spring Data Commons

    spring-data-commons-1.6.1.RELEASE.jar

    spring-data-commons-1.6.4.RELEASE.jar

    *

    *

    *

    Spring Data JPA

    spring-data-jpa-1.4.1.RELEASE.jar

    spring-data-jpa-1.4.3.RELEASE.jar

    		  

    *

    		  

    AspectJ

    aspectjrt-1.7.3.jar

    aspectjrt-1.7.4.jar

    *

    *

    *
     

    aspectjweaver-1.7.3.jar

    aspectjweaver-1.7.4.jar

    *

    *

    *

    Java Transaction API

    jta-1.1.jar

    -

    		  

    *

    		  

  4. Update(delete and add) source jar files in $YOUR_ECLIPSE_WTP_PROJECT/src/main/webapp/WEB-INF/libsrc. ( * : target file for operation)

    Library Name

    Delete File

    Add File

    For none data access

    For JPA

    For Mybatis2

    TERASOLUNA Global Framework

    terasoluna-gfw-common-1.0.0.RELEASE-sources.jar

    terasoluna-gfw-common-1.0.1.RELEASE-sources.jar

    *

    *

    *
     

    terasoluna-gfw-web-1.0.0.RELEASE-sources.jar

    terasoluna-gfw-web-1.0.1.RELEASE-sources.jar

    *

    *

    *
     

    terasoluna-gfw-security-core-1.0.0.RELEASE-sources.jar

    terasoluna-gfw-security-core-1.0.1.RELEASE-sources.jar

    *

    *

    *
     

    terasoluna-gfw-security-web-1.0.0.RELEASE-sources.jar

    terasoluna-gfw-security-web-1.0.1.RELEASE-sources.jar

    *

    *

    *
     

    terasoluna-gfw-jpa-1.0.0.RELEASE-sources.jar

    terasoluna-gfw-jpa-1.0.1.RELEASE-sources.jar

    		  

    *

    		  
     

    terasoluna-gfw-mybatis2-1.0.0.RELEASE-sources.jar

    terasoluna-gfw-mybatis2-1.0.1.RELEASE-sources.jar

    		    

    *

    Spring Framework

    spring-aop-3.2.4.RELEASE-sources.jar

    spring-aop-3.2.10.RELEASE-sources.jar

    *

    *

    *
     

    spring-aspects-3.2.4.RELEASE-sources.jar

    spring-aspects-3.2.10.RELEASE-sources.jar

    *

    *

    *
     

    spring-beans-3.2.4.RELEASE-sources.jar

    spring-beans-3.2.10.RELEASE-sources.jar

    *

    *

    *
     

    spring-context-3.2.4.RELEASE-sources.jar

    spring-context-3.2.10.RELEASE-sources.jar

    *

    *

    *
     

    spring-context-support-3.2.4.RELEASE-sources.jar

    spring-context-support-3.2.10.RELEASE-sources.jar

    *

    *

    *
     

    spring-core-3.2.4.RELEASE-sources.jar

    spring-core-3.2.10.RELEASE-sources.jar

    *

    *

    *
     

    spring-expression-3.2.4.RELEASE-sources.jar

    spring-expression-3.2.10.RELEASE-sources.jar

    *

    *

    *
     

    spring-jdbc-3.2.4.RELEASE-sources.jar

    spring-jdbc-3.2.10.RELEASE-sources.jar

    *

    *

    *
     

    spring-orm-3.2.4.RELEASE-sources.jar

    spring-orm-3.2.10.RELEASE-sources.jar

    *

    *

    *
     

    spring-tx-3.2.4.RELEASE-sources.jar

    spring-tx-3.2.10.RELEASE-sources.jar

    *

    *

    *
     

    spring-web-3.2.4.RELEASE-sources.jar

    spring-web-3.2.10.RELEASE-sources.jar

    *

    *

    *
     

    spring-webmvc-3.2.4.RELEASE-sources.jar

    spring-webmvc-3.2.10.RELEASE-sources.jar

    *

    *

    *

    Spring Data Commons

    spring-data-commons-1.6.1.RELEASE-sources.jar

    spring-data-commons-1.6.4.RELEASE-sources.jar

    *

    *

    *

    Spring Data JPA

    spring-data-jpa-1.4.1.RELEASE-sources.jar

    spring-data-jpa-1.4.3.RELEASE-sources.jar

    		  

    *

    		  

    AspectJ

    aspectjrt-1.7.3-sources.jar

    aspectjrt-1.7.4-sources.jar

    *

    *

    *
     

    aspectjweaver-1.7.3-sources.jar

    aspectjweaver-1.7.4-sources.jar

    *

    *

    *

    Java Transaction API

    jta-1.1-sources.jar

    -

    		  

    *

    		  

  5. Update the referenced libraries in all of the following files, using replace string. ( * : target for operation)

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

    Library Name

    Delete File

    Add File

    For none data access

    For JPA

    For Mybatis2

    TERASOLUNA Global Framework

    terasoluna-gfw-common-1.0.0.RELEASE

    terasoluna-gfw-common-1.0.1.RELEASE

    *

    *

    *
     

    terasoluna-gfw-web-1.0.0.RELEASE

    terasoluna-gfw-web-1.0.1.RELEASE

    *

    *

    *
     

    terasoluna-gfw-security-core-1.0.0.RELEASE

    terasoluna-gfw-security-core-1.0.1.RELEASE

    *

    *

    *
     

    terasoluna-gfw-security-web-1.0.0.RELEASE

    terasoluna-gfw-security-web-1.0.1.RELEASE

    *

    *

    *
     

    terasoluna-gfw-jpa-1.0.0.RELEASE

    terasoluna-gfw-jpa-1.0.1.RELEASE

    		  

    *

    		  
     

    terasoluna-gfw-mybatis2-1.0.0.RELEASE

    terasoluna-gfw-mybatis2-1.0.1.RELEASE

    		    

    *

    Spring Framework

    spring-aop-3.2.4.RELEASE

    spring-aop-3.2.10.RELEASE

    *

    *

    *
     

    spring-aspects-3.2.4.RELEASE

    spring-aspects-3.2.10.RELEASE

    *

    *

    *
     

    spring-beans-3.2.4.RELEASE

    spring-beans-3.2.10.RELEASE

    *

    *

    *
     

    spring-context-3.2.4.RELEASE

    spring-context-3.2.10.RELEASE

    *

    *

    *
     

    spring-context-support-3.2.4.RELEASE

    spring-context-support-3.2.10.RELEASE

    *

    *

    *
     

    spring-core-3.2.4.RELEASE

    spring-core-3.2.10.RELEASE

    *

    *

    *
     

    spring-expression-3.2.4.RELEASE

    spring-expression-3.2.10.RELEASE

    *

    *

    *
     

    spring-jdbc-3.2.4.RELEASE

    spring-jdbc-3.2.10.RELEASE

    *

    *

    *
     

    spring-orm-3.2.4.RELEASE

    spring-orm-3.2.10.RELEASE

    *

    *

    *
     

    spring-tx-3.2.4.RELEASE

    spring-tx-3.2.10.RELEASE

    *

    *

    *
     

    spring-web-3.2.4.RELEASE

    spring-web-3.2.10.RELEASE

    *

    *

    *
     

    spring-webmvc-3.2.4.RELEASE

    spring-webmvc-3.2.10.RELEASE

    *

    *

    *

    Spring Data Commons

    spring-data-commons-1.6.1.RELEASE

    spring-data-commons-1.6.4.RELEASE

    *

    *

    *

    Spring Data JPA

    spring-data-jpa-1.4.1.RELEASE

    spring-data-jpa-1.4.3.RELEASE

    		  

    *

    		  

    AspectJ

    aspectjrt-1.7.3

    aspectjrt-1.7.4

    *

    *

    *
     

    aspectjweaver-1.7.3

    aspectjweaver-1.7.4

    *

    *

    *

    Java Transaction API

    jta-1.1

    -

    		  

    *

    		  

  6. Delete referenced libraries from the settings of Eclipse WTP project. ($YOUR_ECLIPSE_WTP_PROJECT/.classpath)

    Delete jta-1.1.jar from the build classpath setting.

    <!-- omitted -->
<classpathentry kind="lib"
    path="src/main/webapp/WEB-INF/lib/jta-1.1.jar"
    sourcepath="libsrc/jta-1.1-sources.jar" /> <!-- ### Need to delete this classpath entry ### -->
<!-- omitted -->

  7. Delete the dependency libraries from Ant build file. ($YOUR_ECLIPSE_WTP_PROJECT/build.xml)

    Delete jta-1.1.jar from build classpath entry.

    <path id="build.classpath">
 <!-- omitted -->
 <pathelement location="${lib.dir}/jta-1.1.jar"/> <!-- ### Need to deleted this classpathentry ### -->
 <!-- omitted -->
</path>

[Step2] Apply the changes in specification of <t:messagesPanel>

We changed the specification of <t:messagesPanel> for the bug fix. Please see the here about bug information. It is possible to prevent the XSS attack on your application by this specification change.

From 1.0.1.RELEASE, messages are escaped for HTML as default behavior. Therefore, jsp files must be modified for getting the same behavior as 1.0.0.RELEASE.

Please set disableHtmlEscape attribute (new attribute) to true. If set to true, messages are not escaped for HTML. If exist a placeholder that bind user's input value, that value must be escaped for HTML in your application logic.

<t:messagesPanel disableHtmlEscape="true" />

[Step3] Apply the changes in specification of <t:pagination>

We changed the specification about the usage of <t:pagination> for the bug fix. Please see the here about bug information. With this specification change, it is possible to resolve issue that occurs due to duplicate URL encoding on the query string in your application.

Use criteriaQuery attribute (new attribute) to specify the encoded query string of search criteria. Encoded query string of search criteria can be generated using f:query(Object).

  • New style (available from 1.0.1.RELEASE onwards)

    <t:pagination page="${page}"
    criteriaQuery="${f:query(articleSearchCriteriaForm)}" />

  • Old style

    This style should not be used, because exists issue that occur duplicate URL encode on the query string.

    <t:pagination page="${page}"
    queryTmpl="page={page}&size={size}&${f:query(articleSearchCriteriaForm)}" />

[Step4] Change the message code in dataAccessError.jsp

Specified message code in dataAccessError.jsp is wrong in partial blank project of 1.0.0.RELEASE. Please see here about bug information.

If your project use wrong error code(w.xx.fw.9002) , please change to the correct message code(e.xx.fw.9002) in the following file.

  • $YOUR_MULTIPLE_PROJECT_ROOT/xxx-web/src/main/webapp/WEB-INF/views/common/error/dataAccessError.jsp.

    <!-- omitted -->
<div class="error">
    <c:if test="${!empty exceptionCode}">[${f:h(exceptionCode)}]</c:if>
    <spring:message code="e.xx.fw.9002" /> <!-- ### Need to edit ### -->
</div>
<!-- omitted -->

[Step5] Change the message code in businessError.jsp

Specified message code in businessError.jsp is wrong in partial blank project of 1.0.0.RELEASE. Please see here about bug information.

If your project use wrong error code(w.xx.fw.8001) , please change to the correct message code(e.xx.fw.8001) in the following file.

  • $YOUR_MULTIPLE_PROJECT_ROOT/xxx-web/src/main/webapp/WEB-INF/views/common/error/businessError.jsp.

    <!-- omitted -->
<c:when test="${empty exceptionCode}">
    <spring:message code="e.xx.fw.8001" /> <!-- ### Need to edit ### -->
</c:when>
<!-- omitted -->

[Step6] Change the order of importing bean files in xxx-domain.xml

For using JDBCCodeList, it should be imported in the following order; since DataSource is defined in xxx-infra.xml, while xxx-codelist.xml uses it. It does not defined in correct order in partial blank project of 1.0.0.RELEASE. Please see here about improvement information.

If it is not defined in the following order in your project, please change the order of import in $YOUR_MULTIPLE_PROJECT_ROOT/xxx-domain/src/main/resources/META-INF/spring/xxx-domain.xml.

<import resource="classpath:META-INF/spring/xxx-infra.xml" /> <!-- ### Wrong order ### -->
<import resource="classpath:META-INF/spring/xxx-codelist.xml" />

[Step7] Add exception mappings into ExceptionCodeResolver

In ExceptionCodeResolver, settings of exception mappings are not enough. Please see here about bug information.

If settings of exception mappings are not enough, please add the following exception mappings into ExceptionCodeResolver. (It defined in one of the following files).

  • $YOUR_MULTIPLE_PROJECT_ROOT/xxx-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.
<!-- omitted -->
<bean id="exceptionCodeResolver"
    class="org.terasoluna.gfw.common.exception.SimpleMappingExceptionCodeResolver">
    <!-- Setting and Customization by project. -->
    <property name="exceptionMappings">
        <map>
            <entry key="ResourceNotFoundException" value="e.xx.fw.5001" />
            <entry key="InvalidTransactionTokenException" value="e.xx.fw.7001" /> <!-- ### Need to add ### -->
            <entry key="BusinessException" value="e.xx.fw.8001" />
            <entry key=".DataAccessException" value="e.xx.fw.9002" /> <!-- ### Need to add ### -->
        </map>
    </property>
    <property name="defaultExceptionCode" value="e.xx.fw.9001" />
</bean>
<!-- omitted -->

[Step8] Add messages of type mismatch

For using a type other than String in form class or in controller's method arguments (@RequestParam,@Pathvariable,etc..), messages of type mismatch need to be defined in application-messages.properties. These are not defined in partial blank project of 1.0.0.RELEASE. Please see here about improvement information.

If these are not defined in your project, please add following default messages in one of the following files.

  • $YOUR_SINGLE_PROJECT/src/main/resources/i18n/application-messages.properties.
  • $YOUR_ECLIPSE_WTP_PROJECT/src/main/resources/i18n/application-messages.properties.
# typemismatch
typeMismatch="{0}" is invalid.
typeMismatch.int="{0}" must be an integer.
typeMismatch.double="{0}" must be a double.
typeMismatch.float="{0}" must be a float.
typeMismatch.long="{0}" must be a long.
typeMismatch.short="{0}" must be a short.
typeMismatch.boolean="{0}" must be a boolean.
typeMismatch.java.lang.Integer="{0}" must be an integer.
typeMismatch.java.lang.Double="{0}" must be a double.
typeMismatch.java.lang.Float="{0}" must be a float.
typeMismatch.java.lang.Long="{0}" must be a long.
typeMismatch.java.lang.Short="{0}" must be a short.
typeMismatch.java.lang.Boolean="{0}" is not a boolean.
typeMismatch.java.util.Date="{0}" is not a date.
typeMismatch.java.lang.Enum="{0}" is not a valid value.

[Step9] Add <context:property-placeholder> in spring-mvc.xml

For fetching property values in application layer components, <context:property-placeholder> element should be defined in spring-mvc.xml. It is not defined in partial blank project of 1.0.0.RELEASE. Please see here about bug information.

If it is not defined in your project, please add the following at the top position in one of the following files.

  • $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.
<context:property-placeholder
    location="classpath*:/META-INF/spring/*.properties" />

[Step10] Add dozer.properties

If dozer.properties does not exists under classpath, waring log will be output at the application server startup. It is not added in partial blank project of 1.0.0.RELEASE. Please see here about improvement information.

Add dozer.properties under classpath (one of the following directories).

  • YOUR_SINGLE_PROJECT/src/main/resources
  • YOUR_ECLIPSE_WTP_PROJECT/src/main/resources
$YOUR_PROJECT
  + src
      + main
          + resources
              - dozer.properties

[Step11] Change URL of Maven repositories

Change the URL of TERASOLUNA Global Framework Maven repository. Replace the ip address(54.248.227.230) to the host name(repo.terasoluna.org) in one of the following files.

  • $YOUR_MULTIPLE_PROJECT_ROOT/pom.xml
  • $YOUR_SINGLE_PROJECT/pom.xml
  • $YOUR_ECLIPSE_WTP_PROJECT/pom.xml
<repositories>
    <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> <!-- ### Need to edit ### -->
    </repository>
    <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> <!-- ### Need to edit ### -->
    </repository>
    <repository>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>terasoluna-gfw-3rdparty</id>
        <url>http://repo.terasoluna.org/nexus/content/repositories/terasoluna-gfw-3rdparty/</url> <!-- ### Need to edit ### -->
    </repository>
</repositories>
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️