Installation Middleware4j: Difference between revisions

Latest revision as of 18:05, 5 April 2026

This page covers deploying Middleware4j on a server or integration host.

Requirements

Network access to any input or output directories defined in the map configuration (local paths, UNC shares, or mounted network drives)
If using the EMAIL connector: network access to an SMTP server
If using the SOCKET connector: network access to the target TCP/IP device
Windows, Linux, or macOS
Java 21 — required only when running from the distribution archive; the native install package bundles its own Java runtime

Installation

Native install packages for Windows, macOS, and Linux are available from the Downloads page and are the preferred installation method. The installer creates the application directory, copies all configuration templates, and handles the Java runtime dependency automatically.

Alternatively, a distribution archive can be extracted to a suitable directory, for example:

C:\Commander4j\Middleware4j\          (Windows)
/opt/commander4j/middleware4j/        (Linux)

The extracted directory contains:

c4jMiddleware.jar
Middleware_Service.exe     (Windows — service launcher)
Middleware_GUI.exe         (Windows — desktop GUI launcher)
Encrypt_String.exe         (Windows — utility to encrypt passwords)
start.cmd                  (Windows — fallback start script)
start.sh                   (Linux/macOS — start script)
xml/config/
xslt/
interface/
logs/
samples/

Configuration Before First Run

1. Maps

Edit xml/config/config.xml to define the transformation maps. Each map specifies one input connector, one or more output connectors, and optionally an XSLT stylesheet. See Maps for the full configuration reference.

2. XSLT Stylesheets

Place any XSLT stylesheets used by your maps in the xslt/ directory. A library of over 60 sample stylesheets is included covering common integration scenarios with SAP, Sage, Tropos, B2MML, and others.

3. Email Notifications (Optional)

Edit xml/config/email.xml with your SMTP server details and recipient addresses for error notifications.

4. Password Encryption

Any passwords stored in configuration files (SMTP, database connections) must be AES-encrypted. Use the included Encrypt_String.exe utility (Windows) to generate encrypted values. On Linux/macOS, use the equivalent utility from the Commander4j installation.

Installing as a Windows Service

The native install package includes Middleware_Service.exe, a service-mode launcher built with install4j. This executable manages the Windows service directly — no additional wrapper (such as WinSW) is required.

All service commands must be run from an elevated command prompt (Run as Administrator).

The default Windows service name is Middleware Service (the launcher name defined in the installer). You can specify a different name as an optional second parameter — useful if you need to run multiple instances on the same machine. If a custom name is used at install time, that same name must be passed to every subsequent command.

Command	Effect
`Middleware_Service.exe /install`	Register as Middleware Service with automatic startup on boot
`Middleware_Service.exe /install "My Middleware"`	Register with a custom service name
`Middleware_Service.exe /install-demand`	Register with manual startup only
`Middleware_Service.exe /start`	Start the service
`Middleware_Service.exe /stop`	Stop the service (waits for graceful shutdown)
`Middleware_Service.exe /restart`	Restart the service
`Middleware_Service.exe /status`	Query status (exit code: 0 = running, 3 = stopped)
`Middleware_Service.exe /uninstall`	Remove the service registration

If a custom service name was used at install time, append it to all subsequent commands:

Middleware_Service.exe /start "My Middleware"
Middleware_Service.exe /stop "My Middleware"
Middleware_Service.exe /uninstall "My Middleware"

Once installed, the service also appears in the Windows Services management console (services.msc).

Testing Before Installing as a Service

Before committing to service installation, run Middleware4j in desktop GUI mode using:

Middleware_GUI.exe

This launches a desktop window showing all configured maps, their current status, and real-time message counts. Use this mode to confirm that maps are reading from the correct input directories and that XSLT transformations produce the expected output. Once satisfied, switch to service mode for production deployment.

Starting on Linux / macOS

Use the provided shell script:

./start.sh

The mode (GUI or Service) is passed as an argument by the script. The process runs in the foreground. For production deployment, use systemd, launchd, or nohup to manage it as a background process.

Verifying the Installation

After starting Middleware4j:

Check logs/ for startup messages confirming that each map thread has initialised.
Place a test input file in the input directory of one of the configured maps.
Confirm the file is consumed and the expected output appears in the output directory.
Check interface/log/ for the message transaction record.

Log Files

All activity is written to the Log4j log file in the logs/ directory. Log rotation and retention are configured in xml/config/log4j2.xml.

