Interface Store<TFeature>

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 extends Feature = Feature> {
    add(feature: TFeature, options?: any): FeatureId | Promise<FeatureId>;
    get(id: FeatureId, options?: any): undefined | TFeature | Promise<TFeature>;
    on(
        event: "StoreChanged",
        callback: (eventType: string, feature: TFeature, id: FeatureId) => any,
        context?: any,
        options?: StoreChangedOptions,
    ): Handle;
    on(
        event: string,
        callback: (...args: any[]) => any,
        context?: any,
        options?: StoreChangedOptions,
    ): Handle;
    put(feature: TFeature, options?: any): FeatureId | Promise<FeatureId>;
    query(
        query?: any,
        options?: QueryOptions,
    ): Cursor<TFeature> | Promise<Cursor<TFeature>>;
    remove(id: FeatureId): boolean | Promise<boolean>;
    spatialQuery(
        bounds?: Bounds,
        query?: any,
        options?: QueryOptions,
    ): 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

add? get? put? query remove? spatialQuery?

Events

StoreChanged

Methods

  • Adds a Feature to the store.

    When the addition is successful, the Store must:

    • Update the ID of the Feature to reflect the ID assigned by the server, if the Feature's ID was undefined prior to addition. If an ID was already defined, the Store should respect the provided ID unless overridden by the server.
    • Emit a "StoreChanged" event with:
      • eventType: "add"
      • feature: The added Feature, including its updated ID.
      • id: The updated identifier of the Feature.
      Failure to do so will result in a map not displaying newly added features.

    Parameters

    • feature: TFeature

      The Feature to add.

    • Optionaloptions: any

      An optional object for additional implementation-specific parameters.

    Returns FeatureId | Promise<FeatureId>

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

  • Retrieves a Feature by id from the data provider.

    Parameters

    • id: FeatureId

      The identifier of the Feature.

    • Optionaloptions: 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, or adds it if it does not already exist.

    When the operation is successful, the Store must emit a "StoreChanged" event. The event should contain:

    • eventType: "update" if an existing feature is updated, or "add" if a new feature is added.
    • feature: The updated or newly added Feature.
    • id: The identifier of the affected Feature.
    Failure to do so will result in a map not displaying updated features.

    The implementation of this method may follow the semantics of an HTTP PUT request. This means that if the feature does not already exist in the store, it may be added as a new entry.

    Parameters

    • feature: TFeature

      The Feature to update or add.

    • Optionaloptions: any

      An optional object for additional implementation-specific parameters.

    Returns FeatureId | Promise<FeatureId>

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

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

    Parameters

    • Optionalquery: 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.

    • Optionaloptions: 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 a Feature from the store by its ID.

    When the removal is successful, the Store must emit a "StoreChanged" event, which contains an eventType of "remove" and the ID of the removed Feature.

    If the Store does not emit the "StoreChanged" event, the map visualization will not reflect the removal of the feature.

    Parameters

    • id: FeatureId

      The identifier of the Feature to be removed.

    Returns boolean | Promise<boolean>

    Returns true on successful removal, or a promise that resolves to true.

  • 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

    • Optionalbounds: Bounds

      The spatial extent to return features for.

    • Optionalquery: 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.

    • Optionaloptions: QueryOptions

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

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

    A Cursor.

Events

  • An event that is emitted when the contents of the store change. Stores that perform create, update, or delete operations must implement this event to ensure that changes are communicated properly to listeners.

    Parameters

    • event: "StoreChanged"

      The "StoreChanged" event.

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

      The callback to be invoked when the contents of the store change. The callback has three parameters:

      • eventType: A string indicating the type of change. Possible values are "add", "update", or "remove".
      • feature: The Feature that was added, updated, or removed. For the "remove" event type, the value should be undefined.
      • id: The identifier of the Feature that was affected by the change.
    • Optionalcontext: any

      An optional value used as the this context when executing the callback.

    • Optionaloptions: StoreChangedOptions

      An optional object specifying additional options for the event listener. StoreChanged

    Returns 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[]) => any

      the event listener

    • Optionalcontext: any

      value to use as "this" when executing callback

    • Optionaloptions: 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.

Settings

Member Visibility

On This Page

Methods
Events