Windows JAR Service Manager

Gestor de servicios JAR para Windows

A simple, secure, and reliable Windows wrapper for running Java JAR applications as native Windows services. Un wrapper de Windows sencillo, seguro y fiable para ejecutar aplicaciones Java JAR como servicios nativos de Windows.

The project also provides a desktop application for monitoring and controlling each installed Java service. El proyecto también proporciona una aplicación de escritorio para supervisar y controlar cada servicio Java instalado.

Project purpose

Objetivo del proyecto

Java applications can be started on Windows with java.exe -jar application.jar, but that command does not create a native Windows service. Las aplicaciones Java pueden iniciarse en Windows con java.exe -jar application.jar, pero ese comando no crea un servicio nativo de Windows.

The Windows Service Control Manager requires a compatible service executable that handles service start, stop, shutdown, and status notifications. El Administrador de control de servicios de Windows necesita un ejecutable compatible que gestione el inicio, la parada, el apagado y las notificaciones de estado del servicio.

Windows JAR Service Manager will provide that native integration while keeping the Java application unchanged. Windows JAR Service Manager proporcionará esa integración nativa manteniendo la aplicación Java sin modificaciones.

The first real application used to develop and validate the wrapper is calculos-ritmo-jc. La primera aplicación real utilizada para desarrollar y validar el wrapper es calculos-ritmo-jc.

Reference application: Aplicación de referencia:

https://github.com/suzdalenko-dev/calculos-ritmo-jc

---

Main goals

Objetivos principales

• Run an executable Java JAR as a native Windows service. Ejecutar un JAR de Java como servicio nativo de Windows.

• Start the Java application automatically when Windows starts. Iniciar automáticamente la aplicación Java cuando arranca Windows.

• Run the Java application even when no user is logged in. Ejecutar la aplicación Java aunque ningún usuario haya iniciado sesión.

• Start, stop, and restart the Java application safely. Iniciar, detener y reiniciar la aplicación Java de forma segura.

• Monitor the Java process and its HTTP heartbeat. Supervisar el proceso Java y su heartbeat HTTP.

• Capture the standard output and standard error streams. Capturar los flujos de salida estándar y error estándar.

• Store and rotate application logs. Guardar y rotar los logs de la aplicación.

• Detect unexpected Java process termination. Detectar la finalización inesperada del proceso Java.

• Restart failed applications with controlled retry delays. Reiniciar aplicaciones con errores utilizando esperas controladas entre intentos.

• Prevent orphaned Java processes. Evitar procesos Java huérfanos.

• Provide a Windows desktop interface for local administration. Proporcionar una interfaz de escritorio para la administración local.

• Provide a simple Windows installer and uninstaller. Proporcionar un instalador y desinstalador sencillo para Windows.

• Support a bundled or separately installed Java runtime. Permitir utilizar un runtime de Java incluido o instalado por separado.

---

Non-goals

Objetivos excluidos

This project will not modify or replace the internal code of the Java application. Este proyecto no modificará ni reemplazará el código interno de la aplicación Java.

This project will not act as a Java application server. Este proyecto no actuará como servidor de aplicaciones Java.

This project will not manage Linux services. Este proyecto no gestionará servicios Linux.

Linux systems can run Java applications directly with systemd. Los sistemas Linux pueden ejecutar aplicaciones Java directamente mediante systemd.

This project is not a container orchestrator or a replacement for Kubernetes. Este proyecto no es un orquestador de contenedores ni un sustituto de Kubernetes.

This project is initially designed for local Windows administration, not remote Internet administration. Este proyecto está diseñado inicialmente para administración local de Windows, no para administración remota por Internet.

---

Design principles

Principios de diseño

One service instance will control one Java JAR process. Una instancia del servicio controlará un proceso Java JAR.

Different Java applications will be isolated in separate Windows service instances. Las diferentes aplicaciones Java estarán aisladas en instancias separadas del servicio de Windows.

