Package com.here.sdk.warner

Class WarnerEngine

java.lang.Object
com.here.NativeBase
com.here.sdk.warner.WarnerEngine
All Implemented Interfaces:
ElectronicHorizonListener
public final class WarnerEngine extends NativeBase implements ElectronicHorizonListener

Provides the core functionality for generating and managing navigation warnings.

WarnerEngine processes Electronic Horizon data and determines when various types of warnings should be issued. It is used with ElectronicHorizonListener, which supply the road topology and positional updates required for warning evaluation.

The engine monitors enabled warning types and notifies registered listeners when new warnings become available.

Note: This is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

  • Constructor Details

    • WarnerEngine

      public WarnerEngine(@NonNull List<WarningType> enabledWarnings) throws InstantiationErrorException

      Creates a new instance of this class.

      Parameters:
      enabledWarnings -

      The list of warning types that should be monitored and processed by the engine. Only warnings of these types will be generated.

      Throws:
      InstantiationErrorException -

      Indicates what went wrong when the instantiation was attempted.

    • WarnerEngine

      public WarnerEngine(@NonNull SDKNativeEngine sdkEngine, @NonNull List<WarningType> enabledWarnings) throws InstantiationErrorException

      Creates a new instance of this class.

      Parameters:
      sdkEngine -

      A SDKEngine instance.

      enabledWarnings -

      The list of warning types that should be monitored and processed by the engine. Only warnings of these types will be generated.

      Throws:
      InstantiationErrorException -

      Indicates what went wrong when the instantiation was attempted.

    • WarnerEngine

      public WarnerEngine(@NonNull SDKNativeEngine sdkEngine, @NonNull WallClock wallClock, @NonNull List<WarningType> enabledWarnings) throws InstantiationErrorException

      Creates a new instance of this class.

      Parameters:
      sdkEngine -

      A SDKEngine instance.

      wallClock -

      A WallClock instance.

      enabledWarnings -

      The list of warning types that should be monitored and processed by the engine. Only warnings of these types will be generated.

      Throws:
      InstantiationErrorException -

      Indicates what went wrong when the instantiation was attempted.

  • Method Details

    • addEnabledWarnings

      public void addEnabledWarnings(@NonNull List<WarningType> warningTypes)

      Adds the given warning types to the set of warnings monitored by the engine.

      After this call, the engine will begin generating warnings for all types included in warningTypes, in addition to those that are already enabled.

      Parameters:
      warningTypes -

      Warning types to be added to the engine's active monitoring set.

    • removeEnabledWarnings

      public void removeEnabledWarnings(@NonNull List<WarningType> warningTypes)

      Removes the given warning types from the set of warnings monitored by the engine.

      After this call, the engine will stop generating warnings for all types included in warningTypes, while other enabled types remain unaffected.

      Parameters:
      warningTypes -

      Warning types to be removed from the engine's active monitoring set.

    • setEnabledWarnings

      public void setEnabledWarnings(@NonNull List<WarningType> warningTypes)

      Replaces the current set of enabled warning types with the provided list.

      After this call, the engine will monitor and generate warnings only for types included in warningTypes.

      Parameters:
      warningTypes -

      The complete new set of warning types the engine should track.

    • getEnabledWarnings

      @NonNull public List<WarningType> getEnabledWarnings()

      Returns the current list of enabled warning types. If the WarnerEngine was retrieved from the Navigator, it will also contain all the warnings enabled for which listeners are set.

      Returns:

      The currect list instance.

    • addWarningListener

      public void addWarningListener(@NonNull WarningListener warningListener)

      Registers a listener that will receive warning notifications.

      Parameters:
      warningListener -

      The listener instance that should be notified when new warnings are generated.

    • removeWarningListener

      public void removeWarningListener(@NonNull WarningListener warningListener)

      Unregisters a previously added warning listener.

      Parameters:
      warningListener -

      The listener instance that should no longer receive warning notifications.

    • getWarningsRegistry

      @NonNull public WarningsRegistry getWarningsRegistry()

      Returns the centralized access point for retrieving full metadata of any supported warning category (e.g., safety cameras, truck restrictions, etc.). WarningsRegistry class exposes getter methods, each returning the detailed warning object for the given identifier. Use this getter to look up complete warning information by its id, as provided through WarningListener.onWarning.

      Returns:

      The centralized WarningsRegistry instance.

    • getWarningNotificationDistances

      @NonNull public WarningNotificationDistances getWarningNotificationDistances(@NonNull WarningType warningType)

      Returns the warning notification distances for the requested warning type.

      Note: WarningType.CUSTOM is not a valid value for this method. Use getCustomWarningNotificationDistances(int) to retrieve distances for a specific custom warning type.

      Parameters:
      warningType -

      The warning type for which the notification distances will be returned. Must not be WarningType.CUSTOM.

      Returns:

      The warning notification distances for the given warningType. If warningType is WarningType.CUSTOM, a default WarningNotificationDistances value is returned.

    • setWarningNotificationDistances

      public void setWarningNotificationDistances(@NonNull WarningType warningType, @NonNull WarningNotificationDistances warningNotificationDistances)

      Sets the warning notification distances for the specified warning type.

      Note: WarningType.CUSTOM is not a valid value for this method. Use setCustomWarningNotificationDistances(int, com.here.sdk.navigation.WarningNotificationDistances) to configure distances for a specific custom warning type.

      Parameters:
      warningType -

      The warning type for which the warning notification distances will be set. Must not be WarningType.CUSTOM.

      warningNotificationDistances -

      The warning notification distances to be set for the specified warning type.

    • getCustomWarningNotificationDistances

      @NonNull public WarningNotificationDistances getCustomWarningNotificationDistances(int customWarningType)

      Returns the warning notification distances for the specified custom warning type.

      Unlike getWarningNotificationDistances(com.here.sdk.navigation.WarningType), which operates on a WarningType, this method targets a specific custom warning category identified by customWarningType, as defined in CustomWarning.customWarningType and Warning.customWarningType.

      Parameters:
      customWarningType -

      The identifier of the custom warning type for which the notification distances are requested.

      Returns:

      The warning notification distances configured for the given customWarningType. If no distances have been explicitly set for this type, a default WarningNotificationDistances value is returned.

      Note: This is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

    • setCustomWarningNotificationDistances

      public void setCustomWarningNotificationDistances(int customWarningType, @NonNull WarningNotificationDistances warningNotificationDistances)

      Sets the warning notification distances for the specified custom warning type.

      Unlike setWarningNotificationDistances(com.here.sdk.navigation.WarningType, com.here.sdk.navigation.WarningNotificationDistances), which applies settings to a WarningType, this method allows configuring notification distances independently for each custom warning category identified by customWarningType, as defined in CustomWarning.customWarningType and Warning.customWarningType.

      Parameters:
      customWarningType -

      The identifier of the custom warning type for which the notification distances should be set.

      warningNotificationDistances -

      The warning notification distances to be applied for the specified customWarningType.

      Note: This is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

    • finalizeGivenWarnings

      public void finalizeGivenWarnings()

      Marks all currently active warnings as passed (DistanceType.PASSED), notifies all registered WarningListener instances on the main thread, and then clears these warnings from their corresponding registries by invoking the appropriateWarningsRegistry.clear<Type> methods.

      This method triggers notifications only for enabled warners. Warning processing may occur asynchronously unless synchronous mode is enabled.

      Note: Although each warning type can also be cleared manually via the respective WarningsRegistry.clear<Type>() methods, finalizeGivenWarnings() provides a unified way to flush all active warnings after they have been reported as passed. If this method is not invoked, warnings will continue to accumulate in the registry according to the configured warning-generation options.

    • addCustomWarningProvider

      public void addCustomWarningProvider(@NonNull CustomWarningProvider customWarningProvider, @NonNull SegmentDataLoaderOptions segmentDataLoaderOptions)

      Registers a custom warning provider.

      The registered provider participates in warning evaluation and is invoked to generate custom warnings based on the current vehicle position.

      Parameters:
      customWarningProvider -

      A provider responsible for generating custom warnings.

      segmentDataLoaderOptions -

      Specifies which data should be loaded by the SegmentDataLoader.

      Note: This is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

    • removeCustomWarningProvider

      public void removeCustomWarningProvider(@NonNull CustomWarningProvider customWarningProvider)

      Unregisters a custom warning provider.

      After removal, the provider will no longer participate in warning evaluation and will not generate custom warnings.

      Parameters:
      customWarningProvider -

      The provider to be removed.

      Note: This is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

    • clearCustomWarningProviders

      public void clearCustomWarningProviders()

      Unregisters all custom warning providers.

      After this call, no custom warning providers will participate in warning evaluation until new providers are registered.

      Note: This is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

    • getWarningOptions

      @NonNull public WarningOptions getWarningOptions()

      Gets the currently configured WarningOptions.

      Provides configuration parameters for all the warners.

      Returns:

      Options that define warning behavior for all the warners.

    • setWarningOptions

      public void setWarningOptions(@NonNull WarningOptions value)

      Sets the WarningOptions and updates the configuration for all the warners.

      Provides configuration parameters for all the warners.

      Parameters:
      value -

      Options that define warning behavior for all the warners.

    • getTimingProfile

      @NonNull public TimingProfile getTimingProfile()

      Gets the currently configured TimingProfile.

      Configures the base notification thresholds used for delivering navigation warnings. The effective thresholds depend on the selected TimingProfile and may adjust automatically according to the current speed limit:

      Note: Custom threshold values can be set, but these timing-profile rules will still apply.

      Returns:

      The timing profile that defines when navigation warnings should be triggered.

    • setTimingProfile

      public void setTimingProfile(@NonNull TimingProfile value)

      Sets the TimingProfile of the current position.

      Configures the base notification thresholds used for delivering navigation warnings. The effective thresholds depend on the selected TimingProfile and may adjust automatically according to the current speed limit:

      Note: Custom threshold values can be set, but these timing-profile rules will still apply.

      Parameters:
      value -

      The timing profile that defines when navigation warnings should be triggered.

    • onElectronicHorizonUpdated

      public void onElectronicHorizonUpdated(@Nullable ElectronicHorizonErrorCode errorCode, @Nullable ElectronicHorizonUpdate update)

      Called whenever the electronic horizon subsystem produces:

      • a new update,
      • an error,

      The client must inspect error_code to determine whether the call represents an error or a valid update.

      Specified by:
      onElectronicHorizonUpdated in interface ElectronicHorizonListener
      Parameters:
      errorCode -

      The error associated with the horizon computation. null means no error.

      update -

      The update describing the current electronic horizon state. May be null if an update could not be produced.

      Note: This is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.