A dynamic entity data source that streams observations to a client. More...
Header: | #include <DynamicEntityDataSource.h> |
Since: | Esri::ArcGISRuntime 200.1 |
Inherits: | Esri::ArcGISRuntime::Object, Esri::ArcGISRuntime::Loadable, and Esri::ArcGISRuntime::RemoteResource |
Inherited By: |
Public Functions
virtual | ~DynamicEntityDataSource() override |
QFuture<void> | connectDataSourceAsync() |
Esri::ArcGISRuntime::Error | connectionError() const |
Esri::ArcGISRuntime::ConnectionStatus | connectionStatus() const |
QFuture<void> | disconnectDataSourceAsync() |
Esri::ArcGISRuntime::DynamicEntityDataSourceType | dynamicEntityDataSourceType() const |
int | maximumReconnectionAttempts() const |
QFuture<void> | purgeAllAsync() |
Esri::ArcGISRuntime::DynamicEntityDataSourcePurgeOptions * | purgeOptions() const |
double | reconnectionInterval() const |
void | setMaximumReconnectionAttempts(int maximumReconnectionAttempts) |
void | setReconnectionInterval(double reconnectionInterval) |
Reimplemented Public Functions
virtual void | cancelLoad() override |
virtual Esri::ArcGISRuntime::Credential * | credential() const override |
virtual void | load() override |
virtual Esri::ArcGISRuntime::Error | loadError() const override |
virtual Esri::ArcGISRuntime::LoadStatus | loadStatus() const override |
virtual Esri::ArcGISRuntime::RequestConfiguration | requestConfiguration() const override |
virtual void | retryLoad() override |
virtual void | setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration) override |
virtual QUrl | url() const override |
Signals
void | connectionStatusChanged(Esri::ArcGISRuntime::ConnectionStatus connectionStatus) |
void | doneLoading(const Esri::ArcGISRuntime::Error &loadError) |
void | dynamicEntityObservationPurged(Esri::ArcGISRuntime::DynamicEntityObservationInfo *observationInfo) |
void | dynamicEntityObservationReceived(Esri::ArcGISRuntime::DynamicEntityObservationInfo *observationInfo) |
void | dynamicEntityPurged(Esri::ArcGISRuntime::DynamicEntityInfo *info) |
void | dynamicEntityReceived(Esri::ArcGISRuntime::DynamicEntityInfo *info) |
void | loadStatusChanged(Esri::ArcGISRuntime::LoadStatus loadStatus) |
Protected Functions
DynamicEntityDataSource(QObject *parent = nullptr) | |
void | addObservation(const Esri::ArcGISRuntime::Geometry &geometry, const QVariantMap &attributes) |
QFuture<void> | deleteEntityAsync(const QString &entityId) |
virtual QFuture<void> | onConnectAsync() = 0 |
virtual QFuture<void> | onDisconnectAsync() = 0 |
virtual QFuture<Esri::ArcGISRuntime::DynamicEntityDataSourceInfo *> | onLoadAsync() = 0 |
void | setConnectionFailed(const QString &userDefinedError, bool reconnect) |
void | setConnectionStatusAndError(Esri::ArcGISRuntime::ConnectionStatus status, const QString &userDefinedError = "", bool reconnect = false) |
void | setLoadInfoAndError(Esri::ArcGISRuntime::DynamicEntityDataSourceInfo *dynamicEntityDataSourceInfo, const QString &userDefinedError = "") |
Detailed Description
The DynamicEntityDataSource class is the base class for classes that stream dynamic entity data. The class provides methods and properties that allow:
- maintenance of a persistent connection for streaming
- control over the storage of observations in its local data cache
- notification of received or purged observations
This class is used as the data source for a DynamicEntityLayer.
Users may extend this class by deriving from it. Derived classes must override the following methods:
- DynamicEntityDataSource::onLoadAsync: populate and return a DynamicEntityDataSourceInfo object
- DynamicEntityDataSource::onConnectAsync: start receiving or processing observation data
- DynamicEntityDataSource::onDisconnectAsync: stop receiving or processing observation data
See also ArcGISStreamService.
Member Function Documentation
[protected, since Esri::ArcGISRuntime 200.2]
DynamicEntityDataSource::DynamicEntityDataSource (QObject *parent = nullptr)
Create a DynamicEntityDataSource object.
- parent - The optional parent QObject.
This function was introduced in Esri::ArcGISRuntime 200.2.
[override virtual]
DynamicEntityDataSource::~DynamicEntityDataSource ()
Destructor.
[protected, since Esri::ArcGISRuntime 200.2]
void DynamicEntityDataSource::addObservation (const Esri::ArcGISRuntime::Geometry &geometry, const QVariantMap &attributes)
Adds or updates the newly-received observation data in the data source store.
- geometry - Geometry of the associated observation. It can be an invalid geometry.
- attributes - The attributes of the associated observation. This can be empty.
This function was introduced in Esri::ArcGISRuntime 200.2.
[override virtual]
void DynamicEntityDataSource::cancelLoad ()
Reimplements: Loadable::cancelLoad().
Cancels loading metadata for the object.
Cancels loading the metadata if the object is loading and always calls doneLoading.
[since Esri::ArcGISRuntime 200.2]
QFuture<void> DynamicEntityDataSource::connectDataSourceAsync ()
Connects to a service that provides dynamic entity observations.
Data does not start streaming from the dynamic entity data source until it's loaded and connected. Once the connection is successfully established, data begins to flow from the stream.
Use this method to explicitly connect to the data source. This call loads the data source if it is not already loaded and then initiates a persistent connection to the service that provides the observation stream. When this method completes, the connectionStatus is set to connected or failed.
Note that a data source connection is initiated implicitly if the data source is contained by a DynamicEntityLayer and added to a map or scene.
This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.
See Working with QFuture for further details.
This function was introduced in Esri::ArcGISRuntime 200.2.
Esri::ArcGISRuntime::Error DynamicEntityDataSource::connectionError () const
Returns the current network connection Error.
This property is empty until an attempt to connect the data source is made. If a connection attempt succeeds, this property is set to empty. If a connection fails, this property contains the platform-specific error.
If maximumReconnectionAttempts is greater than 0, this property will contain the error that caused the data source to lose the connection.
Esri::ArcGISRuntime::ConnectionStatus DynamicEntityDataSource::connectionStatus () const
Returns the current network connection status of the DynamicEntityDataSource.
This property contains the state of the connection throughout the lifetime of the data source. The initial value of this property is ConnectionStatus::Disconnected.
[signal]
void DynamicEntityDataSource::connectionStatusChanged (Esri::ArcGISRuntime::ConnectionStatus connectionStatus )
Signal emitted when the connectionStatus changes.
- connectionStatus - The new connection status.
[override virtual]
Esri::ArcGISRuntime::Credential *DynamicEntityDataSource::credential() const
Reimplements: RemoteResource::credential() const.
Returns the security credentials to access the remote resource.
Only applicable if the resource is secured.
[protected, since Esri::ArcGISRuntime 200.2]
QFuture<void> DynamicEntityDataSource::deleteEntityAsync (const QString &entityId )
Deletes the dynamic entity identified by the id value from the data source store.
- entityId - The value of the unique id field identifying an entity. For example, a track id field value for track-aware data or an object id value for discrete data.
This function was introduced in Esri::ArcGISRuntime 200.2.
[since Esri::ArcGISRuntime 200.2]
QFuture<void> DynamicEntityDataSource::disconnectDataSourceAsync ()
Closes the connection to a service.
This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.
See Working with QFuture for further details.
This function was introduced in Esri::ArcGISRuntime 200.2.
[signal]
void DynamicEntityDataSource::doneLoading (const Esri::ArcGISRuntime::Error &loadError )
Signal emitted when this object is done loading.
- loadError - The Error object.
Note: If there is a load error, it will also be emitted on the errorOccurred
signal.
Esri::ArcGISRuntime::DynamicEntityDataSourceType DynamicEntityDataSource::dynamicEntityDataSourceType () const
Returns the type of dynamic entity data source.
[signal]
void DynamicEntityDataSource::dynamicEntityObservationPurged (Esri::ArcGISRuntime::DynamicEntityObservationInfo *observationInfo )
Signal emitted when a WebSocket purged dynamic entity observations.
- observationInfo - a new DynamicEntityObservationInfo with the details of the event.
Note: Please use RAII techniques to ensure this object is cleaned up after you are done with it. This could be a high frequency event, depending on your data source. The DynamicEntityDataSource will be the QObject parent of the observationInfo object.
This signal will be a no-op if you are not connected to it. No DynamicEntityObservationInfo objects will be created until this signal is connected.
See also Returned QObjects Parenting.
[signal]
void DynamicEntityDataSource::dynamicEntityObservationReceived (Esri::ArcGISRuntime::DynamicEntityObservationInfo *observationInfo )
Signal emitted when a WebSocket received dynamic entity observations.
- observationInfo - a new DynamicEntityObservationInfo with the details of the event.
Note: Please use RAII techniques to ensure this object is cleaned up after you are done with it. This could be a high frequency event, depending on your data source. The DynamicEntityDataSource will be the QObject parent of the observationInfo object.
This signal will be a no-op if you are not connected to it. No DynamicEntityObservationInfo objects will be created until this signal is connected.
See also Returned QObjects Parenting.
[signal]
void DynamicEntityDataSource::dynamicEntityPurged (Esri::ArcGISRuntime::DynamicEntityInfo *info)
Signal emitted when a WebSocket purged a dynamic entity.
- info - a new DynamicEntityInfo with the details of the event.
Note: Please use RAII techniques to ensure this object is cleaned up after you are done with it. This could be a high frequency event, depending on your data source. The DynamicEntityDataSource will be the QObject parent of the info object.
This signal will be a no-op if you are not connected to it. No DynamicEntityInfo objects will be created until this signal is connected.
See also Returned QObjects Parenting.
[signal]
void DynamicEntityDataSource::dynamicEntityReceived (Esri::ArcGISRuntime::DynamicEntityInfo *info)
Signal emitted when a WebSocket received a dynamic entity.
- info - a new DynamicEntityInfo with the details of the event.
Note: Please use RAII techniques to ensure this object is cleaned up after you are done with it. This could be a high frequency event, depending on your data source. The DynamicEntityDataSource will be the QObject parent of the info object.
This signal will be a no-op if you are not connected to it. No DynamicEntityInfo objects will be created until this signal is connected.
See also Returned QObjects Parenting.
[override virtual]
void DynamicEntityDataSource::load()
Reimplements: Loadable::load().
Loads the metadata for the object asynchronously.
Loads the metadata if the object is not loaded and always calls doneLoading.
[override virtual]
Esri::ArcGISRuntime::Error DynamicEntityDataSource::loadError () const
Reimplements: Loadable::loadError() const.
Returns the load error.
See also Error.
[override virtual]
Esri::ArcGISRuntime::LoadStatus DynamicEntityDataSource::loadStatus () const
Reimplements: Loadable::loadStatus() const.
Returns the load status.
See also LoadStatus.
[signal]
void DynamicEntityDataSource::loadStatusChanged (Esri::ArcGISRuntime::LoadStatus loadStatus )
Signal emitted when the load status changes for this object.
- loadStatus - The LoadStatus.
See also Loadable.
int DynamicEntityDataSource::maximumReconnectionAttempts () const
Returns the maximum number of attempts to reconnect after a connection fails.
This property informs the data source to attempt reconnection if a connection is lost. When a connection fails, the data source attempts to reconnect the specified number of times waiting reconnectionInterval between attempts.
If reconnection fails on the final attempt, connectionStatus is set to ConnectionStatus::Failed and the connectionError is set to the platform specific connection error.
The default value is 12. The first 2 connection attempts are made without waiting the specified reconnectionInterval between attempts.
See also setMaximumReconnectionAttempts().
[pure virtual protected, since Esri::ArcGISRuntime 200.2]
QFuture<void> DynamicEntityDataSource::onConnectAsync ()
Handles the connection process of a data source.
Override this method to perform operations that initiate a connection and start the flow of data from an underlying data source. For instance, operations like connecting a websocket, opening a source file, or starting a polling timer are all operations that may be performed in this method.
This method is called by the ArcGIS Maps SDK when the connection is required. This can be due to an explicit call to onConnectAsync or called implicitly when a layer that contains the data source needs to be rendered.
Code in a derived class should throw an error if the connect operation fails. The error is passed back to the data source and is available in the connectionError property.
Canceling the QFuture will not stop this operation from completing, though the QFuture will report that it is canceled and the completion handler will not be called.
See Working with QFuture for further details.
This function was introduced in Esri::ArcGISRuntime 200.2.
[pure virtual protected, since Esri::ArcGISRuntime 200.2]
QFuture<void> DynamicEntityDataSource::onDisconnectAsync ()
Handles the disconnection process of a data source.
Override this method to perform operations that stop the flow of data from an underlying data source.
Canceling the QFuture will not stop this operation from completing, though the QFuture will report that it is canceled and the completion handler will not be called.
See Working with QFuture for further details.
This function was introduced in Esri::ArcGISRuntime 200.2.
[pure virtual protected, since Esri::ArcGISRuntime 200.2]
QFuture<Esri::ArcGISRuntime::DynamicEntityDataSourceInfo *> DynamicEntityDataSource::onLoadAsync ()
Handles the loading process of a data source and returns DynamicEntityDataSourceInfo.
Override this method to populate and return a DynamicEntityDataSourceInfo object. This object defines the schema and metadata used by the internal data cache of the DynamicEntityDataSource. If the returned DynamicEntityDataSourceInfo object does not contain all required values, the data source will fail to load and will not be usable.
This method is called by the ArcGIS Maps SDK when loading is required. This can be due to an explicit call to load the data source using Loadable::load or called implicitly when a layer that contains the data source needs to be rendered.
Code in a derived class should throw an error if the load operation fails. The error is passed back to the data source and is available in the loadError property.
Canceling the QFuture will not stop this operation from completing, though the QFuture will report that it is canceled and the completion handler will not be called.
See Working with QFuture for further details.
This function was introduced in Esri::ArcGISRuntime 200.2.
[since Esri::ArcGISRuntime 200.2]
QFuture<void> DynamicEntityDataSource::purgeAllAsync ()
Removes all dynamic entities from the data source as well as from the map or scene.
Sometimes, the number of dynamic entities can crowd the display and make information hard to interpret. You can clear (purge) all dynamic entities to remove stale information and limit the amount of memory consumed. This does not unsubscribe the app from the service, so new dynamic entities will continue to display as they become available.
This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.
See Working with QFuture for further details.
This function was introduced in Esri::ArcGISRuntime 200.2.
Esri::ArcGISRuntime::DynamicEntityDataSourcePurgeOptions *DynamicEntityDataSource::purgeOptions () const
Returns a DynamicEntityDataSourcePurgeOptions that defines when observations are purged from the local data cache.
Data received from the DynamicEntityDataSource is stored in memory on the client and can grow quickly depending on the number of dynamic entities and frequency of updates. If purge options are not set appropriately, a data source may store too many observations in its local data cache and cause performance and memory issues for the application. Use the purgeOptions property to control app data storage for the local cache.
This property must be set before loading the data source and cannot be changed once the data source is loaded.
By default, purge options are set to remove observations from the data cache when a maximum limit of 100,000 observations is reached.
Note that you can clear all observations from the cache using purgeAllAsync. This clears all data from the local data cache, but does not disconnect from the stream. Dynamic entities and observations will continue to be added to the local data cache as they come from the stream.
double DynamicEntityDataSource::reconnectionInterval () const
Returns the time (in seconds) to wait between attempts to reconnect.
This property sets the amount of time delay between reconnection attempts after a connection fails. The default value is 10 seconds.
See also setReconnectionInterval() and maximumReconnectionAttempts.
[override virtual]
Esri::ArcGISRuntime::RequestConfiguration DynamicEntityDataSource::requestConfiguration () const
Reimplements: RemoteResource::requestConfiguration() const.
Returns the RequestConfiguration used to customize the request to this RemoteResource.
See also setRequestConfiguration().
[override virtual]
void DynamicEntityDataSource::retryLoad ()
Reimplements: Loadable::retryLoad().
Loads or retries loading metadata for the object asynchronously.
Will retry loading the metadata if the object is failed to load. Will load the object if it is not loaded. Will not retry to load the object if the object is loaded. Will always call the done loading signal if this is called.
[protected, since Esri::ArcGISRuntime 200.2]
void DynamicEntityDataSource::setConnectionFailed (const QString &userDefinedError , bool reconnect)
Sets the error when the connection fails and may attempt to reconnect.
- userDefinedError - The error message that was encountered during connection failure.
- reconnect - Indicates whether reconnection should be attempted after failure.
Use this method when an established connection is interrupted. Pass the error message that caused the connection to fail and a flag that indicates whether to attempt reconnection.
This function was introduced in Esri::ArcGISRuntime 200.2.
[protected, since Esri::ArcGISRuntime 200.2]
void DynamicEntityDataSource::setConnectionStatusAndError (Esri::ArcGISRuntime::ConnectionStatus status, const QString &userDefinedError = "", bool reconnect = false)
Sets the connection status and error.
- status - The connection status.
- userDefinedError - The user defined error message.
- reconnect - Indicates whether reconnection should be attempted.
This function was introduced in Esri::ArcGISRuntime 200.2.
[protected, since Esri::ArcGISRuntime 200.2]
void DynamicEntityDataSource::setLoadInfoAndError (Esri::ArcGISRuntime::DynamicEntityDataSourceInfo *dynamicEntityDataSourceInfo , const QString &userDefinedError = "")
Sets the load info object and error.
- dynamicEntityDataSourceInfo - The metadata of the DynamicEntityDataSource.
- userDefinedError - The user defined error message.
This function was introduced in Esri::ArcGISRuntime 200.2.
void DynamicEntityDataSource::setMaximumReconnectionAttempts (int maximumReconnectionAttempts )
Sets the maximumReconnectionAttempts to maximumReconnectionAttempts.
See also maximumReconnectionAttempts.
void DynamicEntityDataSource::setReconnectionInterval (double reconnectionInterval )
Sets the reconnectionInterval to reconnectionInterval.
See also reconnectionInterval.
[override virtual]
void DynamicEntityDataSource::setRequestConfiguration (const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration )
Reimplements: RemoteResource::setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration).
Sets the RequestConfiguration, which is used to customize the request to this RemoteResource, to requestConfiguration.
See also requestConfiguration().
[override virtual]
QUrl DynamicEntityDataSource::url() const
Reimplements: RemoteResource::url() const.
Returns the URL of the dynamic entity data source.