@@ Line 1: / Line 1: @@
-The application should be downloaded from [[Downloads]]
+This page covers deploying Middleware4j on a server or integration host.
-You will find versions for Windows (32 and 64 bit), MacOS and Linux. The screens below show the Windows installation.
+== Requirements ==
-[[file:middleware00.png|400px]]
+* Network access to any input or output directories defined in the map configuration (local paths, UNC shares, or mounted network drives)
+* If using the EMAIL connector: network access to an SMTP server
+* If using the SOCKET connector: network access to the target TCP/IP device
+* Windows, Linux, or macOS
+* Java 21 — required only when running from the distribution archive; the native install package bundles its own Java runtime
-Windows will ask you to confirm that you want to install the software. Click Yes if you want to proceed.
+== Installation ==
-[[file:middleware01.png|400px]]
+Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method. The installer creates the application directory, copies all configuration templates, and handles the Java runtime dependency automatically.
-The installer will load.....
+Alternatively, a distribution archive can be extracted to a suitable directory, for example:
-[[file:middleware02.png|400px]]
+ C:\Commander4j\Middleware4j\          (Windows)
+ /opt/commander4j/middleware4j/        (Linux)
-Click on Next to begin the install.
+The extracted directory contains:
-[[file:middleware03.png|400px]]
+ c4jMiddleware.jar
+ Middleware_Service.exe     (Windows — service launcher)
+ Middleware_GUI.exe         (Windows — desktop GUI launcher)
+ Encrypt_String.exe         (Windows — utility to encrypt passwords)
+ start.cmd                  (Windows — fallback start script)
+ start.sh                   (Linux/macOS — start script)
+ xml/config/
+ xslt/
+ interface/
+ logs/
+ samples/
-The licence is displayed for you to read. If you are happy with it then click Agree.
+== Configuration Before First Run ==
-[[file:middleware04.png|400px]]
+=== 1. Maps ===
-The default installation path is shown. I recommend not installing into the Windows Program Files folders as those folders will default to read-only after the install and this will cause issues with message processing and log files.
+Edit <code>xml/config/config.xml</code> to define the transformation maps. Each map specifies one input connector, one or more output connectors, and optionally an XSLT stylesheet. See [[Maps]] for the full configuration reference.
-[[file:middleware05.png|700px]]
+=== 2. XSLT Stylesheets ===
-The install progress is displayed.
-[[file:middleware06.png|700px]]
+Place any XSLT stylesheets used by your maps in the <code>xslt/</code> directory. A library of over 60 sample stylesheets is included covering common integration scenarios with SAP, Sage, Tropos, B2MML, and others.
-This message will be displayed when the install is complete.
-At this point you can run the [[Middleware GUI]] application which is just a standard visual status display.
+=== 3. Email Notifications (Optional) ===
-However the middlware application is intended to be an always on backgroud task which just processes messages without any interaction.
+Edit <code>xml/config/email.xml</code> with your SMTP server details and recipient addresses for error notifications.
-To configure middlware to run as a service on a Windows computer use the following steps.
+=== 4. Password Encryption ===
-[[file:middleware_service0.png|700px]]
+Any passwords stored in configuration files (SMTP, database connections) must be AES-encrypted. Use the included <code>Encrypt_String.exe</code> utility (Windows) to generate encrypted values. On Linux/macOS, use the equivalent utility from the Commander4j installation.
-In order to install a windows service you need to run a command from the command prompt with admin permissions. This is a windows requirement.
+== Installing as a Windows Service ==
-[[file:middleware_service1.png|700px]]
+The native install package includes <code>Middleware_Service.exe</code>, a service-mode launcher built with install4j. This executable manages the Windows service directly — no additional wrapper (such as WinSW) is required.
-Windows will ask you if you are sure you want to open the command prompt with admin rights.
+All service commands must be run from an elevated command prompt (Run as Administrator).
-[[file:middleware_service2.png|700px]]
+The default Windows service name is '''Middleware Service''' (the launcher name defined in the installer). You can specify a different name as an optional second parameter — useful if you need to run multiple instances on the same machine. If a custom name is used at install time, that same name must be passed to every subsequent command.
-When the command prompt has opened you need to change into the folder where you installed the application. Then run the command shown above.
+{| class="wikitable"
+|-
+! Command !! Effect
+|-
+| <code>Middleware_Service.exe /install</code> || Register as '''Middleware Service''' with automatic startup on boot
+|-
+| <code>Middleware_Service.exe /install "My Middleware"</code> || Register with a custom service name
+|-
+| <code>Middleware_Service.exe /install-demand</code> || Register with manual startup only
+|-
+| <code>Middleware_Service.exe /start</code> || Start the service
+|-
+| <code>Middleware_Service.exe /stop</code> || Stop the service (waits for graceful shutdown)
+|-
+| <code>Middleware_Service.exe /restart</code> || Restart the service
+|-
+| <code>Middleware_Service.exe /status</code> || Query status (exit code: 0 = running, 3 = stopped)
+|-
+| <code>Middleware_Service.exe /uninstall</code> || Remove the service registration
+|}
-[[file:middleware_service3.png|700px]]
+If a custom service name was used at install time, append it to all subsequent commands:
-By default the account which a newly created service runs under is "System" which won't allow the program to connect to things like network shares. If you want the middleware to be able to collect and process files from network shares you will need to amend the service to run under a regular windows account - possibly a domain account. The account to use is your choice and depends on the folder/share/file permissions that you want the middleware to access. See the next screen for information on how to assign a specific account to the service.
+ Middleware_Service.exe /start "My Middleware"
+ Middleware_Service.exe /stop "My Middleware"
+ Middleware_Service.exe /uninstall "My Middleware"
-[[file:middleware_service4.png|700px]]
+Once installed, the service also appears in the Windows Services management console (<code>services.msc</code>).
+=== Testing Before Installing as a Service ===
+Before committing to service installation, run Middleware4j in desktop GUI mode using:
+ Middleware_GUI.exe
+This launches a desktop window showing all configured maps, their current status, and real-time message counts. Use this mode to confirm that maps are reading from the correct input directories and that XSLT transformations produce the expected output. Once satisfied, switch to service mode for production deployment.
+== Starting on Linux / macOS ==
+Use the provided shell script:
+ ./start.sh
+The mode (GUI or Service) is passed as an argument by the script. The process runs in the foreground. For production deployment, use systemd, launchd, or nohup to manage it as a background process.
+== Verifying the Installation ==
+After starting Middleware4j:
+# Check <code>logs/</code> for startup messages confirming that each map thread has initialised.
+# Place a test input file in the input directory of one of the configured maps.
+# Confirm the file is consumed and the expected output appears in the output directory.
+# Check <code>interface/log/</code> for the message transaction record.
+== Log Files ==
+All activity is written to the Log4j log file in the <code>logs/</code> directory. Log rotation and retention are configured in <code>xml/config/log4j2.xml</code>.
+See also: [[Overview_Middleware4j]], [[Maps]], [[Connectors]]
+[[Category:Middleware4j]]