The FeatureModel class

A FeatureModel is used to model vector data that must be displayed on a map. A feature model contains instances of Feature. Such a feature contains a number of properties specific to the application domain, as well as a shape. See Introduction to features (vector shapes) for more information on Feature.

A feature model is responsible for the following tasks:

  • Determine the geospatial reference of the feature data

  • If there is a server that hosts the features, communicate with the server

  • CRUD functionality: the FeatureModel lets you retrieve a list of features, and also allows you to create, update and delete features. The CRUD functionality and server communication go hand-in-hand: the feature model communicates each operation to the feature server. For more information, see Managing your feature data with a Store.

  • Decode features from a server-specific format to the LuciadRIA Feature format, and the other way around. For more information, see Configuring a codec.

Managing your feature data with a Store

What is a Store?

The Store provides a facade for the FeatureModel to query and update its data. It inserts a layer of abstraction from the client-server communication protocol and the format in which the data is stored on the server.

The Store has two main functions:

  • Implementing the communication protocol between the client and the server.

  • Translating between the server-specific data format and the LuciadRIA Feature format. A FeatureModel is designed to work with LuciadRIA Feature instances while the data on the server is typically stored in another format. The conversion of data from one format to another is handled in the Store.

The Store concept is inspired by the HTML5/W3C IndexedDB object store API, and offers a means to interact with stored data services. A Store is able to manage:

  • Data stored on a server, by encapsulating the communication protocol for data exchange

  • Data stored offline, by communicating with the HTML5 offline storage facilities

  • Data in local memory

Using Stores in LuciadRIA

The CRUD operations supported by the FeatureModel are the ones that are supported by the Store.

Because of the asynchronous communication mechanisms used in web applications, the API is driven mainly by Promise. Promise instances constitute a way to follow up on the results of asynchronous server requests. For more information about this CommonJS interface, see the Promises/A specification.

Most methods in a Store implementation are optional. A Store that implements a particular method offers support for that particular Store operation. The most important operations are:

query

Queries a set of features from the server. A set of store-specific query parameters can be passed to this function. This method must return a cursor that can be used to iterate over the results of the query, or a Promise for this cursor.

add

Adds a new feature to the store

put

Updates a feature in the store

remove

Removes a feature from the store

get

Retrieves a single feature from the store

For complete documentation, see the API reference documentation for Store.

The LuciadRIA FeatureModel reflects this API, and adopts only those CRUD operations that are also supported by the store.

Configuring a codec

Features retrieved from a server are typically not instances of the Feature class. They are encoded in a server-specific format. It is up to the store to convert between this server-specific format and LuciadRIA Feature instances.

Most of the store implementations available in LuciadRIA allow you to specify a Codec. The Codec is used to decode the data structure retrieved from the server to a set of LuciadRIA features. Such a Feature contains a Shape and a number of properties specific to the application domain.

The Codec also supports the encoding of feature data structures to the data format expected by the server.

Querying and updating models

You can retrieve data from the model by means of the model query method. LuciadRIA Layer instances use this method as well to retrieve data from the model. The result of a query is a model/Cursor or a Promise for a cursor. Cursor provides a hasNext and next method that you can use to iterate over the results of the query.

It is possible for Store implementations to implement the util/Evented API for the purpose of providing change notifications. If a Store implements this API, it must emit a StoreChanged event when features in the store are modified. A FeatureModel only emits ModelChanged events if it receives StoreChanged events from its underlying store. In other words, a FeatureModel is only observable if its Store is as well.