Skip to content

Feature Request: Automatic Stub Generation and Validation of IBM Deployment Descriptors #396

Open
Open
Feature Request: Automatic Stub Generation and Validation of IBM Deployment Descriptors#396
Labels
enhancementNew feature or request
@venmanyarun

Description

@venmanyarun
venmanyarun
opened on Feb 6, 2026

Feature Request: Automatic Stub Generation and Validation of IBM Deployment Descriptors

Overview

Enhance the Liberty Language Server to automatically generate stub files and provide comprehensive language support (validation, completion, hover, diagnostics) for IBM-specific deployment descriptors, similar to the existing support for server.xml configuration files.

Problem Statement

Currently, the Liberty Language Server provides excellent support for:

  • server.xml - Liberty server configuration
  • bootstrap.properties - Bootstrap properties
  • server.env - Server environment variables

However, IBM-specific deployment descriptors lack language server support, forcing developers to:

  • Manually reference documentation
  • Create descriptor files from scratch without templates
  • Debug configuration errors without validation
  • Miss out on auto-completion and hover documentation

Proposed Solution

Provide automatic stub generation and full language server features for all IBM deployment descriptors used in Liberty/WebSphere applications.

Supported IBM Deployment Descriptors

1. Web Application Descriptors

1.1 ibm-web-ext.xml (Web Extensions)

Location: WEB-INF/ibm-web-ext.xml
Purpose: Extends web application configuration with IBM-specific features

Example Stub:

<?xml version="1.0" encoding="UTF-8"?>
<web-ext
    xmlns="http://websphere.ibm.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee 
        http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_1.xsd"
    version="1.1">
    
    <!-- Reload settings -->
    <reload-interval value="3"/>
    <enable-directory-browsing value="false"/>
    <enable-file-serving value="true"/>
    <enable-reloading value="true"/>
    <enable-serving-servlets-by-class-name value="false"/>
    
    <!-- Context root override -->
    <context-root uri="/myapp"/>
    
    <!-- Default error page -->
    <default-error-page uri="/error.jsp"/>
    
    <!-- File serving attributes -->
    <file-serving-attribute name="com.ibm.ws.webcontainer.fileServingEnabled" value="true"/>
    
    <!-- Auto-load filters -->
    <autoload-filters value="true"/>
    
</web-ext>

Common Elements:

  • <reload-interval> - Application reload interval
  • <context-root> - Override context root
  • <enable-directory-browsing> - Enable/disable directory browsing
  • <enable-file-serving> - Enable/disable static file serving
  • <enable-reloading> - Enable/disable application reloading
  • <default-error-page> - Default error page URI
  • <file-serving-attribute> - File serving configuration
  • <autoload-filters> - Auto-load filter configuration

1.2 ibm-web-bnd.xml (Web Bindings)

Location: WEB-INF/ibm-web-bnd.xml
Purpose: Binds web application resources to Liberty/WebSphere resources

Example Stub:

<?xml version="1.0" encoding="UTF-8"?>
<web-bnd
    xmlns="http://websphere.ibm.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee 
        http://websphere.ibm.com/xml/ns/javaee/ibm-web-bnd_1_2.xsd"
    version="1.2">
    
    <!-- Virtual host binding -->
    <virtual-host name="default_host"/>
    
    <!-- Resource reference bindings -->
    <resource-ref name="jdbc/myDataSource" binding-name="jdbc/myDS"/>
    <resource-ref name="jms/myConnectionFactory" binding-name="jms/myCF"/>
    
    <!-- EJB reference bindings -->
    <ejb-ref name="ejb/MyBean" binding-name="ejb/MyBeanJNDI"/>
    
    <!-- Resource environment reference bindings -->
    <resource-env-ref name="jms/myQueue" binding-name="jms/Queue1"/>
    
    <!-- Message destination reference bindings -->
    <message-destination-ref name="jms/myTopic" binding-name="jms/Topic1"/>
    
</web-bnd>

Common Elements:

  • <virtual-host> - Virtual host binding
  • <resource-ref> - JDBC/JMS resource bindings
  • <ejb-ref> - EJB reference bindings
  • <resource-env-ref> - Resource environment bindings
  • <message-destination-ref> - Message destination bindings
  • <env-entry> - Environment entry bindings

2. Enterprise Application Descriptors

2.1 ibm-application-ext.xml (Application Extensions)

Location: META-INF/ibm-application-ext.xml
Purpose: Extends enterprise application configuration

Example Stub:

<?xml version="1.0" encoding="UTF-8"?>
<application-ext
    xmlns="http://websphere.ibm.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee 
        http://websphere.ibm.com/xml/ns/javaee/ibm-application-ext_1_2.xsd"
    version="1.2">
    
    <!-- Reload settings -->
    <reload-interval value="3"/>
    <enable-reloading value="true"/>
    
    <!-- Shared library references -->
    <shared-library-ref>
        <shared-library-name>mySharedLib</shared-library-name>
    </shared-library-ref>
    
    <!-- Module extensions -->
    <module name="myWebModule.war">
        <context-root uri="/myapp"/>
    </module>
    
