Solution: Deploying Liferay 7.4 DXP 2025 Q4 on JBoss EAP 8.0 with Oracle 19c

General
1

Solution: Deploying Liferay 7.4 DXP 2025 Q4 on JBoss EAP 8.0 with Oracle 19c

Author: Jefferson Capelo
Email: jcapelo@greenintegration.com.ec
Company: Green Integration
Date: December 2025
Context: Migration from Liferay 7.2 to 7.4 DXP 2025 Q4

Problem

When deploying Liferay 7.4 DXP 2025 Q4 on JBoss EAP 8.0 with Oracle 19c, the following issues occur:

1. Deployment XML Parsing Error

WFLYSRV0174: Unexpected content of type 'element start', 
name is '{urn:jboss:deployment-structure:1.1}exclude-subsystems'

2. JSP ClassLoader Conflict

java.lang.ClassCastException: class org.apache.jasper.runtime.JspApplicationContextImpl 
cannot be cast to class org.apache.jasper.runtime.JspApplicationContextImpl 
(org.apache.jasper.runtime.JspApplicationContextImpl is in unnamed module of loader 
'io.undertow.jsp@2.2.8.Final-redhat-00001' vs com.liferay.shielded.container.internal.ShieldedContainerClassLoader)

3. Product Menu Not Visible

The left sidebar Product Menu does not appear in the Liferay interface due to JSP conflicts between JBoss and Liferay.

Root Cause

The problem originates because:

  1. JBoss EAP 8.0 includes its own JSP engine (Undertow JSP) based on Jakarta EE 10

  2. Liferay 7.4 DXP brings its own embedded JSP engine with isolated classloaders (Shielded Container)

  3. Both attempt to load the same JSP classes (JspApplicationContextImpl) from different classloaders

  4. This causes a type conflict that prevents proper rendering of JSP components like the Product Menu

Complete Solution

Step 1: Configure jboss-deployment-structure.xml

Create or modify the WEB-INF/jboss-deployment-structure.xml file inside the Liferay WAR with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.1">
    <deployment>
        <exclusions>
            <module name="io.undertow.jsp" />
            <module name="org.apache.jasper" />
            <module name="jakarta.faces.api" />
            <module name="org.jboss.as.jsf" />
            <module name="org.apache.taglibs.standard-impl" />
        </exclusions>
        
        <dependencies>
            <module name="jakarta.mail.api" />
            <module name="java.xml" />
        </dependencies>
    </deployment>
</jboss-deployment-structure>

Exclusion Explanation:

  • io.undertow.jsp: Excludes Undertow’s JSP engine

  • org.apache.jasper: Excludes JBoss’s Apache Jasper implementation

  • jakarta.faces.api: Prevents JSF conflicts

  • org.jboss.as.jsf: Excludes JBoss JSF subsystem

  • org.apache.taglibs.standard-impl: Prevents taglib implementation conflicts

Minimal Dependencies:

  • jakarta.mail.api: Mail API required by Liferay

  • java.xml: Standard XML processing

Step 2: Disable JSP in standalone.xml

Modify the JBoss configuration file (standalone/configuration/standalone.xml or your active profile):

Option A: Manual XML Editing

Find the undertow subsystem section and modify or add the JSP configuration:

<subsystem xmlns="urn:jboss:domain:undertow:14.0" default-server="default-server" 
           default-virtual-host="default-host" default-servlet-container="default" 
           default-security-domain="other" statistics-enabled="${wildfly.undertow.statistics-enabled:${wildfly.statistics-enabled:false}}">
    <buffer-cache name="default"/>
    <server name="default-server">
        <!-- server configuration -->
    </server>
    <servlet-container name="default">
        <jsp-config development="false" disabled="true"/>
        <!-- rest of configuration -->
    </servlet-container>
    <!-- rest of undertow configuration -->
</subsystem>

Important Attributes:

  • development="false": Disables JSP development mode

  • disabled="true": CRITICAL - Completely disables JBoss JSP compiler

Option B: Using JBoss CLI

Connect to JBoss CLI and execute:

# Connect to server
./jboss-cli.sh --connect

# Disable JSP
/subsystem=undertow/servlet-container=default/setting=jsp:add(disabled=true,development=false)

# Or if it already exists, modify it:
/subsystem=undertow/servlet-container=default/setting=jsp:write-attribute(name=disabled,value=true)

# Reload configuration
reload

Step 3: Clean Temporary Directories

Before restarting JBoss, completely clean temporary directories:

cd $JBOSS_HOME/standalone

# Stop JBoss if running
./bin/jboss-cli.sh --connect command=:shutdown

# Clean temporary directories
rm -rf data/*
rm -rf tmp/*
rm -rf deployments/ROOT.war.deployed
rm -rf deployments/ROOT.war.failed

On Windows:

cd %JBOSS_HOME%\standalone
rd /s /q data
rd /s /q tmp
del deployments\ROOT.war.deployed
del deployments\ROOT.war.failed

Step 4: Deploy and Verify

  1. Copy the Liferay WAR to the deployment directory:
cp liferay-dxp-7.4-2025-q4.war $JBOSS_HOME/standalone/deployments/ROOT.war
  1. Start JBoss:
./bin/standalone.sh

  1. Verify in the logs that NO ClassCastException errors related to JSP appear

  2. Access Liferay and verify that the Product Menu appears correctly on the left side

Tested Versions

  • Liferay: 7.4 DXP 2025 Q4

  • JBoss EAP: 8.0 Update 11.0 (21.0.18.Final-redhat-00001)

  • Database: Oracle 19c

  • Java: OpenJDK 11 or 17

  • Operating System: Linux/Windows

Considerations for Migration from 7.2 to 7.4

During the migration process from Liferay 7.2 to 7.4, consider:

  1. Jakarta EE Changes: JBoss EAP 8.0 uses Jakarta EE 10 (jakarta.* namespace instead of javax.*)

  2. Shielded Classloader: Liferay 7.4 uses a stricter classloader system

  3. Module Compatibility: Some JBoss modules may conflict with Liferay’s embedded libraries

  4. Oracle JDBC: Ensure using a driver compatible with Oracle 19c (ojdbc8.jar or higher)

Troubleshooting

If Product Menu Still Not Appearing:

  1. Verify there are no JSP errors in Liferay logs

  2. Check that the jboss-deployment-structure.xml file is in WEB-INF/ of the WAR

  3. Confirm JSP is actually disabled in standalone.xml:

/subsystem=undertow/servlet-container=default/setting=jsp:read-resource

If Module Not Found Errors Appear:

Verify that exclusions in jboss-deployment-structure.xml are not blocking required modules. Minimum required modules are:

  • jakarta.mail.api

  • java.xml

If Oracle Database Issues Occur:

  1. Verify Oracle JDBC driver is correctly installed as a JBoss module

  2. Confirm datasource configuration in standalone.xml

  3. Review connection parameters in portal-ext.properties

References

License and Usage

This solution is free to use and distribute. Attribution to the author and original source is appreciated.

Contact for Support:
Jefferson Capelo
Green Integration
jcapelo@greenintegration.com.ec

Changelog

  • v1.0 (December 2025): Initial solution published

    • jboss-deployment-structure.xml configuration

    • JSP disabling in standalone.xml

    • Complete deployment procedure

    • Validated in production environment during 7.2 → 7.4 migration

Tags: #Liferay #JBoss #EAP8 #Oracle19c #Migration #JSP #ClassLoader #ProductMenu #DXP #Jakarta

5 Likes