Nablarch 5 to 6 Migration Guide¶

Change Java EE dependency to Jakarta EE¶

Java EE API dependencies (dependency) must be changed to those of Jakarta EE. For example, a typical example is Java Servlet.

The dependency of Java EE API is different and not unified depending on the jar provider and version. Therefore, it cannot be determined mechanically from groupId. Which dependency is a Java EE API must be determined from groupId, artifactId, classes included in the jar, and so on.

For your reference, archetypes and examples provided by Nablarch changes listed below.

In addition, in example applications, by reading the BOM provided by Jakarta EE, it is possible to avoid specifying the version individually. It is recommended to read BOM because it reduces the trouble of checking the version and mistakes in specification, and makes management easier.

<dependencyManagement>
  <dependencies>
    ...
    <dependency>
      <groupId>jakarta.platform</groupId>
      <artifactId>jakarta.jakartaee-bom</artifactId>
      <version>10.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Additionally, Correspondence table between Java EE and Jakarta EE specifications is listed as an appendix at the end of this page as a reference for changing dependencies that are not listed in the modification examples. What is dependency in Jakarta EE is described on each specification page, so please check it (for example, Jakarta Servlet 6.0 specification page (external site) shows jakarta.servlet:jakarta.servlet-api:jar:6.0.0 in “Maven coordinates”).

<dependency>
  <groupId>javax.servlet</groupId>
  <artifactId>javax.servlet-api</artifactId>
  <version>...</version>
  <scope>provided</scope>
</dependency>

<dependency>
  <groupId>jakarta.servlet</groupId>
  <artifactId>jakarta.servlet-api</artifactId>
  <scope>provided</scope>
</dependency>

<dependency>
  <groupId>javax.servlet.jsp</groupId>
  <artifactId>javax.servlet.jsp-api</artifactId>
  <version>...</version>
  <scope>provided</scope>
</dependency>

<dependency>
  <groupId>jakarta.servlet.jsp</groupId>
  <artifactId>jakarta.servlet.jsp-api</artifactId>
  <scope>provided</scope>
</dependency>

<dependency>
  <groupId>javax.servlet.jsp.jstl</groupId>
  <artifactId>javax.servlet.jsp.jstl-api</artifactId>
  <version>...</version>
</dependency>

<dependency>
  <groupId>jakarta.servlet.jsp.jstl</groupId>
  <artifactId>jakarta.servlet.jsp.jstl-api</artifactId>
</dependency>

<dependency>
  <groupId>org.apache.geronimo.specs</groupId>
  <artifactId>geronimo-jpa_2.0_spec</artifactId>
  <version>...</version>
</dependency>

<dependency>
  <groupId>jakarta.persistence</groupId>
  <artifactId>jakarta.persistence-api</artifactId>
</dependency>

<dependency>
  <groupId>javax.ws.rs</groupId>
  <artifactId>javax.ws.rs-api</artifactId>
  <version>...</version>
</dependency>

<dependency>
  <groupId>jakarta.ws.rs</groupId>
  <artifactId>jakarta.ws.rs-api</artifactId>
</dependency>

<dependency>
  <groupId>javax.annotation</groupId>
  <artifactId>javax.annotation-api</artifactId>
  <version>...</version>
</dependency>

<dependency>
  <groupId>jakarta.annotation</groupId>
  <artifactId>jakarta.annotation-api</artifactId>
</dependency>

Update Java EE specification implementation library¶

If you have embedded Java EE specification implementation library in your application, replace them with those from Jakarta EE.

To find out which dependency is Java EE specification implementation library, you need to investigate each dependency individually. Also, if it is found to be a Java EE specification implementation library, what the dependency of the Jakarta EE compliant version of that implementation library will be depends on the implementation library. Therefore, it is necessary to check the official site etc. for each implementation library used in the project.

For your reference, archetypes and examples provided by Nablarch changes listed below.

Compatible implementations are also introduced on each Jakarta EE specification page, so please refer to those as well. (For example, the Jakarta RESTful Web Services 3.1 specification page (external site) lists Eclipse Jersey as a compatible implementation. 3.1.0 is introduced)

<dependency>
  <groupId>org.hibernate</groupId>
  <artifactId>hibernate-validator</artifactId>
  <version>5.3.6.Final</version>
</dependency>

<dependency>
  <groupId>org.hibernate.validator</groupId>
  <artifactId>hibernate-validator</artifactId>
  <version>8.0.0.Final</version>
</dependency>

<dependency>
  <groupId>taglibs</groupId>
  <artifactId>standard</artifactId>
  <version>...</version>
</dependency>

<dependency>
  <groupId>org.glassfish.web</groupId>
  <artifactId>jakarta.servlet.jsp.jstl</artifactId>
  <version>3.0.0</version>
