The store object provides the link between the FeatureModel and the data provider. The function of the store is to query the server for data, convert the response of the server to LuciadRIA Feature instances, and to perform optional CRUD operations: get, create, update and delete.

Most of the Store implementations separate the communication with a data provider (e.g. a WFS service) from the actual parsing of the server response. The conversion of the server response to LuciadRIA Feature instances is left to a Codec. For example, the WFSFeatureStore can be configured with a dedicated Codec if your WFS server, which the WFSFeatureStore connects to, does not support GeoJson as an output format.

A typical sequence of method calls on a set of a FeatureModel - Store - Codec is the following (without considering the asynchronous nature of those methods):

  1. FeatureModel#query gets called to perform the query on the server side.
  2. The FeatureModel passes the query parameters to the Store#query method.
  3. The Store performs the query and passes the response value to the Codec for decoding.
  4. The Codec returns the Feature instances to the Store, which passes them back to the FeatureModel.

Note: Most of the methods in the Store API are optional. The presence of such an optional method indicates that the store can perform a specific action on a feature. For instance, a Store can implement the query and get methods but omit the add, put and remove methods. That also affects the functionality of the FeatureModel paired with the Store, as explained in the documentation of the FeatureModel class.

Users of this class should always check whether an optional method is available before calling the method, as illustrated below:

if (typeof store.add === "function") {
//The "add" method is available and can be called
store.add(feature);
}

In order to create a custom store that implements the event system, the custom store should implement Evented.

export class CustomStore implements Store, Evented {

private _eventedSupport: EventedSupport;

constructor() {
this._eventedSupport = new EventedSupport()
}

on(event: "StoreChanged", callback: (eventType: string, feature: Feature, id: FeatureId) => any): Handle {
return this._eventedSupport.on(event, callback);
}

add(feature: Feature, options?: any): FeatureId | Promise<FeatureId> {
//Add the logic to actually store the feature

//Trigger a change event for the Store
this._eventedSupport.emit("StoreChanged", "add", feature, feature.id);
return feature.id;
}

query(query?: any, options?: any): Cursor | Promise<Cursor> {
//Create a Cursor with the correct results.
return new CursorImplementation();
}
}

interface Store<TFeature> {
    add?(feature, options?): FeatureId | Promise<FeatureId>;
    get?(id, options?): undefined | TFeature | Promise<TFeature>;
    on?(event, callback, context?, options?): Handle;
    on?(event, callback, context?, options?): Handle;
    put?(feature, options?): FeatureId | Promise<FeatureId>;
    query(query?, options?): Cursor<TFeature> | Promise<Cursor<TFeature>>;
    remove?(id): boolean | Promise<boolean>;
    spatialQuery?(bounds?, query?, options?): Cursor<TFeature> | Promise<Cursor<TFeature>>;
}

Type Parameters

  • TFeature extends Feature = Feature

    Represents the type of Feature instances that are handled by the store.

Implemented by

