This chapter details deployment specifications for TIBCO EBX® on a Java application server. For specific information regarding supported application servers and inherent limitations, see Supported environments.
Refer to the Security Best Practices for information on navigating secure deployments.
EBX® uses the following components:
Library ebx.jar
EBX® built-in web applications and optional custom web applications
Default user and roles directory, integrated within the EBX® repository, or a third-party system (LDAP, RDBMS) for the user authentication
To increase EBX® independence and interoperability, it embeds its own third-party libraries. Even if some of them have been modified, preventing conflicts, others must remain unchanged since they are official Java APIs.
The ones that can produce conflicts are:
Apache Geronimo JSON
Apache Geronimo JSON Bind
Jakarta Activation API
Jakarta Annotations API
Jakarta JSON API
Jakarta JSON Binding
Jakarta Transaction API
Jakarta WS RS
Jakarta XML Bind
Jakarta XML SOAP messaging API
Jakarta XML WS API
MicroProfile OpenAPI
For more information regarding the versions or the details of the Third-Party Library, please refer to the: TIB_ebx_6.2.3_license.pdf.
Since those libraries are already integrated, custom web applications should not include them anew, otherwise linkage errors can occur. Furthermore, they should not be deployed aside from the ebx.jar library for the same reasons.
EBX® requires several third-party Java libraries. These libraries must be deployed and be accessible from the class-loader of ebx.jar. Depending on the application server and the Java runtime environment being used, these libraries may already be present or may need to be added manually.
Starting with EBX® version 6.2.3, deployment of a separate compression library is no longer required. The following 2 compression modes are supported:
Native is the optimal, faster mode but only available if using Java 21 or newer on Linux/Windows, x86_64.
A pure Java implementation is also available when using Java 17.
To see the compression type you are using, open kernel.log and look for:
Compression: Java, or
Compression: Native
If native compression is not being used, the reason will display in the logs.
If you find compression performance is an issue, use the following parameters in ebx.properties to adjust it:
ebx.compression.dictSize controls the dictionary size and defaults to 16 KB. The recommended range is between 1 KB to 64 KB. However, you should be aware of the following tradeoff that occurs with a larger dictionary: The compression ratio (Logarithmic progression) is better, but compression is slower (linear increase).
You must set this value ahead of time. After EBX® creates a dictionary for a given table definitions, it does not create another one. The new value only applies to tables that don't have a dictionary, or to new table definitions.
ebx.compression.level controls the compression level. Possible values are FAST, BALANCED, and HIGH (default). Lower the level to speed up compression, but expect a lower compression ratio. This setting immediately applies to the next compression operation. This setting has no noticeable impact on decompression.
The EBX® repository requires a database. Generally, the required driver is configured along with a data source, if one is used. Depending on the database defined in the main configuration file, one of the following drivers is required. Keep in mind that, whichever database you use, the version of the JDBC client driver must be equal to or higher than the version of the database server.
H2 | Version 2.2.224 validated. Note that H2 is not supported in production environments. If the H2 repository has been built with version 1.0 driver, this migration to v2 process must be applied. |
Oracle JDBC | Oracle database 23ai is validated on their latest patch set update. Determine the driver that should be used according to the database server version and the Java runtime environment version. Download the |
SQL Server JDBC | SQL Server 2014 and greater, with all corrective and maintenance patches applied, are validated. Remember to use an up-to-date JDBC driver, as some difficulties have been encountered with older versions. For example, include the |
PostgreSQL | PostgreSQL Java 8 validated Include the latest JDBC driver version 4.2 released for your database server and Java runtime environment. |
According to the web application server being used, the library Jakarta Mail API for email management may already be provided, or must be added manually.
EBX® requires a library that is compatible with version 2.0 of this API. See Activating and configuring SMTP and emails for more information on the configuration.
To facilitate manual installation, the jakarta.mail-2.0.2.jar has been provided and placed under the ebx.software/lib/lib-mail directory.
SSL features activation, configuration, and management are tightly linked to the web application server used. Consequently, you should refer to the appropriate web application server documentation. For example, Tomcat SSL/TLS Configuration How-To.
When using JMS, version 3.0.0 or higher is required.
Depending on whether a Jakarta EE application server or a Servlet/Java Server Pages (JSP) implementation is being used, the library required is as follows:
For an application server based on Jakarta EE (Enterprise Edition), the required JMS provider library is available by default. See https://jakarta.ee/specifications/platform/ for more information.
For a Servlet/Java Server Pages (JSP) implementation using Java SE (Java Platform Standard Edition), for example Apache Tomcat, a JMS provider library such as Apache ActiveMQ may need to be added. See https://www.oracle.com/java/technologies/java-se-glance.html for more information.
In EBX®, the supported JMS model is exclusively Point-to-Point (PTP). PTP systems allow working with queues of messages.
EBX® provides pre-packaged EARs that can be deployed directly if your company has no custom EBX® module web applications to add. If deploying custom web applications as EBX® modules, it is recommended to rebuild an EAR containing the custom modules packaged at the same level as the built-in web applications.
Web application deployment on / path context is no more supported. The path context must not be empty nor equals to /. Moreover, web applications deployment on paths of different depth is deprecated. Every web application path context must be set on the same path depth.
For more information, see the note on repackaging the EBX® EAR at the end of this chapter.
EBX® includes the following built-in web applications.
Web application name | Description | Required |
|---|---|---|
| EBX® entry point, which handles the initialization on start up. See Deployment details for more information. | Yes |
| EBX® root web application. Any application that uses EBX® requires the root web application to be deployed. | Yes |
| EBX® user interface web application. | Yes |
| EBX® authentication application. | Yes |
| EBX® user interface web application. | Yes |
| EBX® data model assistant, which helps with the creation of data models through the user interface. Note: The data model assistant requires the | Yes |
| EBX® data services web application. Data services allow external interactions with the EBX® repository using the SOAP operations and Web Services Description Language WSDL generation standards or using the Built-in RESTful services. Note: The EBX® web service generator requires the deployment of the | Yes |
| EBX® Integrated Development Environment web application. | Yes |
| EBX® assistant web application. | Yes |
| EBX® Hub web application. | No |
It is possible to extend the behavior of EBX® by deploying add-ons applications.
It is possible to extend and customize the behavior of EBX® by deploying custom web applications which conform to the EBX® module requirements.
This section describes the various options available to deploy the 'ebx' web application. These options are available in its deployment descriptor (WEB-INF/web.xml) and are complemented by the properties defined in the main configuration file.
For JBoss application servers, any unused resources must be removed from the WEB-INF/web.xml deployment descriptor.
The web application 'ebx' (packaged as ebx.war) contains the servlet FrontServlet, which handles the initialization and serves as the sole user interface entry point for the EBX® web tools.
In the file WEB-INF/web.xml of the web application 'ebx', the following elements must be configured for FrontServlet:
| To ensure that |
|
|
FrontServlet must be authorized to access other contexts, such as ServletContext.
For example, on Tomcat, this configuration is performed using the attribute crossContext in the configuration file server.xml, as follows:
<Context path="/ebx" docBase="(...)" crossContext="true"/>
If the EBX® main configuration specifies the property ebx.persistence.url, then the environment entry below will be ignored by EBX® runtime. This option is only provided for convenience; it is always recommended to use a fully-configurable datasource. In particular, the size of the connection pool must be set according to the number of concurrent users. See Configuring the EBX® repository for more information on this property.
The JDBC datasource for EBX® is specified in the deployment descriptor WEB-INF/web.xml of the 'ebx' web application as follows:
Reserved resource name | Default JNDI name | Description |
|---|---|---|
| JBoss: | JDBC data source for EBX® Repository. Java type: |
If the EBX® main configuration does not set ebx.mail.activate to 'true', or if it specifies the property ebx.mail.smtp.host, then the environment entry below will be ignored by EBX® runtime. See SMTP in the EBX® main configuration properties for more information on these properties.
SMTP and email is declared in the deployment descriptor WEB-INF/web.xml of the 'ebx' web application as follows:
Reserved resource name | Default JNDI name | Description |
|---|---|---|
| JBoss: | Java Mail session used to send emails from EBX®. Java type: |
If the EBX® main configuration does not activate JMS through the property ebx.jms.activate, the environment entry below will be ignored by the EBX® runtime. See JMS in the EBX® main configuration properties for more information on this property.
The JMS connection factory is declared in the deployment descriptor WEB-INF/web.xml of the 'ebx' web application as follows:
Reserved resource name | Default JNDI name | Description | Required |
|---|---|---|---|
| JBoss: | JMS connection factory used by EBX® to create connections with the JMS provider configured in the operational environment of the application server. Java type: | Yes |
For deployment on WildFly, JBoss application servers with JNDI capabilities, you must update EBX.ear for additional mappings of all required resource names to JNDI names.
To configure data services to use JMS instead of the default HTTP, you must configure the JMS connection factory and the following queues, declared in the WEB-INF/web.xml deployment descriptor of the 'ebx' web application. This is the only method for configuring JMS for data services.
When a SOAP request is received, the SOAP response is optionally returned if the header field JMSReplyTo is defined. If so, the fields JMSCorrelationID and JMSType are retained.
See JMS for more information on the associated EBX® main configuration properties.
If the EBX® main configuration does not activate JMS through the property ebx.jms.activate, then the environment entries below will be ignored by EBX® runtime. See JMS in the EBX® main configuration properties for more information on this property.
Reserved resource name | Default JNDI name | Description | Required |
|---|---|---|---|
| JBoss: | JMS queue for incoming SOAP requests sent to EBX® by other applications. Java type: | No |
| JBoss: | JMS queue for failures. It contains incoming SOAP requests for which an error has occurred. This allows replaying these messages if necessary. Java type: Note: For this property to be read, the main configuration must also activate the queue for failures through the property | No |
To speed up the web applications server startup, the JAR files scanner configuration should be modified to exclude, at least, the ebx.jar and ebx-addons.jar libraries.
For example, on Tomcat, this should be performed in the tomcat.util.scan.StandardJarScanFilter.jarsToSkip property from the catalina.properties file.
EBX® can be deployed on any Jakarta EE 9 or greater application server that supports Servlet 5.0 and above. The following documentation on deployment and installation notes are available:
The EBX® installation notes on Jakarta EE 9 application servers do not replace the native documentation for each application server.
These are not general installation recommendations, as the installation process is determined by architectural decisions, such as the technical environment, application mutualization, delivery process, and organizational decisions.
In these examples, no additional EBX® modules are deployed. To deploy custom or add-on modules, the best practice is to rebuild an EAR with the module as a web application at the same level as the other EBX® modules. The web application must declare its class path dependency as specified by the Java™ 2 Platform Enterprise Edition Specification, v1.4:
J2EE.8.2 Optional Package Support
(...)
A JAR format file (such as a JAR file, WAR file, or RAR file) can reference a JAR file by naming the referenced JAR file in a Class-Path header in the Manifest file of the referencing JAR file. The referenced JAR file is named using a URL relative to the URL of the referencing JAR file. The Manifest file is named META-INF/MANIFEST.MF in the JAR file. The Class-Path entry in the Manifest file is of the form:
Class-Path: list-of-jar-files-separated-by-spaces
In an "industrialized" process, it is strongly recommended to develop a script that automatically builds the EAR, with the custom EBX® modules, the EBX® web applications, as well as all the required shared libraries.
In order to avoid unpredictable behavior, the guideline to follow is to avoid any duplicates of ebx.jar or other libraries in the class-loading system.