The Windows service will own and supervise the Java process. El servicio de Windows será propietario y supervisor del proceso Java.

The desktop application will never be responsible for keeping Java alive. La aplicación de escritorio nunca será responsable de mantener Java en ejecución.

Closing the desktop window will not stop the Windows service or the Java application. Cerrar la ventana de escritorio no detendrá el servicio de Windows ni la aplicación Java.

The Java executable, JAR path, arguments, working directory, and heartbeat URL will be configurable. El ejecutable de Java, la ruta del JAR, los argumentos, el directorio de trabajo y la URL del heartbeat serán configurables.

All important paths will be absolute and validated before starting Java. Todas las rutas importantes serán absolutas y se validarán antes de iniciar Java.

The wrapper will start Java directly without using cmd.exe or shell scripts. El wrapper iniciará Java directamente sin utilizar cmd.exe ni scripts de shell.

---

Planned architecture

Arquitectura prevista

The solution contains three main projects. La solución contiene tres proyectos principales.

JarServiceManager.Core

JarServiceManager.Core

This project contains shared models, configuration, validation, service states, and contracts. Este proyecto contiene modelos compartidos, configuración, validación, estados del servicio y contratos.

It should not contain the desktop interface or the Windows service execution loop. No debe contener la interfaz de escritorio ni el bucle de ejecución del servicio de Windows.

JarServiceManager.ServiceHost

JarServiceManager.ServiceHost

This project is the native Windows service host. Este proyecto es el host nativo del servicio de Windows.

It starts, monitors, and stops the Java process. Inicia, supervisa y detiene el proceso Java.

It captures Java output and performs heartbeat checks. Captura la salida de Java y realiza comprobaciones del heartbeat.

It continues running independently from the desktop application. Continúa ejecutándose independientemente de la aplicación de escritorio.

JarServiceManager.Desktop

JarServiceManager.Desktop

This project is the Windows WPF administration interface. Este proyecto es la interfaz de administración WPF para Windows.

It displays service status, Java status, uptime, process ID, health, and recent logs. Muestra el estado del servicio, el estado de Java, el tiempo activo, el identificador del proceso, la salud y los logs recientes.

It sends start, stop, and restart requests to the Windows service. Envía solicitudes de inicio, parada y reinicio al servicio de Windows.

It does not start or own the Java process directly. No inicia ni controla directamente el proceso Java.

Installer

Instalador

A future installer project will install the service, desktop application, configuration, shortcuts, and optional Java runtime. Un futuro proyecto de instalación instalará el servicio, la aplicación de escritorio, la configuración, los accesos directos y el runtime de Java opcional.

The installer will also support clean upgrades and uninstallation. El instalador también permitirá actualizaciones limpias y desinstalación.

---

Runtime architecture

Arquitectura de ejecución

The desktop application communicates with the Windows service. La aplicación de escritorio se comunica con el servicio de Windows.

The Windows service controls java.exe. El servicio de Windows controla java.exe.

The Java process executes the configured JAR. El proceso Java ejecuta el JAR configurado.

The Windows service periodically checks the configured heartbeat endpoint. El servicio de Windows comprueba periódicamente el endpoint de heartbeat configurado.

WPF Desktop -> Windows Service -> java.exe -> application.jar
Escritorio WPF -> Servicio Windows -> java.exe -> application.jar

Windows Service -> HTTP heartbeat endpoint
Servicio Windows -> Endpoint HTTP de heartbeat

---

Planned service states

Estados previstos del servicio

• Stopped: the Java process is not running. Stopped: el proceso Java no se está ejecutando.

• Starting: Java has started, but the application is not ready yet. Starting: Java se ha iniciado, pero la aplicación todavía no está preparada.

• Running: Java is running and the heartbeat reports UP. Running: Java se está ejecutando y el heartbeat devuelve UP.

• Unhealthy: Java is running, but the heartbeat is failing. Unhealthy: Java se está ejecutando, pero el heartbeat está fallando.

