Setup and installation

Setup and installation: Workder 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).

  1. Download and install the 64-bit JDK 8 for Windows. You’ll need to install the 1.8.0_65 version or newer.
    (If you're using Chocolatey, run choco install --yes jdk8.)

    Check it worked by running in a terminal: java -versionbr/> Expected output: java version "1.8.0_x"

  2. Add javac to your PATH by following these instructions. This binary is located in the bin directory inside the JDK installation directory.

    Check it worked by running in a terminal: javac -version
    Expected output: javac 1.8.0_x

  3. Set the JAVA_HOME system environment variable by following these instructions

These instructions assume you're using Bash.

  1. In a terminal, run: brew cask install java

    Check it worked by running: javac -version
    Expected output: javac 1.8.0_x

  2. Determine which configuration file to use: run `cd`, then `ls -a ~`
    • * If you have a .bash_profile, that's your configuration file.
    • * Otherwise, if you have a .bash_login, that's your configuration file.
    • * Otherwise, if you have a .profile, that's your configuration file.
    • * If you don't have any of these files, you can use .bash_profile (which you'll create in the next step).

  3. Set the JAVA_HOME system environment variable by running:
    echo "export JAVA_HOME=\$(/usr/libexec/java_home)" >> ~/your_config_file_here source ~/your_config_file_here

    Check it worked by running: echo $JAVA_HOME
    Expected output: /Library/Java/JavaVirtualMachines/jdk1.8.0_x.jdk/Contents/Home

  1. Download the 64-bit JDK for Linux. You'll need to install the 1.8.0_65 version or newer
  2. Add the /bin folder to your PATH.

    Check it worked by running: javac -version
    Expected output: javac 1.8.0_x

  3. Set the JAVA_HOME system environment variable by running:

    Check it worked by running: echo $JAVA_HOME
    Expected output: /bin

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:

Package name Arch Build type More information
java Any Java JAR Targeting Java 1.6+

Package name Arch Build type More information
java_native-dynamic-x86_64-win32 x86_64 Dynamic VS 2015 with multithreaded runtime library (`/MD`)

Package name Arch Build type More information
`java_native-dynamic-x86_64-macos` x86_64 Dynamic Xcode 10 targeting macOS 10.10+
(-mmacosx-version-min=10.10)

Package name Arch Build type More information
java_native-dynamic-x86_64-linux x86_64 Dynamic gcc 5.4.0 with libstdc++

Setting up a worker using the SpatialOS build system

If you're using the flexible project layout, you don't need to do this.

To add a Java worker to your project:

  1. Create a directory under workers/ of your SpatialOS project (for example, workers/java).
  2. 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/
    +-- 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..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 below into it.

apply plugin: 'java'

sourceCompatibility = 1.8
targetCompatibility = 1.8

repositories {
    maven { url "http://repo.maven.apache.org/maven2" }
}
dependencies {
    compile project(':worker-sdk')
}

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, cloud 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 below:

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

rootProject.name = "ExampleJavaWorker"
gradle.ext.mainClass = 'com.example.MyJavaWorker'

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.

Updated about a year ago


Setup and installation


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.