Package dev.gmitch215.bytebox.durable

Interface DurableState

All Superinterfaces:
org.teavm.jso.JSObject
public interface DurableState extends org.teavm.jso.JSObject
A Durable Object's own context: its storage, its alarm, and its WebSockets.

Handed to every handler. Storage is strongly consistent and private to this instance, and an instance is single-threaded, so a read-modify-write needs no lock. 

 public class Counter implements DurableObject {
 	@Override
 	public Response fetch(Request request, DurableState state, Env env) {
 		long count = state.getLong("count", 0) + 1;
 		state.put("count", count);
 		return Bytebox.response(String.valueOf(count));
 	}
 }
Since:
1.0.0

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    DurableState.Storage
    A Durable Object's storage.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    acceptWebSocket(WebSocket socket)
    Takes the server end of a WebSocket into this instance's set.
    void
    acceptWebSocket(WebSocket socket, org.teavm.jso.JSObject tags)
    Takes the server end into this instance's set, under tags.
    default long
    alarmAt()
    Returns when the alarm is due, in milliseconds since the epoch, or 0 when none is set.
    default int
    broadcast(String message)
    Sends text to every open WebSocket this instance holds.
    default boolean
    delete(String key)
    Removes a key.
    default void
    deleteAlarm()
    Cancels the alarm.
    default void
    deleteAll()
    Removes everything this instance holds, including the alarm.
    default TSObject
    get(String key)
    Reads a value.
    default long
    getLong(String key, long fallback)
    Reads a number.
    default String
    getString(String key)
    Reads text.
    default String
    identifier()
    Returns this instance's identifier, stable for the life of the object.
    default List<String>
    keys()
    Returns every key this instance holds.
    default void
    put(String key, long value)
    Writes a number.
    default void
    put(String key, TSObject value)
    Writes a value.
    default void
    put(String key, String value)
    Writes text.
    default void
    setAlarm(long at)
    Schedules the alarm handler.
    default List<WebSocket>
    sockets()
    Returns every WebSocket this instance holds.
    default SQL
    sql(String query, Object... bindings)
    Runs a query against this instance's own SQLite database.
    DurableState.Storage
    storage()
    Returns the storage itself, for anything the convenience methods here do not cover.
    org.teavm.jso.core.JSArrayReader<WebSocket>
    webSockets()
     

    Methods inherited from interface org.teavm.jso.JSObject

    cast

  • Method Details

    • storage

      DurableState.Storage storage()
      Returns the storage itself, for anything the convenience methods here do not cover.
      Returns:
      the storage itself, for anything the convenience methods here do not cover

    • get

      default TSObject get(String key)
      Reads a value.
      Parameters:
      key - the key
      Returns:
      the value, or null when absent

    • getLong

      default long getLong(String key, long fallback)
      Reads a number.
      Parameters:
      key - the key
      fallback - what to answer when the key is absent
      Returns:
      the value

    • getString

      default String getString(String key)
      Reads text.
      Parameters:
      key - the key
      Returns:
      the value, or null when absent

    • put

      default void put(String key, TSObject value)
      Writes a value.
      Parameters:
      key - the key
      value - the value

    • put

      default void put(String key, String value)
      Writes text.
      Parameters:
      key - the key
      value - the value

    • put

      default void put(String key, long value)
      Writes a number.

      Stored as a JavaScript number, so a value past 2^53 loses precision. Write one that has to survive exactly with String.valueOf instead.

      Parameters:
      key - the key
      value - the value

    • delete

      default boolean delete(String key)
      Removes a key.
      Parameters:
      key - the key
      Returns:
      whether it was there

    • keys

      default List<String> keys()
      Returns every key this instance holds.
      Returns:
      every key this instance holds

    • deleteAll

      default void deleteAll()
      Removes everything this instance holds, including the alarm.

    • sql

      default SQL sql(String query, Object... bindings)
      Runs a query against this instance's own SQLite database.

      Synchronous, unlike D1: the database is local to this instance, so there is no promise to wait on and no fiber suspension. Bind parameters are ?1, ?2 and so on. 

       state.sql("create table if not exists visits (day text primary key, count integer)");
 long count = state.sql("select count from visits where day = ?1", day)
 	.one()
 	.get("count")
 	.asLong();
      Parameters:
      query - the SQL
      bindings - the values to bind, in order
      Returns:
      what the query answered

    • setAlarm

      default void setAlarm(long at)
      Schedules the alarm handler.

      One alarm per instance: setting it again moves the time rather than adding a second. The handler is retried on a throw, so it has to be safe to run twice.

      Parameters:
      at - when, in milliseconds since the epoch

    • alarmAt

      default long alarmAt()
      Returns when the alarm is due, in milliseconds since the epoch, or 0 when none is set.
      Returns:
      when the alarm is due, in milliseconds since the epoch, or 0 when none is set

    • deleteAlarm

      default void deleteAlarm()
      Cancels the alarm.

    • acceptWebSocket

      void acceptWebSocket(WebSocket socket)
      Takes the server end of a WebSocket into this instance's set.

      Accepted this way rather than with the socket's own accept, because this is what lets the instance hibernate: the connection stays open with no instance in memory, and a message brings one back.

      Parameters:
      socket - the server end

    • acceptWebSocket

      void acceptWebSocket(WebSocket socket, org.teavm.jso.JSObject tags)
      Takes the server end into this instance's set, under tags.
      Parameters:
      socket - the server end
      tags - labels to find it by later, at most 10 of at most 256 characters

    • sockets

      default List<WebSocket> sockets()
      Returns every WebSocket this instance holds.
      Returns:
      every WebSocket this instance holds

    • broadcast

      default int broadcast(String message)
      Sends text to every open WebSocket this instance holds.
      Parameters:
      message - the text
      Returns:
      how many it reached

    • webSockets

      org.teavm.jso.core.JSArrayReader<WebSocket> webSockets()

    • identifier

      default String identifier()
      Returns this instance's identifier, stable for the life of the object.
      Returns:
      this instance's identifier, stable for the life of the object