Runtime Service: Application Startup and Native Self-Check

Technical reference for the Runtime service main application entry point. Details standard startup and the native self-check mode for validating data

Overview

The RuntimeApplication class is the main entry point for the Runtime service. It is a standard Spring Boot application responsible for bootstrapping the service, loading configuration, and enabling core functionalities.

The application is configured to:

Scan for and apply external configuration properties (@ConfigurationPropertiesScan).
Enable and execute scheduled tasks (@EnableScheduling).
Integrate a shared database connection pool health check for liveness monitoring (@Import(DbPoolHealthConfig.class)).

In addition to its primary role of starting the full service, RuntimeApplication includes a special pre-boot operational mode: a native self-check. This mode allows for targeted validation of a critical data transformation path without starting the full Spring application context, providing a fast-fail mechanism for verifying native image builds.

How it works

The application has two distinct operational modes determined by the command-line arguments provided at launch. The main method inspects arguments before deciding whether to start the full application or run the self-check.

flowchart TD
    A[Process Start] --> B{Argument matches<br/>NativeSelfCheck.FLAG?};
    B -- Yes --> C[Run In-Process<br/>JSON-to-SOAP Self-Check];
    C --> D[Process Exits with 0 (Success) or 1 (Failure)];
    B -- No --> E[Start Full Spring Application];
    E --> F[Runtime Service is Active];

Standard Startup

If no special flags are detected, the main method proceeds to call SpringApplication.run(RuntimeApplication.class, args). This initiates the standard Spring Boot startup sequence:

An application context is created.
All components, including controllers, services, and scheduled tasks, are initialized.
Configuration properties are bound.
The embedded web server starts, and the service begins accepting requests.

Native Self-Check Mode

If the application is launched with a specific command-line flag, it enters a self-check mode instead of starting the full service.

Trigger: The main method iterates through the command-line arguments and checks if any of them match the NativeSelfCheck.FLAG constant.
Execution: If the flag is found, the NativeSelfCheck.run() method is invoked. This method performs a JSON-to-SOAP data conversion entirely in-process. This check is self-contained and does not initialize the Spring context, connect to a database, or make any network calls.
Termination: After the check completes, the run() method calls System.exit. The process terminates immediately with an exit code of 0 for a successful conversion or 1 for a failure.

This mode is specifically designed to prove that the JAXP/DOM-based conversion path functions correctly within a compiled GraalVM native image.

Invoking the Native Self-Check

To run the application in self-check mode, pass the designated flag as a command-line argument when executing the application JAR.

NOTE

The source defines the flag via a constant, NativeSelfCheck.FLAG, but does not specify its string value. You must use the exact flag value defined for your build.

Example

The following command demonstrates how to invoke the self-check. Replace <FLAG_VALUE> with the actual value of the NativeSelfCheck.FLAG.

java -jar runtime-application.jar <FLAG_VALUE>

Expected Result:

On success: The process will execute silently and exit with a status code of 0.
On failure: The process will exit with a status code of 1.

Command-Line Arguments

The application's startup behavior can be modified with the following argument.

Name	Type	Default	Required	Description
`NativeSelfCheck.FLAG`	String	—	No	When present, triggers the native self-check mode. The application runs an in-process JSON-to-SOAP conversion and exits with status 0 (success) or 1 (failure) without starting the full service. The exact string value is not specified in this source.

Troubleshooting

Process Exits with Code 1

Condition: The application process terminates immediately after launch with an exit code of 1.
Cause: This indicates that the native self-check was invoked via its command-line flag and the internal JSON-to-SOAP conversion test failed.
Meaning: There is a potential issue with the native compilation of the core data transformation logic (JAXP/DOM). The critical path required for service operation is not functioning as expected in the native image environment.