</dependency>

<dependencyManagement>
  <dependencies>
    ...
    <dependency>
      <groupId>org.glassfish.jersey</groupId>
      <artifactId>jersey-bom</artifactId>
      <version>...</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependency>
  <groupId>org.glassfish.jersey.media</groupId>
  <artifactId>jersey-media-json-jackson</artifactId>
</dependency>

<dependency>
  <groupId>org.glassfish.jersey.core</groupId>
  <artifactId>jersey-client</artifactId>
</dependency>

<dependency>
  <groupId>org.glassfish.jersey.inject</groupId>
  <artifactId>jersey-hk2</artifactId>
</dependency>

<dependencyManagement>
  <dependencies>
    ...
    <dependency>
      <groupId>org.glassfish.jersey</groupId>
      <artifactId>jersey-bom</artifactId>
      <version>3.1.8</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependency>
  <groupId>org.glassfish.jersey.media</groupId>
  <artifactId>jersey-media-json-jackson</artifactId>
</dependency>

<dependency>
  <groupId>org.glassfish.jersey.core</groupId>
  <artifactId>jersey-client</artifactId>
</dependency>

<dependency>
  <groupId>org.glassfish.jersey.inject</groupId>
  <artifactId>jersey-hk2</artifactId>
</dependency>

<dependency>
  <groupId>org.apache.activemq</groupId>
  <artifactId>activemq-all</artifactId>
  <version>...</version>
</dependency>

<dependency>
  <groupId>org.apache.activemq</groupId>
  <artifactId>artemis-server</artifactId>
  <version>2.37.0</version>
</dependency>
<dependency>
  <groupId>org.apache.activemq</groupId>
  <artifactId>artemis-jakarta-server</artifactId>
  <version>2.37.0</version>
</dependency>
<dependency>
  <groupId>org.apache.activemq</groupId>
  <artifactId>artemis-jakarta-client</artifactId>
  <version>2.37.0</version>
</dependency>

Update gsp-dba-maven-plugin¶

gsp-dba-maven-plugin (external site) is preinstalled in nablarch-example-web and other projects built from archetypes. This plugin provides a function (generate-entity) to generate Java entity classes from database table metadata. Since Java EE annotations such as JPA are set in this entity class, it cannot be used as is in the Jakarta EE environment.

Since gsp-dba-maven-plugin is compatible with Jakarta EE in 5.0.0, change <version> of gsp-dba-maven-plugin in pom.xml.

<plugin>
  <groupId>jp.co.tis.gsp</groupId>
  <artifactId>gsp-dba-maven-plugin</artifactId>
  <version>5.1.0</version>
  <configuration>
  ...

Furthermore, in order to use the generate-entity of the gsp-dba-maven-plugin that supports Jakarta EE, it is necessary to add dependency and JVM arguments. See the gsp-dba-maven-plugin guide (external site) for details.

As described above, an entity for which Jakarta EE annotations are set will be generated.

Change waitt-maven-plugin to jetty-ee10-maven-plugin¶

The waitt-maven-plugin (external site) is preinstalled in nablarch-example-web and other web application projects built from archetypes. This plugin provides the ability to easily deploy and run your project’s code on an embedded server (such as Tomcat). However, this plugin is not compatible with Jakarta EE, so change it to jetty-ee10-maven-plugin which provides similar functionality and also supports Jakarta EE.

Before modification, waitt-maven-plugin is set in pom.xml in nablarch-example-web as follows.

Before modification

<plugin>
  <groupId>net.unit8.waitt</groupId>
  <artifactId>waitt-maven-plugin</artifactId>
  <version>1.2.3</version>
  <configuration>
    <servers>
      <server>
        <groupId>net.unit8.waitt.server</groupId>
        <artifactId>waitt-tomcat8</artifactId>
        <version>1.2.3</version>
      </server>
    </servers>
  </configuration>
</plugin>

Change this to jetty-ee10-maven-plugin as follows.

After modification

<plugin>
  <groupId>org.eclipse.jetty.ee10</groupId>
  <artifactId>jetty-ee10-maven-plugin</artifactId>
  <version>12.0.12</version>
</plugin>

Now you can deploy and run your application code on Jetty.

If you want to actually run it, you can start Jetty with the following command.

mvn jetty:run

Change nablarch-testing-jetty6 to nablarch-testing-jetty12¶

If your web application project uses NTF (Nablarch Testing Framework), use the module nablarch-testing-jetty6 to run the embedded server in your JUnit tests. Jetty 6 launched with this module does not support Jakarta EE. Jetty supports Jakarta EE 10 with Jetty 12, so you need to change it to use nablarch-testing-jetty12 which can start Jetty 12.

First, modify pom.xml as follows.