</application-ext>

Common Elements:

  • <reload-interval> - Application reload interval
  • <enable-reloading> - Enable/disable reloading
  • <shared-library-ref> - Shared library references
  • <module> - Module-specific extensions
  • <context-root> - Module context root override

2.2 ibm-application-bnd.xml (Application Bindings)

Location: META-INF/ibm-application-bnd.xml
Purpose: Binds enterprise application resources

Example Stub:

<?xml version="1.0" encoding="UTF-8"?>
<application-bnd
    xmlns="http://websphere.ibm.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee 
        http://websphere.ibm.com/xml/ns/javaee/ibm-application-bnd_1_2.xsd"
    version="1.2">
    
    <!-- Security role mappings -->
    <security-role name="Administrator">
        <user name="admin"/>
        <group name="admins"/>
        <special-subject type="ALL_AUTHENTICATED_USERS"/>
    </security-role>
    
    <security-role name="User">
        <group name="users"/>
    </security-role>
    
    <!-- Resource reference bindings -->
    <resource-ref name="jdbc/myDataSource" binding-name="jdbc/myDS"/>
    
    <!-- EJB reference bindings -->
    <ejb-ref name="ejb/MyBean" binding-name="ejb/MyBeanJNDI"/>
    
</application-bnd>

Common Elements:

  • <security-role> - Security role to user/group mappings
  • <user> - User mapping
  • <group> - Group mapping
  • <special-subject> - Special subject types (ALL_AUTHENTICATED_USERS, EVERYONE)
  • <resource-ref> - Resource bindings
  • <ejb-ref> - EJB bindings

3. EJB Descriptors

3.1 ibm-ejb-jar-ext.xml (EJB Extensions)

Location: META-INF/ibm-ejb-jar-ext.xml
Purpose: Extends EJB configuration with IBM-specific features

Example Stub:

<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar-ext
    xmlns="http://websphere.ibm.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee 
        http://websphere.ibm.com/xml/ns/javaee/ibm-ejb-jar-ext_1_1.xsd"
    version="1.1">
    
    <!-- Session bean extensions -->
    <session name="MySessionBean">
        <time-out value="600"/>
        <local-transaction>
            <boundary value="BEAN_METHOD"/>
            <resolver value="APPLICATION"/>
        </local-transaction>
    </session>
    
    <!-- Entity bean extensions -->
    <entity name="MyEntityBean">
        <read-only value="false"/>
    </entity>
    
    <!-- Message-driven bean extensions -->
    <message-driven name="MyMDB">
        <listener-port name="myListenerPort"/>
    </message-driven>
    
</ejb-jar-ext>

Common Elements:

  • <session> - Session bean extensions
  • <entity> - Entity bean extensions
  • <message-driven> - MDB extensions
  • <time-out> - Transaction timeout
  • <local-transaction> - Local transaction settings
  • <read-only> - Read-only entity flag
  • <listener-port> - MDB listener port

3.2 ibm-ejb-jar-bnd.xml (EJB Bindings)

Location: META-INF/ibm-ejb-jar-bnd.xml
Purpose: Binds EJB resources to JNDI names

Example Stub:

<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar-bnd
    xmlns="http://websphere.ibm.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee 
        http://websphere.ibm.com/xml/ns/javaee/ibm-ejb-jar-bnd_1_2.xsd"
    version="1.2">
    
    <!-- Session bean bindings -->
    <session name="MySessionBean">
        <interface class="com.example.MySessionRemote" binding-name="ejb/MySession"/>
        <interface class="com.example.MySessionLocal" binding-name="ejb/local/MySession"/>
        
        <!-- Resource reference bindings -->
        <resource-ref name="jdbc/myDataSource" binding-name="jdbc/myDS"/>
        <ejb-ref name="ejb/OtherBean" binding-name="ejb/OtherBeanJNDI"/>
    </session>
    
    <!-- Message-driven bean bindings -->
    <message-driven name="MyMDB">
        <jca-adapter activation-spec-binding-name="jms/MyActivationSpec"/>
        <resource-ref name="jms/myConnectionFactory" binding-name="jms/myCF"/>
    </message-driven>
    
</ejb-jar-bnd>

Common Elements:

  • <session> - Session bean bindings
  • <entity> - Entity bean bindings
  • <message-driven> - MDB bindings
  • <interface> - EJB interface JNDI bindings
  • <resource-ref> - Resource reference bindings
  • <ejb-ref> - EJB reference bindings
  • <jca-adapter> - JCA adapter bindings

4. Web Services Descriptors

4.1 ibm-webservices-ext.xml (Web Services Extensions)

Location: META-INF/ibm-webservices-ext.xml or WEB-INF/ibm-webservices-ext.xml
Purpose: Extends web services configuration

Example Stub:

