Cloud Software Group, Inc. EBX®
Documentation > Developer Guide > Introduction
Navigation mode Documentation > Developer Guide > Introduction

# Packaging TIBCO EBX® modules

An EBX® module is a standard Jakarta EE web application, packaging various resources such as XML Schema documents, Java classes and static resources.

Since EBX® modules are web applications they benefit from features such as class-loading isolation, WAR or EAR packaging, and Web resources exposure.

## Module structure

An EBX® module contains the following files:

`/WEB-INF/ebx/module.xml` | This mandatory document defines the main properties and services of the module. See Module declaration.
`/WEB-INF/web.xml` | This is the standard Jakarta EE deployment descriptor. It can perform the registration of the EBX® module when the application server is launched. See Module registration.
`/META-INF/MANIFEST.MF` | Optional. If present, EBX® reports the 'Implementation-Title' and 'Implementation-Version' values to Administration > Technical configuration > Modules and data models.
`/www/` | This optional directory contains all packaged resources, which are accessible via public URL. See Packaged resources.

## Module declaration

A module is declared using the document `/WEB-INF/ebx/module.xml`. For example:

    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:ebx-schemas:module_2.4"
    	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    	xsi:schemaLocation="urn:ebx-schemas:module_2.4 https://schema.orchestranetworks.com/module_2.4.xsd">
    	<name>moduleTest</name>
    </module>

See the associated schema for documentation about each property. The main properties are as follows:

Element | Description | Required
--- | --- | ---
`name` | Defines the unique identifier of the module in the server instance. The module name usually corresponds to the name of the web application (the name of its directory). | Yes.
`publicPath` | Defines a path other than the module's name identifying the web application in public URLs. This path is added to the URL of external resources of the module when computing absolute URLs. If this field is not defined, the public path is the module's `name`, defined above. | No.
`services` | Declares user services using the legacy API. See Declaration and configuration of legacy user services. From the version 5.8.0, it is strongly advised to use the new user services. | No.
`beans` | Declares reusable Java bean components. See the workflow package. | No.
`ajaxComponents` | Declares Ajax components. See Declaring an Ajax component in a module in the Java API. | No.

## Module registration

In order to be identifiable by EBX®, a module must be registered at runtime when the application server is launched. For a web application, every EBX® module must:

- contain a Java class with the annotation `@WebListener` extending the class `ModuleRegistrationListener`.

  ##### Attention

  When using the `@WebListener` annotation, ensure that the application server is configured to activate the servlet 3.0 annotation scanning for the web application. See `JSR 315`: JavaTM Servlet 3.0 Specification for more information.

or:

- contain a Servlet extending the class `ModuleRegistrationServlet`;

- make a standard declaration of this servlet in the deployment descriptor `/WEB-INF/web.xml`;

- ensure that this servlet will be registered at server startup by adding the following standard element to the deployment descriptor: `<load-on-startup>1</load-on-startup>`.

Additional recommendations and information:

- The method `handleRepositoryStartup` in `ModuleRegistrationServlet` allows setting the logger associated with the module and defining additional behavior such as common JavaScript and CSS resources.

- The specific class extending `ModuleRegistrationServlet` must be located in the web application (under `/WEB-INF/classes` or `/WEB-INF/lib`; due to the fact that this class is internally used as a hook to the application's class-loader, to load Java classes used by the data models associated with the module).

- The application server startup process is asynchronous and web applications / EBX® modules are discovered dynamically. The EBX® repository initialization depends on this process and will wait for the registration of all used modules up to an unlimited amount of time. As a consequence, if a used module is not deployed for any reason, it must be declared in the EBX® main configuration file. For more information, see the property Declaring modules as undeployed.

- All module registrations and unregistrations are logged in the `log.kernel` category.

- If an exception occurs while loading a module, the cause is written in the application server log.

- Once the servlet is out of service, the module is unregistered and the data models and associated datasets become unavailable. Note that hot deployment/undeployment is not supported.

### Deployment descriptor example

Here is an example of a Jakarta EE deployment descriptor (`/WEB-INF/web.xml`):

    <?xml version="1.0" encoding="UTF-8"?>
    <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 https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
          version="5.0">
    	<servlet>
    	   <servlet-name>InitEbxServlet</servlet-name>
    	   <servlet-class>com.foo.RegisterServlet</servlet-class>
    	   <load-on-startup>1</load-on-startup>
    	</servlet>
    </web-app>

### Registration example

Here is an implementation example of the `ModuleRegistrationServlet`:

    package com.foo;
    import jakarta.servlet.*;
    import jakarta.servlet.http.*;
    import com.onwbp.base.repository.*;

    public class RegisterServlet extends ModuleRegistrationServlet
    {

    	public void handleRepositoryStartup(ModuleContextOnRepositoryStartup aContext)
    		throws OperationException
    	{
    		// Perform module-specific initializations here
    		...

    		// Declare custom resources here
    		aContext.addExternalStyleSheetResource(MyCompanyResources.COMMON_STYLESHEET_URL);
    		aContext.addExternalJavaScriptResource(MyCompanyResources.COMMON_JAVASCRIPT_URL);

    		aContext.addPackagedStyleSheetResource("myModule.css");
    		aContext.addPackagedJavaScriptResource("myModule.js");

    	}

    	public void handleRepositoryShutdown()
    	{
    		// Release resources of the current module when the repository is shut down here
    		...
    	}

    		public void destroyBeforeUnregisterModule()
    	{
    		// Perform operations when this servlet is being taken out of service here
    		...
    	}

    }

## Packaged resources

The packaged resources are files and documents that can be directly accessed from client browsers and can be managed and specified either as `osd:resource` fields or via the Java API. They have various types and can also be localized.

##### See also

- `ResourceType`
- Type `osd:resource`

### Directory structure

The packaged resources must be located under the following directory structure:

1. On the first level, the directory `/www/` must be located at the root of the module (web application).

2. On the second level, the directory must specify the localization. It can be:

   - `common/` should contain all the resources to be used by default, either because they are locale-independent or as the default localization (in EBX®, the default localization is `en`, namely English);

   - `{lang}/` when localization is required for the resources located underneath, with `{lang}` to be replaced by the actual locale code; it should correspond to the locales supported by EBX®; for more information, see Configuring EBX® localization.

3. On the third level, the directory must specify the resource type. It can be:

   - `jscripts/` for JavaScript resources;

   - `stylesheets/` for Cascading Style Sheet (CSS) resources;

   - `html/` for HTML resources;

   - `icons/` for icon typed resources;

   - `images/` for image typed resources.

### Example

In this example, the image `logoWithText.jpg` is the only resource that is localized:

    /www
     ├── common
     │   ├── images
     │   │   ├── myCompanyLogo.jpg
     │   │   └── logoWithText.jpg
     │   ├── jscripts
     │   │   └── myCompanyCommon.js
     │   └── stylesheets
     │       └── myCompanyCommon.css
     ├── de
     │   └── images
     │       └── logoWithText.jpg
     └── fr
         └── images
             └── logoWithText.jpg

Documentation > Developer Guide > Introduction