Introduction

Gradle plugin for wrapping java application as a windows service. The plugin uses Apache Commons Daemon Procrun for creation of service executables.

Quick start

To create a windows service application you need to go through several simple steps:

1. Create a class with the appropriate method:

public class MyService {

  public static void main(String[] args) {
    String command = "start";
    if (args.length > 0) {
      command = args[0];
    }
    if ("start".equals(command)) {
      // process service start function
    } else {
      // process service stop function
    }
  }

}

2. Include the plugin:

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "gradle.plugin.com.github.alexeylisyutenko:windows-service-plugin:1.1.0"
  }
}

apply plugin: "com.github.alexeylisyutenko.windows-service-plugin"

The same script snippet for new, incubating, plugin mechanism introduced in Gradle 2.1:

plugins {
  id "com.github.alexeylisyutenko.windows-service-plugin" version "1.1.0"
}

3. Configure the plugin:

windowsService {
  architecture = 'amd64'
  displayName = 'TestService'
  description = 'Service generated with using gradle plugin'   
  startClass = 'MyService'
  startMethod = 'main'
  startParams = 'start'
  stopClass = 'MyService'
  stopMethod = 'main'
  stopParams = 'stop'
  startup = 'auto'
}

4. Run createWindowsService gradle task to create a windows service distribution.

That's all you need to do to create a simple windows service.

In ${project.buildDir}/windows-service directory you will find service executables, batch scripts for installation/uninstallation of the service and all runtime libraries. To install the service run <project-name>-install.bat and if you want to uninstall the service run <project-name>-uninstall.bat. To start and stop the service use <project-name>w.exe executable.

Note that the method handling service start should create and start a separate thread to carry out the processing, and then return. The main method is called from different threads when you start and stop the service.

Tasks

There is only one main task:

• createWindowsService - Task which generates windows service executables and creates batch scripts for installation/uninstallation. With defalut settings this creates the executable under ${project.buildDir}/windows-service and puts all runtime libraries into the lib subfolder.

Configuration

The configuration virtually follows of the Apache Commons Daemon Procrun command line parameters.

How to include

Please see the Gradle Plugin Portal for instructions on including this plugin in your project.

How to configure

The plugin defines the following extension properties in the windowsService closure:

Overriding the default classpath

By default, the plugin's classpath consists of jar task outputs and all runtime dependencies. When you execute the createWindowsService task, all jars which are in the classpath will be copied to ${project.buildDir}/windows-service/lib directory and will be used in an install script. For majority of applications this works perfectly fine, but there could be some situations when you might need to change this behavior.

The following example shows how to use this plugin hand in hand with the shadow plugin, which combines dependency classes and resources into a single output Jar:

windowsService {
	// Setup the main windows service parameters.
    ...
    
    // Set shadowJar task outputs as the plugin's classpath.
    overridingClasspath = project.files(project.tasks.shadowJar.outputs)
}

// Add shadowJar dependency. 
createWindowsService.dependsOn shadowJar

Now, when you execute createWindowsService task, you'll get only one jar file in the output lib directory and in the install script.

The overridingClasspath property is a Gradle's FileCollection, which is simply a set of files. A natural way to obtain a FileCollection instance is to use the Project.files(java.lang.Object[]) method. You can pass this method any number of objects, which are then converted into a set of File objects. You can pass collections, iterables, maps and arrays to the files() method. These are flattened and the contents converted to File instances.

Version

See VERSION.md for more information.