Methods

  • Adds a Feature to the store. This method is optional.

    When the adding action is successful, the Store should:

    • Update the ID of the Feature, which has just been added, to match the ID on the server side. That ID should also be returned by the method.
    • Emit the "add" event, which contains the Feature with updated ID, and the ID itself.

    Note:: If the Store does not emit the event, a map will not update the visualization of the feature if another entity than the map performs updates a feature on the Store.

    Parameters

    • feature: TFeature

      The Feature to add. When successfully added, the ID of the Feature will be adjusted to match the ID in the Store.

    • Optional options: any

      An optional object that can be used in a specific implementation of the method.

    Returns FeatureId | Promise<FeatureId>

    Returns the identifier of the Feature on success, or a promise for that identifier.

  • Retrieves a Feature by id from the data provider. This method is optional.

    Parameters

    • id: FeatureId

      The identifier of the Feature.

    • Optional options: any

      An optional object that can be used in a specific implementation of the method.

    Returns undefined | TFeature | Promise<TFeature>

    May return the Feature, or a promise for the Feature. When no feature with that id exists the returned value must be either undefined (the synchronous case), or a rejected promise (the asynchronous case).

  • Updates an existing Feature in the store. This method is optional.

    When the update is successful, the Store should emit an event which contains the Feature and the ID of the Feature.

    Note:: If the Store does not emit the event, a map will not update the visualization of the feature if another entity than the map updates a feature on the Store.

    Put may be implemented with the put-semantics of an HTTP-put. This means that if the feature does not exist yet in the store, it may be added to the store instead. The corresponding StoreChanged must correctly reflect the operation: the eventType must be 'update' when an existing element is updated and 'add' when a new element is added.

    Parameters

    • feature: TFeature

      The Feature to update.

    • Optional options: any

      An optional object that can be used in a specific implementation of the method.

    Returns FeatureId | Promise<FeatureId>

    Returns the identifier of the Feature on success, or a promise for the identifier.

  • Queries the store for objects. This method is not optional.

    Parameters

    • Optional query: any

      An object which represents a query filter that is understood by the underlying data provider. The structure of this object depends on a specific store implementation.

    • Optional options: QueryOptions

      An optional object that can be used in a specific implementation of the method.

    Returns Cursor<TFeature> | Promise<Cursor<TFeature>>

    A Cursor over a set of Feature instances or a promise for that Cursor.

  • Removes an object from the store by id. This method is optional.

    When the removal is successful, the Store should emit an event which contains the ID of the removed Feature.

    Note:: If the Store does not emit the event, a map will not update the visualization of the feature if another entity than the map removes a feature on the Store.

    Parameters

    Returns boolean | Promise<boolean>

    Returns true on successful removal, or a promise for that value.

  • Queries the store for objects within a spatial extent. This method is optional.

    Note: LuciadRIA determines the layer's default loading strategy based on the existence of this method in the store. If this method is implemented by store then the default loading strategy is LoadEverything.

    Note: In a situation when the map reference and the model reference are incompatible, for example: a Cartesian reference and a geodetic reference, then the layer's LoadEverything.

    Note: WFSFeatureStore implements this method by creating an OGC BBOX filter based on the bounds parameter.

    Parameters

    • Optional bounds: Bounds

      The spatial extent to return features for.

    • Optional query: any

      An object which represents a query filter that is understood by the underlying data provider. The structure of this object depends on a specific store implementation.

    • Optional options: QueryOptions

      An optional object that can be used in a specific implementation of the method.

    Returns Cursor<TFeature> | Promise<Cursor<TFeature>>

    A Cursor.

Events

"StoreChanged" event

  • on("StoreChanged", callback: ((eventType, feature, id) => any), context?: any) : Handle
  • An event that is emitted when the contents of the store changes.

    Parameters

    • event: "StoreChanged"

      the "StoreChanged" event.

    • callback: ((eventType, feature, id) => any)

      the callback to be invoked when the contents of the store changes. The callback has 3 parameters:

      • eventType: "add", "update" or "remove"
      • feature: the Feature that was added, updated or removed. In case of the "remove" event type, it may be undefined.
      • id: the identifier of the Feature.
        • (eventType, feature, id): any
        • Parameters

          Returns any

    • Optional context: any

      value to use as "this" when executing callback

    • Optional options: StoreChangedOptions

      An options object literal. If a query is specified, the listener function must only be invoked for features that match the query. StoreChanged

    Returns Handle

"" event

  • on("", callback: ((...args) => any), context?: any) : Handle
  • Registers an event listener on this store. This method is optional if Store does not emit events.

    Note: although this method is optional, it is strongly recommended to provide support for attaching listeners to the Store. The FeatureModel needs those events to generate ModelChanged events. So if your Store does not emit events, the visual representation of the model (e.g. the layer) will not be automatically updated when a feature is changed in the Store.

    Parameters

    • event: string

      the event

    • callback: ((...args) => any)

      the event listener

        • (...args): any
        • Parameters

          • Rest ...args: any[]

          Returns any

    • Optional context: any

      value to use as "this" when executing callback

    • Optional options: StoreChangedOptions

      An options object literal

    Returns Handle

    An object containing a single function named 'remove'. This can be used to unregister the listener from this store.