Troubleshooting Common Payara Deployment Issues in Jakarta EE 9

Deploying applications on Payara Server, particularly with Jakarta EE 9, can sometimes lead to unexpected hurdles. This blog post is dedicated to helping you identify and troubleshoot common deployment issues you might encounter while using Payara Server. By the end of this guide, you should be equipped with useful strategies to overcome these challenges.

Understanding Payara and Jakarta EE

Before delving into troubleshooting, it's imperative to understand the relationship between Payara Server and Jakarta EE.

Payara Server is an open-source application server derived from GlassFish. It supports features of Jakarta EE, which is an evolution of Java EE. The transition from Java EE to Jakarta EE involved namespace changes and other enhancements aimed at improving the developer's experience.

For an in-depth overview, you can refer to the official Jakarta EE documentation.

Common Deployment Issues

Let’s explore several common problems you might face while deploying applications on Payara Server and how to resolve them.

1. Missing Dependencies

One challenge many developers face is missing libraries or dependencies during deployment. Payara requires specific libraries available during runtime, and if these are omitted, deployment can fail.

Solution:

Always check the dependency declarations in your pom.xml or build.gradle files, depending on your build tool. To aid in debugging, Payara creates logs that can be particularly useful. The log file is located at payara5/glassfish/domains/domain1/logs/server.log.

Example Log Entry:

[2023-01-26T11:31:35.123+0000] [Payara 5.2021.1] [ERROR] [] [javax.enterprise.system.container.java] [tid: _Thread-2] [time: 2023-01-26 11:31:35.123 UTC] [level: SEVERE] [class: org.glassfish.api.deployment.DeploymentException] [method: handle] Deployment failed, probably due to missing or unresolved dependencies.

2. Namespace Issues

With Jakarta EE 9, the most notable change was the transition from javax to jakarta namespaces.

Solution:

Ensure that all your imports have been updated correctly. This means looking for all occurrences of the old namespace in your Java files, XML files (like web.xml and persistence.xml), and configuration files.

Example Code Snippet:

import jakarta.persistence.Entity; // Correct Namespace
// import javax.persistence.Entity; // Old Namespace

@Entity
public class Product {
    // Class Implementation
}

3. Configuration Errors

Configuration errors can occur if there is a mismatch between deployment descriptors and the project structure. Payara Server reads several configuration files during deployment.

Solution:

Verify your configuration files for correctness. Besides checking XML for errors, ensure your persistence.xml or any servlet configurations are correct.

Example persistence.xml:

<persistence xmlns="http://jakarta.ee/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://jakarta.ee/xml/ns/persistence
             http://jakarta.ee/xml/ns/persistence/persistence_2_2.xsd"
             version="2.2">

    <persistence-unit name="example-unit">
        <provider>jakarta.persistence.spi.PersistenceProvider</provider>
        <class>com.example.Product</class>
        <properties>
            <property name="javax.persistence.jdbc.user" value="user"/>
            <property name="javax.persistence.jdbc.password" value="password"/>
            <property name="javax.persistence.jdbc.url" value="jdbc:h2:mem:test;DB_CLOSE_DELAY=-1"/>
            <property name="javax.persistence.jdbc.driver" value="org.h2.Driver"/>
        </properties>
    </persistence-unit>
</persistence>

Make sure the schema used matches Jakarta EE 9 standards.

4. Database Connection Issues

Many application deployments require a connection to a database. If your datasource is misconfigured, your application may not start.

Solution:

Check the datasource configuration in the Payara Admin Console or via the command line. Ensure the database server is running and reachable.

Connecting a datasource:

asadmin create-jdbc-connection-pool --connectionpoolid myDBPool --restype javax.sql.DataSource --property User=myuser:Password=mypassword:URL=jdbc:h2:mem:test myDBPool

5. Port Conflicts

Another common issue can arise from port conflicts. If another application is using the same ports configured for Payara, you’ll encounter an error.

Solution:

Change the port settings in the domain.xml file located at payara5/glassfish/domains/domain1/config/. Adjust the following settings:

<network-listeners>
    <network-listener protocol="http-listener"
                       port="8080"
                       ... />
</network-listeners>

Ensure no other service is using that port.

6. Memory Issues

Under-resourcing your Payara server can lead to Java heap space errors or other memory-related issues during deployment.

Solution:

Increase the Java heap size in the domain.xml or via asadmin command line.

Example Command:

asadmin set-jvm-options "-Xmx512m"

This command sets the maximum heap size to 512 MB. Adjust it as necessary according to your application's needs.

7. Slow Deployment

Sometimes, your application may take forever to deploy due to various reasons including inefficient code, large files, or heavy dependencies.

Solution:

Consider optimizing your application. Break it down into smaller modules if possible. Analyze performance bottlenecks using monitoring tools such as Java Mission Control.

The Last Word

Troubleshooting deployment issues on Payara Server when working with Jakarta EE 9 can initially seem daunting. However, by systematically analyzing logs, checking configurations, and ensuring proper dependency management, most roadblocks can be effectively overcome. Always refer to the official Payara documentation for up-to-date information and deeper insights into configurations.

Deploying applications is a skill cultivated with time and experience. By implementing these troubleshooting strategies, you will likely find greater ease in your deployment journeys within the Jakarta EE ecosystem on Payara Server. Happy coding!