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:

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:

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.

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