Snapshots

The SDK provides two classes to manipulate snapshots stored in files; Improbable.worker.SnapshotInputStream to read snapshot files from disk, one entity at a time, and Improbable.worker.SnapshotOutputStream to write snapshot files to disk, one entity at a time. These stream classes are the recommended methods of manipulating snapshots as they do not require the entire snapshot to be stored in memory when reading or writing a snapshot.

Improbable.worker.SnapshotInputStream has a constructor and three public methods:

/**
 * Open a SnapshotInputStream to load a snapshot from a file.
 *
 * @param path The path to the snapshot file.
 */
public SnapshotInputStream(String path);

/**
 * Returns true if the SnapshotInputStream has not reached the end of the snapshot file.
 *
 * @return A boolean which is true if the SnapshotInputStream has not reached the end of the snapshot and false otherwise.
 */
public boolean hasNext();

/**
 * Load the next (EntityId, Entity) pair from the snapshot file. Throws a RuntimeException if an error occured.
 *
 * @return A Map.Entry<EntityId, Entity> containing the (EntityId, Entity) pair read from the snapshot file.
 */
public Map.Entry<EntityId, Entity> readEntity();

/**
 * Close the SnapshotInputStream and release its resources.
 */
public void close();

Improbable.worker.SnapshotOutputStream has a constructor and two public methods:

/**
 * Open a SnapshotOutputStream to write a snapshot to a file saved at the String path.
 *
 * @param path The path to write the snapshot file to.
 */
public SnapshotOutputStream(String path);

/**
 * Write the (EntityId, Entity) pair to the snapshot.
 *
 * @param entityId The EntityId of the Entity to be written to the snapshot.
 * @param entity The Entity to be written to the snapshot.
 *
 * @return An Optional string which contains an error message if an error occured and is empty otherwise.
 */
public Option<String> writeEntity(EntityId entityId, Entity entity);

/**
 * Close the SnapshotOutputStream.
 */
public void close();

Note that, unlike the rest of the API described in this document, snapshot manipulation does not require a Connection, making it possible to develop standalone, offline snapshot manipulation tools. However, we recommend using the build infrastructure provided by SpatialOS for workers to build your standalone tools.

Here is an example of loading a snapshot, performing some manipulation on it, and saving it back. It uses the types and components defined in the example from Generated code.

private static void addLowHealthEffectToEntities(String snapshotFilename, String newSnapshotFilename) {
    // Create a SnapshotInputStream to read from the snapshot file.
    SnapshotInputStream inputStream = new SnapshotInputStream(snapshotFilename);
    // Create a SnapshotOutputStream to write to a snapshot file.
    SnapshotOutputStream outputStream = new SnapshotOutputStream(newSnapshotFilename);
    java.util.Map.Entry<EntityId, Entity> entry;

    // Iterate over each entity in the snapshot.
    while (inputStream.hasNext()) {
        // Read the next Map.Entry<Entity, Entity> from the stream.
        entry = inputStream.readEntity();
        EntityId entityId = entry.getKey();
        Entity entity = entry.getValue();
        // Add the "LowHealth" effect to all entities that have a Creature component and less than 10 health points.
        if (entity.get(Creature.COMPONENT).isPresent()) {
            CreatureData status = entity.get(Creature.COMPONENT).get();
            if (status.getHealth() < 10) {
                status.getEffects().add(new StatusEffect("LowHealth", 100));
            }
        }
        // Write the (entityId, entity) pair to the snapshot file.
        outputStream.writeEntity(entityId, entity);
    }
    // Write the end of the snapshot and release the SnapshotOutputStream's resources.
    outputStream.close();
    inputStream.close();
}

Search results