OpenSlides/docs/interfaces/autoupdate-service.txt
Finn Stutzenstein c52821d864 Merge pull request #5241 from FinnStutzenstein/autoupdate-service
Autoupdate service interface
2020-03-16 16:05:14 +01:00

130 lines
4.6 KiB
Plaintext

/**
* 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;
};
};
}