Setting up the Worker SDK in Java
Requirements
Follow the SpatialOS tools installation guide (Windows / macOS / Linux). This is a prerequisite for using the Worker SDK.
Oracle’s JDK
1.8
or later (see the OS-specific guides below).
(Windows only) Visual C++ Redistributable for Visual Studio 2015, required for running workers locally.
(if using generated build scripts) Gradle
2.14
or later.- Please note that the Gradle Wrapper is not supported by provided build scripts.
- We’ve tested against Gradle version
2.14
, but later versions are expected to work too. To install it:- macOS:
brew install gradle
- Windows:
choco install --yes gradle
- macOS:
Packages
You can obtain packages through worker packages,
our package management framework. You can specify these packages in a spatialos_worker_packages.json
if
using the spatial build system, or, if you’re using the
flexible project layout, you can download them manually by running
spatial package get worker_sdk <package_name> <version> <destination zip>
(for example: spatial package get worker_sdk java 13.6.2 java.zip
).
The Worker SDK in Java is a combination of two components: a JAR file containing cross platform Java
.class
files called java-worker-sdk.jar
and some native code in separate “native” JAR files. The
Java code then calls into the native library via JNI.
The tables below list all the packages you can retrieve, relevant to the Worker SDK for Java:
Setting up a worker using the SpatialOS build system
To add a Java worker to your project:
- Create a directory under
workers/
of your SpatialOS project (for example,workers/java
). Create a worker configuration file file (for example,
workers/java/spatialos.MyJavaWorker.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.