• Stopping: an orderly shutdown is in progress. Stopping: se está realizando una parada ordenada.

• Failed: Java could not start or stopped unexpectedly. Failed: Java no pudo iniciarse o se detuvo inesperadamente.

---

Java process supervision

Supervisión del proceso Java

The service will launch Java by using the .NET process API. El servicio iniciará Java mediante la API de procesos de .NET.

The service will retain the process handle and process identifier. El servicio conservará el identificador y el control del proceso.

The service will redirect and asynchronously read stdout and stderr. El servicio redirigirá y leerá de forma asíncrona stdout y stderr.

The service will detect the Java exit code. El servicio detectará el código de salida de Java.

A Windows Job Object will be used to control the complete Java process tree. Se utilizará un Job Object de Windows para controlar todo el árbol de procesos Java.

If Java does not stop within the configured timeout, the complete process tree will be terminated. Si Java no se detiene dentro del tiempo configurado, se finalizará todo el árbol de procesos.

---

Heartbeat monitoring

Supervisión del heartbeat

Heartbeat monitoring will be optional and configurable for each service instance. La supervisión del heartbeat será opcional y configurable para cada instancia del servicio.

When enabled, the service will wait for a successful heartbeat before reporting the Java application as running. Cuando esté activado, el servicio esperará un heartbeat correcto antes de indicar que la aplicación Java está funcionando.

The heartbeat URL, interval, timeout, and failure threshold will be configurable. La URL, el intervalo, el tiempo máximo y el umbral de fallos del heartbeat serán configurables.

A single failed request will not immediately restart Java. Una única solicitud fallida no reiniciará Java inmediatamente.

Several consecutive failures will change the application state to Unhealthy. Varios fallos consecutivos cambiarán el estado de la aplicación a Unhealthy.

Automatic restart behavior will use controlled delays to avoid restart loops. El reinicio automático utilizará esperas controladas para evitar bucles de reinicio.

---

Reference heartbeat

Heartbeat de referencia

The initial reference application provides the following endpoint. La aplicación de referencia inicial proporciona el siguiente endpoint.

GET http://192.168.1.98:8080/api/heartbeat/java/

A healthy response has HTTP status 200 and contains res.status with the value UP. Una respuesta saludable tiene el estado HTTP 200 y contiene res.status con el valor UP.

{
  "res": {
    "status": "UP",
    "application": "ritm",
    "timestamp": "2026-08-20T11:30:00Z",
    "uptimeSeconds": 120
  }
}

The reference URL is only an example and will not be hard-coded in the wrapper. La URL de referencia es únicamente un ejemplo y no estará escrita de forma fija en el wrapper.

---

Desktop application

Aplicación de escritorio

The desktop application will show the Windows service status. La aplicación de escritorio mostrará el estado del servicio de Windows.

It will show whether the Java process exists. Mostrará si existe el proceso Java.

It will show the Java process identifier and uptime. Mostrará el identificador del proceso Java y el tiempo activo.

It will show the last successful heartbeat and consecutive failures. Mostrará el último heartbeat correcto y los fallos consecutivos.

It will provide start, stop, and restart buttons. Proporcionará botones para iniciar, detener y reiniciar.

It will display recent application logs. Mostrará los logs recientes de la aplicación.

Administrative operations will require the appropriate Windows permissions. Las operaciones administrativas necesitarán los permisos correspondientes de Windows.

---

Planned installation layout

Estructura de instalación prevista

Program binaries should be stored under C:\Program Files. Los binarios del programa deben almacenarse dentro de C:\Program Files.

Configuration, state, and logs should be stored under C:\ProgramData. La configuración, el estado y los logs deben almacenarse dentro de C:\ProgramData.

C:\Program Files\JarServiceManager\
├── ServiceHost\
├── Desktop\
└── Runtime\

C:\ProgramData\JarServiceManager\
├── Instances\
├── Configuration\
├── State\
└── Logs\

