From 59461a8b7d291e967134a446240a07b4825b8c51 Mon Sep 17 00:00:00 2001 From: Curtis Rueden Date: Mon, 23 Sep 2024 16:26:07 -0500 Subject: [PATCH] Resolve documentation TODOs in Appose.java --- src/main/java/org/apposed/appose/Appose.java | 101 +++++++++++++++++-- 1 file changed, 95 insertions(+), 6 deletions(-) diff --git a/src/main/java/org/apposed/appose/Appose.java b/src/main/java/org/apposed/appose/Appose.java index a84d5f6..53f75e4 100644 --- a/src/main/java/org/apposed/appose/Appose.java +++ b/src/main/java/org/apposed/appose/Appose.java @@ -50,10 +50,6 @@ * {@link Service.Task#listen via callbacks}. * *

Examples

- * *

* Here is a very simple example written in Java: *

@@ -144,11 +140,104 @@ *
  • The worker must issue responses in Appose's response format on its * standard output (stdout) stream.
    • * + *

    Requests to worker from service

    *

    - * TODO - write up the request and response formats in detail here! - * JSON, one line per request/response. + * A request is a single line of JSON sent to the worker process via + * its standard input stream. It has a {@code task} key taking the form of a + * UUID, + * and a {@code requestType} key with one of the following values: *

    + *

    EXECUTE

    + *

    + * Asynchronously execute a script within the worker process. E.g.: + *

    + * 
    
+ * {
+ *    "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+ *    "requestType" : "EXECUTE",
+ *    "script" : "task.outputs[\"result\"] = computeResult(gamma)\n",
+ *    "inputs" : {"gamma": 2.2}
+ * }
+ *
    + *

    CANCEL

    + *

    + * Cancel a running script. E.g.: + *

    + * 
    
+ * {
+ *    "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+ *    "requestType" : "CANCEL"
+ * }
+ *
    * + *

    Responses from worker to service

    + *

    + * A response is a single line of JSON with a {@code task} key + * taking the form of a + * UUID, + * and a {@code responseType} key with one of the following values: + *

    + *

    LAUNCH

    + *

    + * A LAUNCH response is issued to confirm the success of an EXECUTE request. + *

    + * 
    
+ * {
+ *    "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+ *    "responseType" : "LAUNCH"
+ * }
+ *
    + *

    UPDATE

    + *

    + * An UPDATE response is issued to convey that a task has somehow made + * progress. The UPDATE response typically comes bundled with a {@code message} + * string indicating what has changed, {@code current} and/or {@code maximum} + * progress indicators conveying the step the task has reached, or both. + *

    + * 
    
+ * {
+ *    "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+ *    "responseType" : "UPDATE",
+ *    "message" : "Processing step 0 of 91",
+ *    "current" : 0,
+ *    "maximum" : 91
+ * }
+ *
    + *

    COMPLETION

    + *

    + * A COMPLETION response is issued to convey that a task has successfully + * completed execution, as well as report the values of any task outputs. + *

    + * 
    
+ * {
+ *    "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+ *    "responseType" : "COMPLETION",
+ *    "outputs" : {"result" : 91}
+ * }
+ *
    + *

    CANCELATION

    + *

    + * A CANCELATION response is issued to confirm the success of a CANCEL request. + *

    + * 
    
+ * {
+ *    "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+ *    "responseType" : "CANCELATION"
+ * }
+ *
    + *

    FAILURE

    + *

    + * A FAILURE response is issued to convey that a task did not completely + * and successfully execute, such as an exception being raised. + *

    + * 
    
+ * {
+ *    "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+ *    "responseType" : "FAILURE",
+ *    "error", "Invalid gamma value"
+ * }
+ *
    + * * @author Curtis Rueden */ public class Appose {