Worker SDK in Java

Step 2. Address major API breaking changes - Worker SDK in Java

  • See the Upgrade guide page for step 1, before following this page.

1. Update packages

Note: If your project is using generated build scripts, then you can skip this section and go to 2. Update usage of the snapshot API.

We've slightly cleaned up the package structure of the Worker SDK in Java in SpatialOS 14, so you need to make some adjustments within your build system:

a. Change java-worker-sdk.jar to improbable-worker.jar.
b. Change java-worker-sdk-native-win32-x64.jar to improbable-worker-native-win32-x64.jar.
c. Change java-worker-sdk-native-macos-x64.jar to improbable-worker-native-macos-x64.jar.
d. Change java-worker-sdk-native-linux-x64.jar to improbable-worker-native-linux-x64.jar.

2. Update usage of the snapshot API

We've changed the way snapshot errors are reported, to allow distinction between different types of errors. In Java the different snapshot errors are reported by the exceptions StreamBadStateException, StreamInvalidDataException and java.io.EOFException being thrown. The signature of the snapshot API methods has changed as well to reflect this.

2.1. Saving snapshots

All SnapshotOutputStream methods may fail. Previously Option<string> was used to signal errors, for example like this:

HashMap<EntityId, Entity> entities = myEntities();
SnapshotOutputStream outputStream = new SnapshotOutputStream(newSnapshotFilename);

for (Map.Entry<EntityId, Entity> entry : entities.entrySet()) {
    Option<String> error = outputStream.writeEntity(entry.getKey(), entry.getValue());
    if (error.isPresent()) {
        // Log error.
        break;
    }
}
// Write EOF and release the stream's resources.
outputStream.close();

Now, writeEntity no longer returns a value, but instead throws a number of exceptions. To upgrade, rewrite your code to use a try-catch block around your snapshot processing to catch the exceptions and distinguish between different kinds of errors:

HashMap<EntityId, Entity> entities = myEntities();
SnapshotOutputStream outputStream = null;
try {
  outputStream = new SnapshotOutputStream(filePath);
  for (Map.Entry<EntityId, Entity> entry : entities.entrySet()) {
    try {
      outputStream.writeEntity(entry.getKey(), entry.getValue());
    } catch (StreamInvalidDataException ex) {
      // Handle or log operation failure.
      // The last write operation failed, but the snapshot is still usable.
    } catch (StreamBadStateException ex) {
      // Log error.
      // An internal error occurred when writing and the snapshot is not usable.
      break;
    }
  }
} catch (StreamBadStateException ex) {
  // Log error.
  // The snapshot failed to be initialized, and the stream is not usable.
} finally {
  // Write EOF and release the stream's resources.
  if (outputStream != null) {
    outputStream.close();
  }
}

2.2. Loading snapshots

All SnapshotInputStream methods may fail. Previously, a RuntimeException was used to signal errors, for example like this:

HashMap<EntityId, Entity> entities = new HashMap<EntityId, Entity>();
SnapshotInputStream inputStream = new SnapshotInputStream(snapshotFilename);

EntityId entityId;
Entity entity;

while (inputStream.hasNext()) {
    try {
        Map.Entry<EntityId, Entity> entity = inputStream.readEntity();
        entities.put(entity.getKey(), entity.getValue());
    } catch (RuntimeException ex) {
        // Log error.
    }
}
// Release the stream's resources.
inputStream.close();

To upgrade, update the try-catch block around your snapshot processing to catch the different kinds of exceptions and use these to distinguish between different kinds of errors. For example:

HashMap<EntityId, Entity> entities = new HashMap<EntityId, Entity>();
SnapshotInputStream inputStream = null;
try {
  inputStream = new SnapshotInputStream(filePath);
  while (inputStream.hasNext()) // This check can be done alternatively by catching EndOfStreamException.
  {
    try {
      Map.Entry<EntityId, Entity> snapshotEntity = inputStream.readEntity();
      entities.put(snapshotEntity.getKey(), snapshotEntity.getValue());
    } catch (StreamInvalidDataException ex) {
      // Log error.
      // The last read operation failed, but the snapshot is still usable.
    } catch (StreamBadStateException ex) {
      // Log error.
      // An internal error occurred when reading and the snapshot is not usable.
      break;
    } catch (java.io.EOFException ex) {
      // The EOF was reached when reading. Not an error.
      break;
    }
  }
} catch (StreamBadStateException ex) {
  // Log error.
  // The snapshot failed to be initialized, and the stream is not usable.
} finally {
  // Release the stream's resources.
  if (inputStream != null) {
    inputStream.close();
  }
}

Updated about a year ago


Next

Now return to the Upgrade guide and follow step 3.

Upgrade guide

Worker SDK in Java


Suggested Edits are limited on API Reference Pages

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