Package com.inductiveautomation.historian.gateway.api

Interface Historian<S extends HistorianSettings>

Type Parameters:
S - The type parameter that extends HistorianSettings, representing the specific settings of the historian.
All Known Subinterfaces:
TagHistoryProvider<S>
All Known Implementing Classes:
AbstractHistorian, CsvHistorian, HistorySplitterProvider, QuestDBHistorian, RemoteHistorianProvider, SimulatorHistorian, SQLiteHistorian, WideDbHistoryProvider
public interface Historian<S extends HistorianSettings>
Defines the contract for a historian, which manages the storage, query, and lifecycle of historical data. A historian is responsible for handling historical data operations, including adapting paths, processing queries, and managing storage engines. This interface provides core functionalities that can be implemented or extended for custom historian behaviors.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    getName()
    Retrieves the name of the historian.
    default QualifiedPathAdapter
    getPathAdapter()
    Retrieves the QualifiedPathAdapter instance used for normalizing QualifiedPath objects.
    default Optional<QueryEngine>
    getQueryEngine()
    Retrieves the interface for querying historical data.
    S
    getSettings()
    Retrieves the settings associated with the historian.
    ProfileStatus
    getStatus()
    Retrieves the current status of the historian.
    default Optional<StorageEngine>
    getStorageEngine()
    Retrieves the interface for managing historical data storage.
    default boolean
    handleNameChange(String newName)
    Handles a change in the historian's name and determines if the change can be dynamically applied without requiring a complete restart or replacement of the historian.
    default boolean
    handleSettingsChange(S newSettings)
    Handles a change in the historian's settings and determines if the change can be dynamically applied without requiring a complete restart or replacement of the historian.
    void
    shutdown()
    Shuts down the historian and any associated resources.
    void
    startup()
    Starts the historian and initializes any necessary resources required for its operation.

  • Method Details

    • startup

      void startup() throws Exception
      Starts the historian and initializes any necessary resources required for its operation. This method is responsible for setting up the internal state of the historian and preparing it to handle incoming requests or data processing.

      Implementations may include the following operations: - Allocating and initializing required resources. - Establishing connections to external systems or storage backends. - Setting up any internal scheduling or maintenance tasks.

      If this method is invoked when the historian is already started, an IllegalStateException may be thrown to prevent duplicate initialization.

      Throws:
      Exception - if an error occurs during the startup process.

    • shutdown

      void shutdown()
      Shuts down the historian and any associated resources. This method is responsible for ensuring that the historian ceases operations cleanly and releases any allocated resources. Once invoked, the historian should no longer accept or process new requests.

      Implementations may include tasks such as: - Stopping active data processing tasks. - Freeing up connections to external systems or storage. - Logging a shutdown message for diagnostic or auditing purposes.

      If this method is overridden in a subclass, it is recommended to call the superclass implementation to ensure proper cleanup behavior.

    • getName

      String getName()
      Retrieves the name of the historian.
      Returns:
      the name of the historian as a String

    • getSettings

      S getSettings()
      Retrieves the settings associated with the historian. The returned settings provide configuration details specific to the historian's operation.
      Returns:
      an instance of S representing the settings of the historian

    • getStatus

      ProfileStatus getStatus()
      Retrieves the current status of the historian.
      Returns:
      the current ProfileStatus, indicating the general state and optional message describing the historian's operational state.

    • getQueryEngine

      default Optional<QueryEngine> getQueryEngine()
      Retrieves the interface for querying historical data. By default, this method returns an empty Optional, indicating that no QueryEngine is provided.
      Returns:
      An Optional containing the QueryEngine instance, or an empty Optional if none is available.

    • getStorageEngine

      default Optional<StorageEngine> getStorageEngine()
      Retrieves the interface for managing historical data storage. By default, this method returns an empty Optional, indicating that no StorageEngine is provided.
      Returns:
      An Optional containing the StorageEngine instance, or an empty Optional if none is available.

    • getPathAdapter

      default QualifiedPathAdapter getPathAdapter()
      Retrieves the QualifiedPathAdapter instance used for normalizing QualifiedPath objects. By default, this method returns the QualifiedPathAdapter.DEFAULT.
      Returns:
      the QualifiedPathAdapter instance used for path normalization

    • handleNameChange

      default boolean handleNameChange(String newName)
      Handles a change in the historian's name and determines if the change can be dynamically applied without requiring a complete restart or replacement of the historian.
      Parameters:
      newName - The new name to be applied to the historian.
      Returns:
      true if the historian successfully applied the name change dynamically. false if the historian doesn't support applying the name dynamically and requires a new instance with the updated name or a restart.

    • handleSettingsChange

      default boolean handleSettingsChange(S newSettings)
      Handles a change in the historian's settings and determines if the change can be dynamically applied without requiring a complete restart or replacement of the historian.
      Parameters:
      newSettings - The new settings to be applied to the historian. This parameter represents an instance of the historian's settings class.
      Returns:
      true if the historian successfully applied the settings change dynamically. false if the historian doesn't support applying the settings dynamically and requires a new instance with the updated settings or a restart.