Files under Program Files should not be writable by standard users. Los archivos dentro de Program Files no deben poder ser modificados por usuarios estándar.

Configuration files must have restricted Windows permissions. Los archivos de configuración deben tener permisos de Windows restringidos.

---

Security principles

Principios de seguridad

The service should run with the minimum privileges required by the Java application. El servicio debe ejecutarse con los privilegios mínimos necesarios para la aplicación Java.

The service should not run as LocalSystem unless it is strictly necessary. El servicio no debe ejecutarse como LocalSystem salvo que sea estrictamente necesario.

The Java executable and JAR paths must be validated before execution. Las rutas del ejecutable Java y del JAR deben validarse antes de la ejecución.

Command-line arguments must be passed without shell interpretation. Los argumentos de línea de comandos deben pasarse sin interpretación de shell.

The desktop application must not allow an unprivileged user to execute arbitrary commands as the service account. La aplicación de escritorio no debe permitir que un usuario sin privilegios ejecute comandos arbitrarios con la cuenta del servicio.

Passwords and database credentials must never be written to application logs. Las contraseñas y credenciales de bases de datos nunca deben escribirse en los logs de la aplicación.

Production executables and installers should eventually be digitally signed. Los ejecutables e instaladores de producción deberán firmarse digitalmente en el futuro.

---

Development roadmap

Hoja de ruta de desarrollo

Phase 1 — Project foundation

Fase 1 — Base del proyecto

• Create the .NET solution. Crear la solución .NET.

• Create the shared Core project. Crear el proyecto Core compartido.

• Create the Windows ServiceHost project. Crear el proyecto ServiceHost de Windows.

• Create the WPF Desktop project. Crear el proyecto de escritorio WPF.

• Define the initial architecture and project scope. Definir la arquitectura inicial y el alcance del proyecto.

• Add the bilingual project README. Añadir el README bilingüe del proyecto.

• Add the MIT license. Añadir la licencia MIT.

Phase 2 — Native Windows service

Fase 2 — Servicio nativo de Windows

• Add Windows Service hosting support. Añadir soporte para ejecutar como servicio de Windows.

• Configure the real Windows service name. Configurar el nombre real del servicio de Windows.

• Preserve console execution for development and debugging. Mantener la ejecución por consola para desarrollo y depuración.

• Verify installation, start, stop, and removal with the Windows Service Control Manager. Verificar la instalación, el inicio, la parada y la eliminación con el Administrador de servicios de Windows.

Phase 3 — Configuration

Fase 3 — Configuración

• Define the service configuration model. Definir el modelo de configuración del servicio.

• Add JSON configuration loading. Añadir la carga de configuración JSON.

• Validate Java, JAR, working directory, arguments, and heartbeat settings. Validar Java, el JAR, el directorio de trabajo, los argumentos y la configuración del heartbeat.

• Return clear configuration errors before starting Java. Devolver errores de configuración claros antes de iniciar Java.

Phase 4 — Java process lifecycle

Fase 4 — Ciclo de vida del proceso Java

• Start java.exe safely. Iniciar java.exe de forma segura.

• Capture stdout and stderr. Capturar stdout y stderr.

• Detect process termination and exit codes. Detectar la finalización del proceso y los códigos de salida.

• Implement an orderly shutdown. Implementar una parada ordenada.

• Add forced process-tree termination as a last resort. Añadir la finalización forzada del árbol de procesos como último recurso.

• Add Windows Job Object support. Añadir soporte para Job Objects de Windows.

Phase 5 — Health supervision and recovery

Fase 5 — Supervisión de salud y recuperación

• Implement HTTP heartbeat checks. Implementar comprobaciones HTTP del heartbeat.

• Implement startup timeout handling. Implementar el control del tiempo máximo de arranque.

• Implement consecutive failure counting. Implementar el recuento de fallos consecutivos.

• Implement controlled restart delays. Implementar esperas controladas entre reinicios.

