The FeatureModel class

You use a FeatureModel to model vector data that you must display on a map. A feature model has instances of Feature. Such a feature has a properties specific to the application domain, and a shape. See Introduction to features (vector shapes) for more information on Feature.

A feature model handles 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 capabilities: the FeatureModel lets you retrieve a list of features, and you can also create, update and delete features. The CRUD capability 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 Store handles the conversion of data from one format to another.

The HTML5/W3C IndexedDB object store API inspires the The Store idea. It 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 the Store supports.

Because of the asynchronous communication mechanisms 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. You can pass a set of store-specific query parameters to this function. This method must return a cursor that you can use 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.

For an example of the use of a FeatureModel and a Store to connect to an OGC Web Feature Service (WFS), see the Load and display vector data tutorial.

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’s 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. You use the Codec to decode the data structure retrieved from the server to a set of LuciadRIA features. Such a Feature has a Shape and 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 through 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’s possible for Store implementations to implement the util/Evented API so that it sends change notifications. If a Store implements this API, it must emit a StoreChanged event when features in the store change. 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.