DynamicEntityDataSource Class

  • DynamicEntityDataSource
  • class Esri::ArcGISRuntime::DynamicEntityDataSource

    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:

    Esri::ArcGISRuntime::ArcGISStreamService

    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:

    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 nullptr until an attempt to connect the data source is made. If a connection attempt succeeds, this property is set to nullptr. 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 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.

    See also Loadable and Object.

    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.

    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.

    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.

    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.

    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.

    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 connect 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.

    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.

    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.

    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.

    Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.