<?xml version="1.0" encoding="UTF-8"?>
<webservices-ext
    xmlns="http://websphere.ibm.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee 
        http://websphere.ibm.com/xml/ns/javaee/ibm-webservices-ext_1_0.xsd"
    version="1.0">
    
    <!-- Web service extensions -->
    <webservice-description name="MyWebService">
        <webservice-description-name>MyWebService</webservice-description-name>
        
        <!-- Port component extensions -->
        <port-component name="MyPort">
            <port-component-name>MyPort</port-component-name>
            
            <!-- Router module -->
            <router-module>com.example.MyRouter</router-module>
            
            <!-- Request/response encoding -->
            <request-encoding>UTF-8</request-encoding>
            <response-encoding>UTF-8</response-encoding>
        </port-component>
    </webservice-description>
    
</webservices-ext>

Common Elements:

  • <webservice-description> - Web service extensions
  • <port-component> - Port component extensions
  • <router-module> - Custom router module
  • <request-encoding> - Request encoding
  • <response-encoding> - Response encoding

4.2 ibm-webservices-bnd.xml (Web Services Bindings)

Location: META-INF/ibm-webservices-bnd.xml or WEB-INF/ibm-webservices-bnd.xml
Purpose: Binds web services to endpoints

Example Stub:

<?xml version="1.0" encoding="UTF-8"?>
<webservices-bnd
    xmlns="http://websphere.ibm.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee 
        http://websphere.ibm.com/xml/ns/javaee/ibm-webservices-bnd_1_1.xsd"
    version="1.1">
    
    <!-- Web service bindings -->
    <webservice-description name="MyWebService">
        <webservice-description-name>MyWebService</webservice-description-name>
        
        <!-- Port component bindings -->
        <port-component name="MyPort">
            <port-component-name>MyPort</port-component-name>
            
            <!-- Service endpoint address -->
            <service-endpoint-address>http://localhost:9080/myapp/MyService</service-endpoint-address>
            
            <!-- Resource reference bindings -->
            <resource-ref name="jdbc/myDataSource" binding-name="jdbc/myDS"/>
        </port-component>
    </webservice-description>
    
</webservices-bnd>

Common Elements:

  • <webservice-description> - Web service bindings
  • <port-component> - Port component bindings
  • <service-endpoint-address> - Endpoint URL
  • <resource-ref> - Resource bindings

5. Client Application Descriptors

5.1 ibm-application-client-ext.xml (Client Extensions)

Location: META-INF/ibm-application-client-ext.xml
Purpose: Extends application client configuration

Example Stub:

<?xml version="1.0" encoding="UTF-8"?>
<application-client-ext
    xmlns="http://websphere.ibm.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee 
        http://websphere.ibm.com/xml/ns/javaee/ibm-application-client-ext_1_0.xsd"
    version="1.0">
    
    <!-- Callback handler -->
    <callback-handler>com.example.MyCallbackHandler</callback-handler>
    
</application-client-ext>

5.2 ibm-application-client-bnd.xml (Client Bindings)

Location: META-INF/ibm-application-client-bnd.xml
Purpose: Binds application client resources

Example Stub:

<?xml version="1.0" encoding="UTF-8"?>
<application-client-bnd
    xmlns="http://websphere.ibm.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee 
        http://websphere.ibm.com/xml/ns/javaee/ibm-application-client-bnd_1_2.xsd"
    version="1.2">
    
    <!-- Resource reference bindings -->
    <resource-ref name="jdbc/myDataSource" binding-name="jdbc/myDS"/>
    
    <!-- EJB reference bindings -->
    <ejb-ref name="ejb/MyBean" binding-name="ejb/MyBeanJNDI"/>
    
</application-client-bnd>

Required Language Server Features

1. Stub Generation

  • Generate valid XML structure with proper namespace declarations
  • Include commonly used elements as comments or placeholders
  • Support version-specific schemas based on Liberty runtime

2. Schema Validation

  • Validate against XSD schemas from Liberty runtime
  • Provide real-time error detection
  • Support multiple schema versions

3. Code Completion

  • Element name completion
  • Attribute name completion
  • Enumerated value completion
  • Context-aware suggestions

4. Hover Documentation

  • Display element/attribute descriptions
  • Show valid values and constraints
  • Include usage examples

5. Diagnostics

  • Schema validation errors
  • Version compatibility warnings
  • Best practice suggestions

6. Quick Fixes

  • Fix invalid values
  • Add missing required elements
  • Update deprecated elements

User Experience

Scenario 1: Creating New Descriptor

  1. User right-clicks in project → "Generate IBM Descriptor"
  2. Selects descriptor type from list
  3. Stub file created with proper structure
  4. Language support immediately available

Scenario 2: Editing Existing Descriptor

  1. User opens ibm-web-bnd.xml
  2. Language server detects Liberty version
  3. Appropriate schema loaded
  4. Full completion, hover, and validation active

Success Criteria

  • ✅ All IBM descriptors have stub generation
  • ✅ Schema-based validation for all descriptor types
  • ✅ Completion and hover match server.xml quality
  • ✅ Support for multiple Liberty versions
  • ✅ Comprehensive documentation with examples

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions