Setting up a Java worker

To add a Java worker to your project, create a directory under workers/ of your SpatialOS project (for example workers/java), and create a worker configuration file file, e.g. workers/java/spatialos.ExampleJavaWorker.worker.json, with the following contents:

{
  "build": {
    "tasks_filename": "spatialos.java.build.json",
    "generated_build_scripts_type": "java"
  },
  "bridge": {
    "worker_attribute_set": {
      "attributes": [
        "new_worker_attribute"
      ]
    },
    "entity_interest": {
      "range_entity_interest": {
        "radius": 2
      }
    },
    "streaming_query": [],
    "component_delivery": {
      "default": "RELIABLE_ORDERED",
      "checkout_all_initially": true
    }
  }
}

The default build for the Java worker sets up a project that should get you started quickly, lets you customize the build, and is upgradeable between SpatialOS versions. However, if you need to customize it further, you can turn off the automatic build script generation.

The default Java worker project structure is the following:

+-- workers/<your-directory-name>
    +-- worker-sdk          // Auto-generated worker SDK project and schema-generated code.
    |   \-- build.gradle
    |-- worker              // Your worker project.
    |   |-- src/main/java   // Default root source directory for your worker.
    |   \-- build.gradle    // Your project's build configuration.
    |-- build.gradle        // Auto-generated main project build file
    |-- settings.gradle     // Gradle settings file
    \-- spatialos.<your_worker_type>.worker.json

The worker project is controlled by you, and should provide you with enough flexibility without the need to turn off automatically generated build scripts. The worker project depends on worker-sdk project, which includes the worker SDK dependencies and the schema-generated code. The top-level build.gradle builds self-contained assemblies required by SpatialOS in order to run your worker in the cloud.

To create the worker Gradle project, simply create a directory named worker, and copy the example Java build.gradle file into it.

You can now define your main class in the worker project’s default sources location: src/main/java. For example, in worker/src/main/java/example/MyJavaWorker.java:

package example;
public class MyJavaWorker {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

Specify the main class, project name and subprojects in the settings.gradle configuration file:

include ':worker-sdk'
include ':worker'

rootProject.name = "JavaDocsWorker"
gradle.ext.mainClass = 'docs.JavaDocsWorker'

You can also use the example Java settings.gradle file.

You should now be able to build your worker using spatial worker build or spatial worker build <your_worker_type>. This will generate all the remaining project files, including the worker-sdk subproject.

You will need to add the worker to your SpatialOS application. Assemblies produced by spatial worker build contain a jar file with the same name as the rootProject.name set in settings.gradle. For example, if the project’s settings.gradle contains rootProject.name = "ExampleJavaWorker", it will produce an assembly containing ExampleJavaWorker.jar. You should launch them using java -jar ExampleJavaWorker.jar, or configure them to be launched by SpatialOS as managed workers.

You can read more about the build setup in the next section.