Package com.inductiveautomation.ignition.gateway.storeforward.sinks

Class AbstractSink<T extends PersistentData>

java.lang.Object
com.inductiveautomation.ignition.gateway.storeforward.sinks.AbstractSink<T>
Type Parameters:
T - a subclass of PersistentData
All Implemented Interfaces:
DataConsumer<T>, DataSink<T>
Direct Known Subclasses:
AbstractDatasourceSink, com.inductiveautomation.ignition.gateway.storeforward.sinks.AbstractRemoteSink, TagHistoryDataSinkBridge
public abstract class AbstractSink<T extends PersistentData> extends Object implements DataSink<T>
The abstract base class for all data sinks.

  • Field Details

  • Constructor Details

  • Method Details

    • startup

      public final void startup()
      Starts the data sink by transitioning its status to SinkStatus.STARTED and invoking any additional startup logic specific to the sink.

      If the status update to STARTED is successful, a log message is generated at the debug level, indicating that the sink is beginning its startup process. The method then calls onStartup(), a lifecycle hook that subclasses can implement to define custom startup behavior.

      This method is thread-safe due to the use of synchronization, ensuring that only one thread can execute the startup sequence at any given time.

      If any unexpected exceptions are thrown during the startup process (including from onStartup()), they will be caught and handled by transitioning the sink to SinkStatus.FAULTED state. The exception will be logged and stored as the fault error, leaving the sink in a faulted state rather than an inconsistent state.

      Specified by:
      startup in interface DataSink<T extends PersistentData>

    • onStartup

      protected void onStartup()
      This method is a synchronized lifecycle hook intended to be implemented or overridden by subclasses of AbstractSink. It is invoked during the startup phase of the data sink.

      Subclasses can implement this method to define specific behavior that should occur when the sink becomes active, such as initializing resources, registering metrics, or preparing underlying systems. This method is invoked within the startup() method.

      It is thread-safe due to the use of synchronization and ensures that only one thread can execute this method at any given time.

      Any exceptions thrown from this method will be caught and handled by the startup process, causing the sink to transition to SinkStatus.FAULTED state. The exception will be logged and stored as the fault error, ensuring the sink does not remain in an inconsistent state.

    • initialize

      protected final void initialize()
      Initializes the data sink by transitioning its status to SinkStatus.INITIALIZING, performing custom initialization logic, and transitioning to SinkStatus.ACCEPTING upon successful initialization.

      This method is synchronized to ensure thread safety, allowing only one thread to execute the initialization process at any given time. It first attempts to update the sink's status to INITIALIZING. If the status update is successful, a debug log message is generated, indicating that the sink is being initialized.

      During initialization, the onInitialize() method is invoked, allowing subclasses to define specific setup behavior required for the sink. Any exceptions thrown by onInitialize() are caught and handled by calling onFailure(Exception), which logs the error, sets the sink status to SinkStatus.FAULTED, and stores the exception as the fault error. If no exceptions are thrown and no faults are encountered (monitored via the faultError field), the status of the sink is transitioned to ACCEPTING.

      Subclasses implementing custom logic within the onInitialize() method can throw exceptions to signal initialization failures. These exceptions will be properly handled and will cause the sink to fault rather than progress to an operational state.

    • onInitialize

      protected void onInitialize() throws Exception
      Synchronized lifecycle hook intended to be implemented or overridden by subclasses to perform initialization tasks specific to the sink. This method is invoked during the initialization phase of the sink's lifecycle.

      Subclasses can use this method to define custom logic for setting up resources, configurations, or other components necessary for the sink to function properly. The method is designed to ensure that only one thread can execute it at any given time due to synchronization.

      Any exceptions thrown from this method will be handled by the initialization process and will cause the sink to fault. When an exception is thrown, the sink's status will be set to SinkStatus.FAULTED and the exception will be logged and stored as the fault error.

      Throws:
      Exception - if an unhandled exception is thrown during initialization

    • uninitialize

      protected final void uninitialize()
      Uninitializes the data sink by transitioning its status to SinkStatus.UNINITIALIZED and invoking any subclass-specific teardown logic defined in onUninitialize().

      If the status update to SinkStatus.UNINITIALIZED is successful, a debug log message is generated indicating that the data sink is being uninitialized. The method then calls onUninitialize(), a lifecycle hook for performing cleanup tasks or releasing resources.

      This method is thread-safe due to the use of synchronization, ensuring that only one thread can execute the uninitialization process at any given time.

      Subclasses overriding onUninitialize() should ensure that no unhandled exceptions are thrown, as such failures could disrupt the uninitialization process and leave the data sink in an inconsistent state.

    • onUninitialize

      protected void onUninitialize()
      Synchronized lifecycle hook intended to be implemented or overridden by subclasses of AbstractSink to define custom teardown or cleanup operations that should occur during the uninitialization phase of the sink's lifecycle.

      This method is invoked by the uninitialize() method and provides a safe point for releasing resources, deregistering metrics, or any other tasks necessary to prepare the sink for deactivation or shutdown.

      Subclasses overriding this method should ensure no unhandled exceptions are thrown, as this could disrupt the uninitialization process. Due to synchronization, it is guaranteed that only one thread will execute this method at a time.

    • shutdown

      public final void shutdown()
      Shuts down the data sink by transitioning its status to SinkStatus.STOPPED and invoking any subclass-specific shutdown logic defined in onShutdown().

      If the status update to STOPPED is successful, a debug log message is generated, indicating that the sink is shutting down. The method then calls onShutdown(), a lifecycle hook that subclasses can implement to define custom shutdown behavior.

      This method is thread-safe due to the use of synchronization, ensuring that only one thread can execute the shutdown sequence at any given time.

      Subclasses overriding onShutdown() should ensure that no unhandled exceptions are thrown, as such failures may disrupt the shutdown process and leave the data sink in an inconsistent state.

      Specified by:
      shutdown in interface DataSink<T extends PersistentData>

    • onShutdown

      protected void onShutdown()
      Synchronized lifecycle hook intended to be implemented or overridden by subclasses of AbstractSink to define custom behavior that should occur during the shutdown phase of the sink's lifecycle.

      This method is invoked within the shutdown() method and provides a safe point for performing cleanup or resource release tasks. Subclasses can use this method to deregister metrics, close connections, or perform other operations needed to gracefully shut down the sink.

      Due to synchronization, it ensures that only one thread can execute this method at any given time. Subclasses overriding this method should ensure that no unhandled exceptions are thrown, as this could disrupt the shutdown process.

    • onFailure

      protected void onFailure(Exception exception)
      Handles a critical failure encountered by the data sink. This method is synchronized to ensure thread safety when logging an error, updating the status of the sink, and setting the fault error.
      Parameters:
      exception - the Exception representing the critical failure encountered

    • isAccepting

      public boolean isAccepting()
      Description copied from interface: DataSink
      Determines whether the data sink is currently accepting data.
      Specified by:
      isAccepting in interface DataSink<T extends PersistentData>
      Returns:
      true if the data sink is accepting data, false otherwise

    • getWriter

      public BatchWriter<T> getWriter()
      Description copied from interface: DataSink
      Gets a writer object for writing to the data sink. This can be used for batching data together when writing.
      Specified by:
      getWriter in interface DataSink<T extends PersistentData>
      Returns:
      a BatchWriter object for writing to the data sink

    • getInfo

      public DataSinkInformation getInfo()
      Description copied from interface: DataSink
      Returns descriptive information about this data sink.
      Specified by:
      getInfo in interface DataSink<T extends PersistentData>
      Returns:
      the descriptive information pertaining to this data sink

    • getSupportedFlavor

      public PersistentFlavor<T> getSupportedFlavor()
      Description copied from interface: DataSink
      Returns the flavor of data that the data sink supports.
      Specified by:
      getSupportedFlavor in interface DataSink<T extends PersistentData>
      Returns:
      a PersistentFlavor object representing the supported flavor

    • validateFlavor

      public QualityCode validateFlavor(PersistentFlavor<?> flavor)
      Description copied from interface: DataConsumer
      Validates a given PersistentFlavor. The default implementation always gives an uncertain quality code.
      Specified by:
      validateFlavor in interface DataConsumer<T extends PersistentData>
      Parameters:
      flavor - The flavor to be validated
      Returns:
      A QualityCode denoting the evaluated quality of the flavor. By default, returns QualityCode.Uncertain.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getStorageId

      public StorageId getStorageId()

    • getFaultError

      public Optional<Exception> getFaultError()

    • getContext

      protected GatewayContext getContext()
      Returns the GatewayContext within this data sink.
      Returns:
      the gateway context

    • getMetricPrefix

      protected String getMetricPrefix()
      Returns the metric prefix to be used for the metrics registered to the metric registry.
      Returns:
      the string metric prefix for registering metrics to metric registry

    • getLogger

      protected LoggerEx getLogger()
      Returns the LoggerEx instance that can be used to log messages. If the logger hasn't yet been defined, one will be created using createLogger().
      Returns:
      the LoggerEx instance to be used for logging messages

    • createLogger

      protected LoggerEx createLogger()
      Creates and returns a new LoggerEx instance to be used for this sink.
      Returns:
      a LoggerEx instance for this sink

    • getName

      protected String getName()
      Returns the name of the sink.
      Returns:
      the name of the sink

    • markStoreMetric

      protected void markStoreMetric(int count)
      Marks a Meter for the data amount stored in this data sink.
      Parameters:
      count - the data amount to mark as stored

    • updateStatus

      protected boolean updateStatus(SinkStatus status)
      Updates the current status of the sink to the provided value. If the new status differs from the previous status, the change is captured.
      Parameters:
      status - the new SinkStatus to set for the sink
      Returns:
      true if the new status differs from the previous status, false otherwise

    • getTypeDescription

      @Nonnull protected abstract LocalizedString getTypeDescription()