Merge pull request #5241 from FinnStutzenstein/autoupdate-service

Autoupdate service interface

docs/interfaces/autoupdate-service.txt

@@ -0,0 +1,129 @@
+/**
+ * This is a chatch-all exception for some invalid parameters
+ */
+Exception InvalidFormat(msg: string);
+
+/**
+ * This exception is thrown, when parsing model data. E.g. there is an indicated
+ * relation to a key, but the data are no foreign ids/fqids. The exception may
+ * happen, if the stream is used at runtime, because this cannot be detected
+ * when the caller makes the request.
+ */
+Exception ParsingError(msg: string);
+
+/**
+ * This methods subscribes to the given request. The response is a stream
+ * (language dependent) updating all models according to the ModelRequest if new
+ * data is available. On subscription, initial data must be pushed to the caller
+ * as soon as possible. The stream can be closed by closing the stream (e.g. the
+ * underlying network connection).
+ *
+ * @throws InvalidFormat
+ * @throws ParsingError
+ */
+subscribe(request: ModelRequest): stream<ModelData>;
+
+/**
+ * This is the main interface for requesting models in a structured, nested way.
+ * The initial request targets some models as the root models of one collection
+ * with all the same fields. This build a tree of dependencies, because the
+ * value of some fields may be a GenericRelationFieldDescriptor again.
+ *
+ * For a description of `fields` and `collection`, see GenericRelationFieldDescriptor
+ * and RelationFieldDescriptor.
+ *
+ * `ids`: This is a list of ids for a collection, that should be provided. All
+ * models, that the user can see, must be included in the response. The model
+ * fields are handled according to `GenericRelationFieldDescriptor`.
+ */
+Interface ModelRequest extends Fields {
+    ids: ID[];
+    collection: Collection;
+}
+
+Interface Fields {
+    fields: {
+        [field: Field]: GenericRelationFieldDescriptor
+            | RelationFieldDescriptor
+            | StructuredFieldDescriptor
+            | null;
+    }
+}
+
+/**
+ * For an overview, see `ModelRequest`.
+ *
+ * `fields` (inherited from `Fields`, see above):
+ * Regardless of the value of a field, the restricted values are given in the
+ * response (multiple for structured fields). If the restricted value is null,
+ * the field must be included here.
+ *
+ * If the value is not null, it is indicated, that there is a reference to
+ * follow. There are three types of values:
+ * - GenericRelationFieldDescriptor: The reference is a generic one. This means, that
+ *   the actual value from the model is a fqid or an array of fqids.
+ * - RelationFieldDescriptor: A collection is given, so it can be expected, that the
+ *   actual model value is an id or an array of ids.
+ * - StructuredFieldDescriptor: The field is a template field and should be
+ *   handled in this way.
+ */
+Interface GenericRelationFieldDecriptor extends Fields {
+    type: 'generic-relation' | 'generic-relation-list';
+}
+
+/**
+ * For an overview, see `ModelRequest`. For `fields`, see GenericRelationFieldDescriptor.
+ *
+ * `collection`:
+ * This is the collection, the ids are associated to. The ids are provided with
+ * two different ways:
+ * - In a ModelRequest, the ids are given.
+ * - If this interface is used in a field indication a relation, the id(s) are
+ *   given by the actual model data.
+ */
+Interface RelationFieldDescriptor extends Fields {
+    type: 'relation' | 'relation-list';
+    collection: Collection;
+}
+
+/**
+ * Structured Fields: A field with `$` as a placeholder can be structured. The
+ * `$` is a template placeholder. The `template field` holds a list of strings
+ * with options to insert into `$`. All these fields are the `structured
+ * fields`. Example:
+ * B_$_ids is the template field. Its value may be `["1", "test"]`, so the
+ * structured fields are B_1_ids and B_test_ids.
+ *
+ * This interface indicates, that there are structured fields related to the
+ * given template field, that should be resolved. If one would give `B_$_ids:
+ * null` without using this interface, the response would be just the template
+ * field `B_$_ids` and no structured fields.
+ *
+ * For just resolving values, leav `values` out (hence the optional parameter).
+ *
+ * If the values of all structured fields are references, use the `values`
+ * parameter analog to the `fields` paramter as documented in
+ * `GenericRelationFieldDescriptor`.
+ */
+Interface StructuredFieldDecriptor {
+    type: 'template',
+    values?: {
+        [field: Field]: GenericRelationFieldDescriptor
+            | RelationFieldDescriptor
+            | StructuredFieldDescriptor
+            | null;
+    }
+}
+
+
+/**
+ * This structure holds all data given by the called service structured by
+ * fqids. Each fqid contains the (partial, restricted) data for the fqid.
+ */
+Interface ModelData {
+    [collection: Collection]: {
+        [id: Id]: {
+            [field: Field]: Value;
+        };
+    };
+}

docs/interfaces/how-to.txt

@@ -19,7 +19,7 @@ Example:
      * @throws ObjectNotFound
     do_it(data: MyRequest): void publishes MyEvent;
 
-    interface MyRequest {
+    Interface MyRequest {
         id: Id;
         text: string;
         some_other_value: number;