Data Objects
In principle, each application is based on a set of specific Data Objects that are related to each other, have specific functions and are usually persisted.
AOP provides basic functions for managing such objects and takes on the role of an easy-to-use object database. The storage handling and organization remains hidden to the user, who just uses the API to access all Data Objects in a uniform manner.
Type
The type defines which concrete Properties an Object of this type can have and what their meaning is. The type is identified by a string id like “datapoint” or “location” which has to be unique within the AOP application.
Properties
Every Data Object has a Property “Id” which uniquely identifies the Object.
Beside this the Data Object may have the following common Properties:
| Property | Type | Description |
|---|---|---|
| Id | guid | (Mandatory) Unique identifier of the Data Object, usually set by AOP on create. |
| ParentId | guid | Id of the Data Objects parent (if appropriate). |
| EditUser | string | (Readonly) Id of the user who last modified the Object, set by AOP. |
| EditTime | time | (Readonly) Time of the last user modification, set by AOP. |
Services
All Data Objects can be read generically through the Generic Data Service.
For most Data Objects there is also a specific service available with the name of the object type, described below as an example for the object type SampleType.
The Get() function, which can also be used for paginated access, is described in more detail below (→ Get).
Functions
| Result | Name / Params | Comment | ||
|---|---|---|---|---|
| GetResult | sampletype.Get | Returns a filtered list of SampleType Objects. | ||
| filter | string | (Optional) Filter expression which determines the result set. | ||
| select | string[] | (Optional) List of properties that should be contained in the result objects. | ||
| limit | int | (Optional) Maximum amount of Objects that should be returned. (Max : 100000) | ||
| GetResult | sampletype.Get | Returns a filtered list of SampleType Objects as a follow up to a previous Get call. | ||
| context | string | The context received within the last get result. Mandatory for subsequent get calls with pagination. | ||
| scroll | int | Scrolls through the result set with 'Next' or 'Prev'. Used for pagination. See EnumPaginationScroll. | ||
| offset | int | (Optional) Offset of the first Object in the result set that should be returned. Used for direct pagination. | ||
| limit | int | (Optional) Maximum amount of Objects that should be returned. (Max : 100000) | ||
| SampleType | sampletype.GetOne | Returns a single SampleType Object identified by the given id. | ||
| id | guid | The SampleType's id. | ||
| select | string[] | (Optional) List of properties that should be contained in the result object. | ||
| guid | sampletype.Create | Creates the SampleType in the system and returns the id of the SampleType. The SampleType must not have an id. If an id is set, the creation is rejected and an empty id is returned. | ||
| object | SampleType | The SampleType to create. | ||
| bool | sampletype.Update | Updates a SampleType with data from the provided Object. | ||
| object | SampleType | SampleType to update | ||
| bool | sampletype.Set | Sets specific properties of a SampleType Object. | ||
| id | guid | Id of the SampleType to modify. | ||
| props | value{} | List of properties that should be set. Property paths may be used as ids to address any partial aspect of the Object. | ||
| bool | sampletype.Delete | Deletes a SampleType Object. Returns true if successfully deleted or if no such Object existed to begin with. | ||
| id | guid | Id of the SampleType to delete. | ||
| bool | sampletype.BulkModify | Performs a bulk of changes at once. | ||
| create | SampleType[] | (Optional) List of SampleType Objects to create. | ||
| update | SampleType[] | (Optional) List of SampleType Objects to update. | ||
| set | ObjectAspect[] | (Optional) List of SampleType Object properties to set. | ||
| delete | guid[] | (Optional) List of SampleType ids to delete. | ||
Notifications
| Name / Params | Comment | ||
|---|---|---|---|
| sampletype.Created | Notifies about new SampleType Objects. | ||
| objects | SampleType[] | Newly created SampleType Objects. | |
| sampletype.Updated | Notifies about updated SampleType Objects. | ||
| objects | SampleType[] | Changed SampleType Objects. | |
| sampletype.Deleted | Notifies about deleted SampleType Objects. | ||
| ids | guid[] | Ids of the deleted SampleType Objects. | |
Objects
SampleType
| Property | Type | Description |
|---|---|---|
| Id | guid | (Unique) |
| EditTime | time | (Readonly, Not in default set) |
| EditUser | string | (Readonly, Not in default set) |
GetResult
| Property | Type | Description |
|---|---|---|
| Objects | object[] | Array of Objects. |
| Pagination | Pagination | (DistinctNull) Describes the result set, if not all Objects were returned. |
Pagination
| Property | Type | Description |
|---|---|---|
| TotalCount | int | (DistinctNull) Total count of available Objects, if available. |
| Offset | int | (DistinctNull) Offset of first Object, if available. |
| Count | int | Count of returned Objects. |
| Context | string | Pagination context for subsequent get calls. The content depends on the service and should be seen as opaque. |
| HasNext | bool | Can request next Objects for context. |
| HasPrev | bool | Can request previous Objects for context. |
ObjectAspect
| Property | Type | Description |
|---|---|---|
| Id | string | Id of the Object. May be a guid (as string) or string id. |
| Props | value{} | List of properties to change. Property paths may be used to address any partial aspect of the Object. |
EnumPaginationScroll
| Name | Value | Description |
|---|---|---|
| Offset | 0 | Scrolls to fixed position. |
| Next | 1 | Scrolls to next items for given context. |
| Prev | 2 | Scrolls to previous items for given context. |
Get
The Get function has several parameters, but they make sense for use only in certain combinations.
Usually you start with one “Intial Call” optionally specifying Filter, Select and possibly a Limit.
Pagination
If there are more Objects available than can be returned with one call, the result set will be paginated. In this case, a Pagination object will be returned by GetResult which contains a Context. This Context should then be used in “Follow-Up Calls” instead of Filter/Select. Filter/Select and Context should never be used together.
Pagination principially supports two modes Scrolling and Direct Page Access, but not all object types support both modes.
Scrolling
If Scrolling is possible, either HasNext or HasPrev are set in the Pagination object, and consecutive calls are given that Context together with the desired Scroll direction. The Limit specifies the amount of objects which should be returned in that direction.
Direct Page Access
Direct page access is possible if the Pagination object contains TotalCount and Offset. In that case you can directly move to a desired page by calculating its Offset and handing it over together with the Context. Offset and Scroll should never be used together.
Limit
The Limit ist not stored in the Context, so this parameter should always be added if the amount of Objects in the result set should be limited. This Limit can not exceed 100000. If no Limit is given the maximum of 100000 is used by default.
Filter
To query only certain Objects, a filter can be given as an expression. All Property ids of the respective object type can be used as a variable in that expression, and also Property Paths may be used.
Select
The select parameter is a string[] which contains all Property Ids which the result object should contain. For ease of use, the following special selectors can be used:
| Select Id | Description |
|---|---|
| [default] | Select the default Property set. |
| [all] | Select all available Properties. |
Especially [default] is helpful, because it allows specifying specific additional Properties to be returned in addition to the default set.