• Prevent infinite restart loops. Evitar bucles infinitos de reinicio.

Phase 6 — Desktop interface

Fase 6 — Interfaz de escritorio

• Design the WPF status window. Diseñar la ventana de estado WPF.

• Display service and Java process states. Mostrar los estados del servicio y del proceso Java.

• Display heartbeat and uptime information. Mostrar la información del heartbeat y del tiempo activo.

• Display recent logs. Mostrar los logs recientes.

• Add start, stop, and restart actions. Añadir acciones de inicio, parada y reinicio.

• Implement secure communication between Desktop and ServiceHost. Implementar una comunicación segura entre Desktop y ServiceHost.

Phase 7 — Installer and release

Fase 7 — Instalador y publicación

• Create the Windows installer. Crear el instalador de Windows.

• Register and configure the Windows service during installation. Registrar y configurar el servicio de Windows durante la instalación.

• Create Start Menu shortcuts. Crear accesos directos en el menú Inicio.

• Support upgrades and uninstallation. Permitir actualizaciones y desinstalación.

• Publish a self-contained 64-bit Windows build. Publicar una compilación autocontenida para Windows de 64 bits.

• Test installation on a clean Windows computer. Probar la instalación en un equipo Windows limpio.

• Create the first stable release. Crear la primera versión estable.

---

Repository structure

Estructura del repositorio

windows-jar-service/
├── JarServiceManager.slnx
├── README.md
├── LICENSE
├── src/
│   ├── JarServiceManager.Core/
│   ├── JarServiceManager.ServiceHost/
│   └── JarServiceManager.Desktop/
└── learn/

The current learn directory contains development notes and will be reviewed later. El directorio learn actual contiene notas de desarrollo y se revisará más adelante.

Generated build directories must not be committed to the repository. Los directorios generados durante la compilación no deben subirse al repositorio.

---

Technology

Tecnología

The project is written in C#. El proyecto está escrito en C#.

The service and shared libraries target .NET 10. El servicio y las librerías compartidas utilizan .NET 10.

The desktop application uses Windows Presentation Foundation. La aplicación de escritorio utiliza Windows Presentation Foundation.

The initial supported platform is 64-bit Windows. La plataforma compatible inicial es Windows de 64 bits.

The production build will be published as a self-contained application. La compilación de producción se publicará como aplicación autocontenida.

---

Current build commands

Comandos de compilación actuales

Restore the solution dependencies. Restaurar las dependencias de la solución.

dotnet restore '.\JarServiceManager.slnx'

Build the complete solution. Compilar la solución completa.

dotnet build `
    '.\JarServiceManager.slnx' `
    --configuration Release

Run the desktop application. Ejecutar la aplicación de escritorio.

dotnet run `
    --project '.\src\JarServiceManager.Desktop\JarServiceManager.Desktop.csproj'

The ServiceHost is still a development template and does not yet run as a real Windows service. ServiceHost todavía es una plantilla de desarrollo y aún no funciona como un servicio real de Windows.

---

Development workflow

Flujo de desarrollo

The project will be developed in small, verifiable steps. El proyecto se desarrollará mediante pasos pequeños y verificables.

Each step must compile successfully before continuing. Cada paso debe compilar correctamente antes de continuar.

Each new feature must be tested manually before moving to the next phase. Cada nueva funcionalidad debe probarse manualmente antes de pasar a la fase siguiente.

Commits should contain one logical change and use descriptive messages. Los commits deben contener un cambio lógico y utilizar mensajes descriptivos.

Code identifiers and source-code comments should be written in English. Los identificadores y comentarios del código fuente deben escribirse en inglés.

The README will remain bilingual to support English learning. El README continuará siendo bilingüe para facilitar el aprendizaje del inglés.

---

License

Licencia

This project is licensed under the MIT License. Este proyecto se distribuye bajo la licencia MIT.

See the LICENSE file for the complete legal text. Consulta el archivo LICENSE para ver el texto jurídico completo.