Warning, /pim/sink/docs/clientapi.md is written in an unsupported language. File is not indexed.
0001 The client API consists of: 0002 0003 * a modification API for entities (Create/Modify/Delete) 0004 * a query API to retrieve entities 0005 * a resource facade to abstract the resource implementation details 0006 * a set of standardized domain types 0007 * a notification mechanism to be notified about changes from individual stores 0008 0009 ## Requirements/Design goals 0010 * zero-copy should be possible (mmap support) 0011 * A single copy is more realistic 0012 * Most importantly we should hide how the data is stored (in parts, or one mmapped buffer) 0013 * property-level on-demand loading of data 0014 * streaming support for large properties (attachments) 0015 0016 ## Store Facade 0017 The store is always accessed through a store specific facade, which hides: 0018 0019 * store access (one store could use a database, and another one plain files) 0020 * message type (flatbuffers, ...) 0021 * indexes 0022 * synchronizer communication 0023 * notifications 0024 0025 This abstraction layer allows each resource to separately define how data is stored and retrieved. Therefore tradeoffs can be defined to suit the expected access patterns or structure of source data. Further it allows individual resources to choose different technologies as suitable. Logic can still be shared among resources while keeping the maintenance effort reasonable, by providing default implementations that are suitable for most workloads. 0026 0027 Because the facade also implements querying of indexes, a resource my use server-side searching to fullfill the query, and fall back to local searches when the server is not available. 0028 0029 ## Modifications 0030 Modifications are executed by the client sending modification commands to the synchronizer. The synchronizer is responsible for ensuring that modification are not lost and eventually persisted. A small window exists therefore, while a modification is transferred to the synchronizer, where a modification can get lost. 0031 0032 The API consists of the following calls: 0033 0034 * create(domainObject) 0035 * modify(domainObject) 0036 * remove(domainObject) 0037 0038 The changeset are recorded by the domain object when properties are set, and are then sent to the synchronizer once modify is called. 0039 0040 Each modification is associated with a specific revision, which allows the synchronizer to do automatic conflict resolution. 0041 0042 ### Conflict Resolution 0043 Conflicts can occur at two points: 0044 0045 * In the client: While i.e. an editor is open and we receive an update for the same entity 0046 * In the synchronizer: After a modification is sent to the synchronizer but before it's processed 0047 0048 In the first case the client is repsonsible to resolve the conflict, in the latter case it's the synchronizer's responsibility. 0049 A small window exists where the client has already started the modification (i.e. command is in socket), and a notification has not yet arrived that the same entity has been changed. In such a case the synchronizer may reject the modification because it has the revision the modification refers to no longer available. 0050 0051 ### Lazy Loading ### 0052 The system provides property-level lazy loading. This allows i.e. to defer downloading of attachments until the attachments is accessed, at the expense of having to have access to the source (which could be connected via internet). 0053 0054 To achieve this, the query system must check for the availability of all requested properties on all matched entities. If a property is not available, a command must be sent to the synchronizer to retrieve said properties. Once all properties are available the query can complete. 0055 0056 Note: We should perhaps define a minimum set of properties that *must* be available. Otherwise local search will not work. On the other hand, if a resource implements server-side search, it may not care if local search doesn't work. 0057 0058 ### Data streaming ### 0059 Large properties such as attachments should be streamable. An API that allows to retrieve a single property of a defined entity in a streamable fashion is probably enough.