<dependency>
  <groupId>com.nablarch.framework</groupId>
  <artifactId>nablarch-testing-jetty12</artifactId> <!-- Change the artifactId to nablarch-testing-jetty12 -->
  <scope>test</scope>
</dependency>

Next, modify the part that defines the components of HttpServerFactory as follows.

Before modification

<component name="httpServerFactory" class="nablarch.fw.web.httpserver.HttpServerFactoryJetty6"/>

After modification

<component name="httpServerFactory" class="nablarch.fw.web.httpserver.HttpServerFactoryJetty12"/>

In case of nablarch-example-web, the above settings exist in src/test/resources/unit-test.xml.

With the above, the embedded server that is started when NTF is executed is switched to the version that supports Jakarta EE.

Change javax namespace to jakarta namespace¶

The namespace changes that came with Jakarta EE 9 will also be applied to the application code. The general flow of handling namespace changes is described below.

1. Code that is import in javax namespace causes a compilation error, so change to jakarta namespace. 1. Grep the whole project with javax and find out where there are no compilation errors. 2. Judge whether the location found in the search is a Java EE namespace 3. If it is a Java EE namespace, replace javax with jakarta

Details are described below.

javax descriptions often appear in import statements in Java source code. With the modifications made so far, Java EE dependencies have been removed and replaced with Jakarta EE dependencies, so import in the javax namespace causes compilation errors. Therefore, first check where the compilation error occurs and change to jakarta namespace.

However, javax appears not only in import statements, but also in places where compilation errors do not occur. For example, the key javax.servlet.forward.request_uri for obtaining the request URI before forwarding in Java Servlet is specified as a character string, so a compilation error does not occur (This key should be changed to jakarta.servlet.forward.request_uri for Jakarta Servlet). In addition, even if it is described in JSP or configuration file, it will not be a compilation error, but it will be subject to correction.

Therefore, to check for the presence of the javax namespace, you must do a Grep search of the entire project.

Next, for the location hit by javax, determine whether it is really a Java EE namespace. For example, if you search nablarch-example-web with javax, the following description will be hit.

import javax.validation.ConstraintValidator;

This is where the Bean Validation class is import, so it can be judged as a Java EE namespace.

On the other hand, the following description also hits.

import javax.crypto.SecretKeyFactory;

This is not a Java EE namespace because it imports the classes related to cryptographic processing included in the standard library.

In this way, even if javax is hit, you cannot simply judge that they are all Java EE namespaces. Namespaces for each specification are listed in the appendix Correspondence table between Java EE and Jakarta EE specifications on this page, so refer to this to determine if the hit javax is Java EE.

If it can be determined that it is a Java EE namespace, replace javax with jakarta. Below is an example of replacing import with jakarta.

import jakarta.validation.ConstraintValidator;

With the above modifications, nablarch-example-web can now run on an application server that supports Jakarta EE 10.

Change XML schema specification to Jakarta EE 10 schema¶

XML files such as web.xml specify an XML schema, but change this to a schema compatible with Jakarta EE 10. Schemas provided in Jakarta EE 10 can be found at Jakarta EE XML Schemas (external site) .

Before modification

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">

After modification

<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
                             web-app_6_0.xsd"
         version="6.0">

Change tag library namespace to Jakarta EE 10 namespace¶

In the JSP file, the tag library namespace is specified using the taglib directive, but change this to a namespace compatible with Jakarta EE 10. You can check the namespaces provided in Jakarta EE 10 at Jakarta Standard Tag Library 3.0 (external site) .

Before modification

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

After modification

<%@ taglib prefix="c" uri="jakarta.tags.core" %>

When NoClassDefFoundError occurs¶

org.jboss.weld.exceptions.WeldException
    at org.jboss.weld.executor.AbstractExecutorServices.checkForExceptions (AbstractExecutorServices.java:82)
    ...
Caused by: java.lang.NoClassDefFoundError
    at jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance0 (Native Method)
    ...
Caused by: java.lang.NoClassDefFoundError:Could not initialize class org.jboss.weld.logging.BeanLogger
    at org.jboss.weld.util.Beans.getBeanConstructor (Beans.java:279)

If a stack trace like the one above is output during execution and an error occurs, you can resolve the error by placing slf4j-nablarch-adaptor after Logback in the classpath order. When running with Maven, you can change the classpath order by placing slf4j-nablarch-adaptor in pom.xml below Logback.

<dependency>
  <groupId>ch.qos.logback</groupId>
  <artifactId>logback-classic</artifactId>
  <version>...</version>
</dependency>

<!-- Place slf4j-nablarch-adaptor below Logback -->
<dependency>
  <groupId>com.nablarch.integration</groupId>
  <artifactId>slf4j-nablarch-adaptor</artifactId>
  <scope>runtime</scope>
</dependency>