Package energy.trolie.client

Interface TrolieClient

All Superinterfaces:
AutoCloseable, Closeable
public interface TrolieClient extends Closeable

Primary TROLIE client access interface. Represents configured access to a single TROLIE server. Should be used as a singleton within applications, at least for each TROLIE endpoint used by a given application.

Users should note that the TrolieClient is optimized for performance, particularly for users with large data sets. Therefore, most operations use a streaming approach for receipt of data components, rather than force applications to keep entire structures in memory at once.

Using TrolieClient Methods

For consistency, the TrolieClient API uses the same patterns regardless of the size of the data users may be using. These patterns always use reactive-style callbacks, and typically involve streaming mechanisms for breaking each payload into logical slices. This may be more difficult to program for users, but helps ensure that users of the SDK are more likely to have successful implementations, even as data sizes increase.

The methods below make use of the following common constructs:

  • StreamingResponseReceivers are callbacks to get data from the TROLIE server. Instead of returning the entire payload of response in memory, the receivers will have various methods that are invoked as parsed data is returned. API users must implement these interfaces to receive data. This follows a similar pattern to event-based parsing systems, popularized most in Java by the SAX XML parser.
  • RequestSubscriptions are returned from methods that set up a polling loop within the client. The TROLIE client implements the mechanics under the hood to poll for TROLIE servers using Conditional GETs, and will then notify associated StreamingResponseReceivers as new data is returned. These subscriptions may be managed using the unsubscribe(RequestSubscription) and unsubscribeAll() methods.
  • StreamingUpdates are the inverse of the receivers. Rather than send entire payloads at once in a giant in-memory structure, these classes allow the API user to send the data in small chunks and stream it out. Each StreamingUpdate assumes that its methods are invoked in a particular order matching the structure of the TROLIE operation being invoked.
