Getting started with ZK-Jakarta
This guide's purpose is to provide an easy-to-setup environment to develop a ZK application using ZK 9.6 and a Jakarta-compliant run environment in Eclipse.
Please make sure that you are using the up-to-date versions of the softwares described in this example when installing yourself.
Please refer to the the eclipse and maven quick start guide environment setup.
This section details the configuration steps necessary to run your project in a servlet 5.0 context.
Maven dependencies configuration
ZK supports the Jakarta servlet configuration starting from ZK 9.6.0-jakarta. When updating your pom file, you need to include the -jakarta suffix in your dependencies version configuration:
For a more in-depth look at the pom.xml file configuration, please refer to the the Resolving ZK Framework Artifacts via Maven page .
If your project uses the servlet-API dependency, you will need to update your pom file to use the Jakarta servlet-API instead. See here for a list of available versions.
For example, you may need to replace
Jakarta in ZK add-ons and plugins
Some ZK addons and plugins do not interact with the servlet APIs and can be used interchangeably in a ZK javax or jakarta servlet. Some ZK addons do interact with the servlet APIs and require the developer to select a compatible version with their servlet container.
For example, Keikai does require using the matching version.
If used in a javax container: 5.12.2
if used in a jakarta container: 5.12.2-jakarta
Note: use latest version, 5.12.2 is the earliest Keikai release with a -jakarta version.
Addons and plugins transitive dependencies
Maven will automatically resolve transitive dependencies provided by a given dependencies.
In the case of ZK addons such as Keikai, the addons list default ZK core dependencies using javax.servlet. If you are updating to jakarta version, you will need to either manually define the core zk libraries originally loaded by the addons (zk, zkbind, zkplus, zkmax, etc.), or use dependency management to lock the -jakrata versions of the these jars.
Using maven's dependency tree command is a great way to review what dependencies are loaded transitively by the addons, in order to lock them with the -jakarta version instead.
If you have replaced the servlet-API dependency for you project, you will need to refactor Java classes which imports related classes.
For example, you may have a custom servlet implementing
javax.servlet.Servlet, or you may be using the
In this case you will need to replace these imports by the equivalent one from the Jakarta Servlet-API library. In most cases, the imported class will use the same name and package structure:
We recommend that you also refer to the update guide for your preferred run environment.
Running the project in debug mode
There are three approaches to running a project in debug mode in eclipse. Since servlet 5.0 is still a new implementation, not every launch plugin may currently provide servlet 5.0 support.
At time of writing, the jetty integration for eclipse provide jetty support up to jetty 9, which is not compatible with Jakarta servlet.
Run from maven
Refer to the approach described in the eclipse and maven quick start guide.
When configuring your application's pom file, use a jetty version that supports servlet 5.0. For example, the 11.0.X version of the | jetty-maven-plugin supports this specification.
You can then start your project as a maven build, using
Debug as... > Maven build... and declaring the
Run on server through eclipse
Run on server and remotely debug with JPDA
You can run any servlet 5.0 compatible web server in JPDA mode and use remote debugging to connect to the server.
|Documentation relative to ZK 9.6.0-Jakarta