LabelServer4j Example User Interface

LabelServer4j is a headless background service — it has no graphical user interface. All interaction with the service is through configuration files, log files, and (on Windows) the Windows Services control panel.

Starting LabelServer4j

Windows — Running as a Service

The native install package includes LabelServer.exe, a service-mode launcher that manages the Windows service directly. All commands must be run from an elevated command prompt (Run as Administrator).

The default service name is LabelService. A custom name can be passed as an optional second parameter — if used, the same name must be supplied to all subsequent commands.

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

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

Windows — Testing in a Console Window

Before installing as a service, use the debug launcher to run LabelServer4j with all output visible in the console:

LabelServerDebug.exe

This runs the same application code and is the most convenient way to verify that labellers connect and that the configuration is correct before committing to service deployment.

Linux / macOS

Start from the terminal using the provided shell script:

./start_labeller.sh

Or directly:

java -cp ./LabelServer.jar:./lib/devonly/i4jruntime.jar com.commander4j.labeller.Service

The process runs in the foreground. Use a process manager (systemd, launchd, or nohup) for production deployment.

Monitoring

Since there is no GUI, the primary monitoring tool is the log file:

logs/c4jLabelServer.log

The log records every event in detail:

Service startup and configuration loading
Each labeller thread starting
Every CSV file detected and processed
Every command sent to a printer and every response received
File operations (upload, download, backup, delete)
Errors and exceptions with full context

Log files rotate at 10 MB and are retained for 14 days.

What to Look For

Situation	What to check in the log
Label not printing	Look for the CSV filename being detected; if absent, check the input path in labellers.xml
Printer not responding	Look for TCP connection errors or timeout messages for that labeller's IP and port
Wrong data on label	Check the variable substitution log lines to see what values were sent
Script error	Look for the script line number and command that caused the failure
File stuck in input directory	File renamed to `.in` means the script is running or failed — check for a `.error` file

Configuration Changes

To change a labeller's IP address, port, command script, or input path, edit the relevant labellers.xml file and restart the service. Changes to configuration files are not picked up at runtime.

To switch site, edit xml/config/config.xml and change the site id attribute, then restart.

Thread Architecture

When running, LabelServer4j maintains the following threads:

One main service thread (lifecycle management)
One server thread (configuration and orchestration)
Per enabled labeller: one labeller thread, one TCP receive thread, one TCP transmit thread

The thread count grows with the number of configured printers. A site with six printers typically runs around 20 threads in total.

Graceful Shutdown

Sending a termination signal (Ctrl+C on Linux/macOS, or stopping the Windows service) triggers the shutdown hook. LabelServer4j signals all labeller threads to stop, waits for any in-progress print jobs to complete, then exits cleanly.