See Also:

  • Method Details

    • getMonitoringSet

      void getMonitoringSet(@NonNull @NonNull MonitoringSetsReceiver receiver, @NonNull @NonNull String monitoringSet)
      Synchronously fetch the definition of a monitoring set.
      Parameters:
      receiver - receiver for monitoring set contents.
      monitoringSet - monitoring set identifier.

    • subscribeToMonitoringSetUpdates

      RequestSubscription subscribeToMonitoringSetUpdates(MonitoringSetsSubscribedReceiver receiver, String monitoringSet)
      Create a polling subscription for updates to the given monitoring set.
      Parameters:
      receiver - receives updates to the monitoring set as they occur. Note that these invocations will be on the polling thread, so long-running operations will block additional polls for data update.
      monitoringSet - the monitoring set identifier to poll for
      Returns:
      handle to the request.

    • getDefaultMonitoringSet

      void getDefaultMonitoringSet(MonitoringSetsReceiver receiver)
      Identical to getMonitoringSet(MonitoringSetsReceiver, String), but simply fetches this grid operator's default monitoring set rather than one specified with a particular name.
      Parameters:
      receiver - receiver for the monitoring set

    • subscribeToDefaultMonitoringSetUpdates

      RequestSubscription subscribeToDefaultMonitoringSetUpdates(MonitoringSetsSubscribedReceiver receiver)
      Identical to subscribeToMonitoringSetUpdates(MonitoringSetsSubscribedReceiver, String), but creates a polling subscription for this grid operator's default monitoring set rather than one specified with a particular name.
      Parameters:
      receiver - receives updates to the monitoring set as they occur. Note that these invocations will be on the polling thread, so long-running operations will block additional polls for data update.
      Returns:
      handle to the request.

    • getInUseLimitForecasts

      void getInUseLimitForecasts(ForecastSnapshotReceiver receiver)
      Execute a synchronous request for the current forecast limits with a streaming response handler, assuming this user's default monitoring set.
      Parameters:
      receiver - Streaming data receiver for snapshot data

    • getInUseLimitForecasts

      void getInUseLimitForecasts(ForecastSnapshotReceiver receiver, String monitoringSet)
      Execute a request for the current forecast limits with a streaming response handler with the given monitoring set.
      Parameters:
      receiver - Streaming data receiver for snapshot data
      monitoringSet - filter for monitoring set name

    • getInUseLimitForecasts

      void getInUseLimitForecasts(ForecastSnapshotReceiver receiver, Instant offsetPeriodStart, Instant periodEnd)
      Execute a request for the current forecast limits with a streaming response handler, given this user's default monitoring set.
      Parameters:
      receiver - Streaming data receiver for snapshot data
      offsetPeriodStart - Optional. Only periods starting at or after this date will be returned.
      periodEnd - Optional. Only periods starting before this date will be returns If periodStart is not given, all available periods starting before this date will be returned.

    • getInUseLimitForecasts

      void getInUseLimitForecasts(ForecastSnapshotReceiver receiver, String monitoringSet, String resourceId, Instant offsetPeriodStart, Instant periodEnd)
      Execute a request for the current forecast limits with a streaming response handler
      Parameters:
      receiver - Streaming data receiver for snapshot data
      monitoringSet - filter for monitoring set name
      resourceId - Only return limits for this power system resource
      offsetPeriodStart - Optional. Only periods starting at or after this date will be returned.
      periodEnd - Optional. Only periods starting before this date will be returns If periodStart is not given, all available periods starting before this date will be returned.

    • subscribeToInUseLimitForecastUpdates

      RequestSubscription subscribeToInUseLimitForecastUpdates(ForecastSnapshotSubscribedReceiver receiver, String monitoringSet)
      Create a polling subscription for forecast snapshot data updates
      Parameters:
      receiver - Streaming data receiver for snapshot data
      monitoringSet - filter for monitoring set name
      Returns:
      request handle

    • subscribeToInUseLimitForecastUpdates

      RequestSubscription subscribeToInUseLimitForecastUpdates(ForecastSnapshotSubscribedReceiver receiver)
      Create a polling subscription for forecast snapshot data updates
      Parameters:
      receiver - Streaming data receiver for snapshot data
      Returns:
      request handle

    • getRegionalLimitsForecast

      void getRegionalLimitsForecast(ForecastSnapshotReceiver receiver)
      Execute a request for the current forecast limits with a streaming response handler
      Parameters:
      receiver - Streaming data receiver for snapshot data

    • getRegionalLimitsForecast

      void getRegionalLimitsForecast(ForecastSnapshotReceiver receiver, String monitoringSet)
      Execute a request for the regionally limiting forecast limits with a streaming response handler
      Parameters:
      receiver - Streaming data receiver for snapshot data
      monitoringSet - filter for monitoring set name

    • getRegionalLimitsForecast

      void getRegionalLimitsForecast(ForecastSnapshotReceiver receiver, Instant offsetPeriodStart, Instant periodEnd)
      Execute a request for the regionally limiting forecast limits with a streaming response handler
      Parameters:
      receiver - Streaming data receiver for snapshot data
      offsetPeriodStart - Optional. Only periods starting at or after this date will be returned.
      periodEnd - Optional. Only periods starting before this date will be returns If periodStart is not given, all available periods starting before this date will be returned.

    • getRegionalLimitsForecast

      void getRegionalLimitsForecast(ForecastSnapshotReceiver receiver, String monitoringSet, String resourceId, Instant offsetPeriodStart, Instant periodEnd)
      Execute a request for the regionally limiting forecast limits with a streaming response handler
      Parameters:
      receiver - Streaming data receiver for snapshot data
      monitoringSet - filter for monitoring set name
      resourceId - Only return limits for this power system resource
      offsetPeriodStart - Optional. Only periods starting at or after this date will be returned.
      periodEnd - Optional. Only periods starting before this date will be returns If periodStart is not given, all available periods starting before this date will be returned.

    • subscribeToRegionalLimitsForecast

      RequestSubscription subscribeToRegionalLimitsForecast(ForecastSnapshotSubscribedReceiver receiver)
      Create a polling subscription for regionally limiting forecast snapshot data updates
      Parameters:
      receiver - Streaming data receiver for snapshot data
      Returns:
      request handle

    • subscribeToRegionalLimitsForecast

      RequestSubscription subscribeToRegionalLimitsForecast(ForecastSnapshotSubscribedReceiver receiver, String monitoringSet)
      Create a polling subscription for regionally limiting forecast snapshot data updates
      Parameters:
      receiver - Streaming data receiver for snapshot data
      monitoringSet - filter for monitoring set name
      Returns:
      request result handle

    • createForecastRatingProposalStreamingUpdate

      ForecastRatingProposalUpdate createForecastRatingProposalStreamingUpdate()
      Create a forecast proposal update that can stream the update submission to the server
      Returns:
      update handle

    • getInUseLimits

      void getInUseLimits(RealTimeSnapshotReceiver receiver, String monitoringSet, String resourceId)
      Execute a request for the current real-time limits with a streaming response handler
      Parameters:
      receiver - streaming receiver for real-time limits
      monitoringSet - monitoring set name. Either monitoring set or resourceId may be provided, but not both. If neither are provided, the user's default monitoring set is assumed.
      resourceId - a resource to filter by. Either resource ID or monitoring set name may be provided, but not both. If neither are provided, then the user's default monitoring set will be assumed.

    • getInUseLimits

      void getInUseLimits(RealTimeSnapshotReceiver receiver, String monitoringSet)
      Execute a request for the current real-time limits with a streaming response handler
      Parameters:
      receiver - streaming receiver for real-time limits
      monitoringSet - monitoring set name. If not provided, the user's default monitoring set is assumed.

    • getInUseLimits

      void getInUseLimits(RealTimeSnapshotReceiver receiver)
      Execute a request for the current real-time limits with a streaming response handler
      Parameters:
      receiver - stream handler

    • subscribeToInUseLimits

      RequestSubscription subscribeToInUseLimits(RealTimeSnapshotSubscribedReceiver receiver)
      Create a polling subscription for real-time snapshot data updates
      Parameters:
      receiver - Streaming data receiver for snapshot data
      Returns:
      subscription result

    • subscribeToInUseLimits

      RequestSubscription subscribeToInUseLimits(RealTimeSnapshotSubscribedReceiver receiver, String monitoringSet)
      Create a polling subscription for real-time snapshot data updates
      Parameters:
      receiver - Streaming data receiver for snapshot data
      monitoringSet - optional filter for monitoring set
      Returns:
      subscription handle

    • subscribeToInUseLimits

      RequestSubscription subscribeToInUseLimits(RealTimeSnapshotSubscribedReceiver receiver, String monitoringSet, String resourceId)
      Create a polling subscription for real-time snapshot data updates
      Parameters:
      receiver - Streaming data receiver for snapshot data
      monitoringSet - optional filter for monitoring set
      resourceId - optional filter for transmission facility
      Returns:
      subscription handle

    • getRegionalRealTimeLimits

      void getRegionalRealTimeLimits(RealTimeSnapshotReceiver receiver)
      Execute a request for the regional real-time limits with a streaming response handler. Returns limits assuming the default monitoring set in the remote TROLIE.
      Parameters:
      receiver - callback for new limit snapshots

    • getRegionalRealTimeLimits

      void getRegionalRealTimeLimits(RealTimeSnapshotReceiver receiver, String monitoringSet)
      Execute a request for the regional real-time limits with a streaming response handler
      Parameters:
      receiver - callback for new limit snapshots
      monitoringSet - monitoring set to filter by.

    • getRegionalRealTimeLimits

      void getRegionalRealTimeLimits(RealTimeSnapshotReceiver receiver, String monitoringSet, String resourceId)
      Execute a request for the regional real-time limits with a streaming response handler
      Parameters:
      receiver - callback for new limit snapshots
      monitoringSet - monitoring set to filter by.
      resourceId - resource ID filter

    • subscribeToRegionalRealTimeLimits

      RequestSubscription subscribeToRegionalRealTimeLimits(RealTimeSnapshotSubscribedReceiver receiver)
      Create a polling subscription regional real-time snapshot data updates
      Parameters:
      receiver - Streaming data receiver for regional snapshot data
      Returns:
      subscription handle.

    • subscribeToRegionalRealTimeLimits

      RequestSubscription subscribeToRegionalRealTimeLimits(RealTimeSnapshotSubscribedReceiver receiver, String monitoringSet)
      Create a polling subscription for regional real-time snapshot data updates
      Parameters:
      receiver - Streaming data receiver for regional snapshot data
      monitoringSet - optional filter for monitoring set
      Returns:
      subscription handle

    • createRealTimeRatingProposalStreamingUpdate

      RealTimeRatingProposalUpdate createRealTimeRatingProposalStreamingUpdate()
      Create a real-time proposal update that can stream the update submission to the server
      Returns:
      stateful request.

    • unsubscribe

      void unsubscribe(RequestSubscription subscription)
      Un-subscribe an active polling request
      Parameters:
      subscription - subscription to cancel.

    • unsubscribeAll

      void unsubscribeAll()
      Un-subscribe all active polling requests

    • builder

      static TrolieClientBuilder builder(String baseUrl, org.apache.hc.client5.http.impl.classic.CloseableHttpClient httpClient)
      Initializes a new builder.
      Parameters:
      baseUrl - URL to the TROLIE service, such as https://trolie.example.com.
      httpClient - a pre-configured Apache HTTP client. The TROLIE client is built on top of the Apache HTTP client, and the full suite of configuration options for it are available. See examples for more detail.
      Returns:
      new builder