Interoperability research notes

These notes record the interface facts that Java Service Steward relies on to read wrapper.conf-style configuration files, honor the same command-line conventions, and write logs in the same layout as the Java Service Wrapper Community Edition. They describe interfaces and observable behavior only. How those facts were obtained, and the rules that apply to future research, are described in provenance.md.

Command line and service registration

• Installing a Windows service stores the executable path, a hidden -s command, the selected configuration file, and any command-line property overrides in the service ImagePath. An in-place executable replacement must therefore accept -s.
• The configuration file argument is optional and defaults to wrapper.conf. Relative configuration paths, and relative paths inside the configuration, resolve from the directory containing the executable.
• Arguments following -- are passed to the Java application unchanged.

Configuration directives and property families

• The directives are #encoding, #include, #include.required and #include.debug. #encoding is only honored on the first line.
• Numbered properties (wrapper.java.additional.<n>, wrapper.java.classpath.<n>, wrapper.app.parameter.<n>, filters, wrapper.on_exit.<code>, service dependencies) use contiguous indexes starting at 1. An explicitly empty entry preserves later indexes but is not emitted as an empty JVM argument. wrapper.ignore_sequence_gaps=true reads every positive index.
• set.NAME=value defines an environment variable for the child process and for %NAME% expansion inside the file; set.default.NAME only defines it when it is not already set.
• Command-line name=value arguments override file properties.

Local control protocol

• The default control backend is TCP on IPv4 loopback. The wrapper listens on a port taken from the 32000-32999 range by default; the JVM side connects from the 31000-31999 range by default. Fixed ports can be configured.
• Each packet is one type byte, a UTF-8 payload, and a terminating NUL byte.
• The first JVM packet carries a one-time key generated by the supervisor and passed to the JVM as a system property. After authentication, the supervisor sends the minimum log level, the resolved log-file path, the configuration properties, and the start command. Runtime traffic covers start and stop completion, restart requests, pings, log messages, service controls, pause/resume, and garbage-collection requests.
• When an authenticated connection is lost, the JVM does not try to resume the same session. It exits so that the supervisor can launch a fresh instance and resynchronize.

The exact packet codes and system property names are an internal contract between wrapper.exe and wrapper.jar of the same release; see compatibility.md.

Process, PID and ID files

• The JVM is created in its own Windows process group. Service-mode thread dumps need a hidden console and deliver CTRL_BREAK to that group.
• wrapper.pidfile and wrapper.java.pidfile contain the decimal process identifier followed by CRLF and are removed when the owning process ends.
• wrapper.java.idfile contains the decimal JVM invocation number followed by CRLF and is rewritten for every JVM launch.

Log format

• The default log-file layout is LPTM: a six-character level column, an eight-character source column, a local YYYY/MM/DD HH:mm:ss timestamp, and the message, joined by literal ` | ` separators. Records end in CRLF.
• The console default is PM.
• Roll modes are NONE, SIZE, WRAPPER, JVM, SIZE_OR_WRAPPER and SIZE_OR_JVM; archives are numbered wrapper.log.1 (newest) upward, and a maxfiles value of zero keeps an unlimited history.

Diagnostics

• The -d command, wrapper.thread_dump_control_code, and the filter action DUMP all request a thread dump; none of them produces a heap dump. Automatic heap dumps on out-of-memory errors are HotSpot options passed as ordinary JVM arguments.
• -Xrs reduces the JVM’s use of operating-system signals and disables the CTRL_BREAK thread-dump path on Windows. Java Service Steward therefore falls back to jcmd Thread.print when -Xrs is present, and implements the on-demand --heapdump command with jcmd GC.heap_dump. Both are project code; see diagnostics.md.

Java version considerations

• JDK 24 and later warn when code in an unnamed module loads a JNI library without native access being enabled explicitly. The project’s bridge never loads a native library, so the warning does not apply to it.
• JDK 24 permanently disabled the Security Manager. The bridge does not require or install one.
• The default character encoding differs between older Windows JDKs and modern JDKs. Tests include non-ASCII configuration values and application output.

Java 8, 21 and 25 are separate test targets; a successful start on one is not evidence for another. The bridge is compiled to Java 8 bytecode and depends on java.base only.

Public documentation consulted

The public property references used for semantics include exit-code actions, output filters, log-file roll modes, wrapper PID files, Java PID files, Java invocation-ID files, mode-specific startup delays, Windows console titles, thread dumps before forced JVM termination, the thread-dump control code, and the list of actions. Only features that belong to the Community Edition feature set were selected.

Legal and provenance questions are covered in provenance.md.