Package energy.trolie.client

Class TrolieClientBuilder

java.lang.Object
energy.trolie.client.TrolieClientBuilder
public class TrolieClientBuilder extends Object

Builder class used to construct new instances of the TROLIE client.

When configuring the TROLIE client, users should specifically be aware of two things:

  • The TROLIE client builds on the Apache Commons HTTP Client. While a default may be created for naive users, the client implementation itself is injectable, and users may control most of the advanced options of the HTTP client (proxies etc) as needed for their implementations.
  • Correct implementation of an ETagStore is critical to consuming ratings in a robust way. This marks the current version of data that this application (the TROLIE SDK user) has in its knowledge. The default implementation simply stores in memory. This may be fine for many uses, but applications may want to use their own storage (such as a database) for current data values.

  • Field Details

    • DEFAULT_BUFFER_SIZE

      public static final int DEFAULT_BUFFER_SIZE
      Default buffer size for BufferedInputStreams and BufferedOutputStreams.
      See Also:

  • Constructor Details

    • TrolieClientBuilder

      public TrolieClientBuilder(String baseUrl)
      Initializes a new builder with a preconfigured apache HTTP client
      Parameters:
      baseUrl - URL to the TROLIE service, such as https://trolie.example.com.

    • TrolieClientBuilder

      public TrolieClientBuilder(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.

  • Method Details

    • requestConfig

      public TrolieClientBuilder requestConfig(org.apache.hc.client5.http.config.RequestConfig config)
      Override the HTTP client request config
      Parameters:
      config - overridden config
      Returns:
      fluent builder

    • bufferSize

      public TrolieClientBuilder bufferSize(int bufferSize)
      Override the buffer size used in Java BufferedInputStreams and BufferedOutputStreams to optimize performance. Defaults to DEFAULT_BUFFER_SIZE.
      Parameters:
      bufferSize - new buffer size
      Returns:
      fluent builder.

    • objectMapper

      public TrolieClientBuilder objectMapper(com.fasterxml.jackson.databind.ObjectMapper objectMapper)
      Overrides configuration of the Jackson object mapper using for JSON parsing and serialization
      Parameters:
      objectMapper - new object mapper
      Returns:
      fluent builder

    • etagStore

      public TrolieClientBuilder etagStore(ETagStore eTagStore)
      Overrides the ETag Store used to cache the version of data stored by this system.
      Parameters:
      eTagStore - new store
      Returns:
      fluent builder.

    • httpHeaders

      public TrolieClientBuilder httpHeaders(Map<String,String> httpHeaders)
      Allows for additional headers to be passed with every request.
      Parameters:
      httpHeaders - Key value pairs of additional header set to be passed with every request.
      Returns:
      fluent builder

    • addRequestHeaderProvider

      public TrolieClientBuilder addRequestHeaderProvider(RequestHeaderProvider provider)
      Adds a request header provider that can generate additional headers for each request execution. Providers are invoked during the initial request construction.

      Note: If the underlying HttpClient is configured with automatic retries, the same request object (and its headers) may be sent multiple times. To ensure security-sensitive headers like nonces are regenerated, users should ensure that automatic retries are disabled or that the client is configured to rebuild requests on retry.

      Parameters:
      provider - provider used to generate request-specific headers
      Returns:
      fluent builder

    • requestHeaderProviders

      public TrolieClientBuilder requestHeaderProviders(List<RequestHeaderProvider> providers)
      Replaces the current set of request header providers with the given list. Providers are invoked during the initial request construction.

      Note: If the underlying HttpClient is configured with automatic retries, the request (including these headers) may be reused across multiple attempts. To guarantee fresh header values (e.g., new nonces) on retry, implementers must ensure that automatic transport-level retries are disabled or that the client is configured to rebuild requests on retry.

      Parameters:
      providers - list of providers used to generate request-specific headers
      Returns:
      fluent builder

    • periodLength

      public TrolieClientBuilder periodLength(int periodLengthMinutes)
      Sets the period length assumed for forecast ratings. Defaults to 60 minutes.
      Parameters:
      periodLengthMinutes - new assumed period length.
      Returns:
      fluent builder

    • forecastRatingsPollMs

      public TrolieClientBuilder forecastRatingsPollMs(int forecastRatingsPollMs)
      Sets the period at which TrolieClient.subscribeToInUseLimitForecastUpdates(ForecastSnapshotSubscribedReceiver) and similar methods for forecast ratings poll for new ratings. Defaults to 30 seconds
      Parameters:
      forecastRatingsPollMs - new poll periodicity in milliseconds
      Returns:
      fluent builder

    • realTimeRatingsPollMs

      public TrolieClientBuilder realTimeRatingsPollMs(int realTimeRatingsPollMs)
      Sets the period at which TrolieClient.subscribeToInUseLimits(RealTimeSnapshotSubscribedReceiver) and similar methods poll for new real-time ratings. Defaults to 10 seconds
      Parameters:
      realTimeRatingsPollMs - new poll periodicity in milliseconds
      Returns:
      fluent builder

    • monitoringSetPollMs

      public TrolieClientBuilder monitoringSetPollMs(int monitoringSetPollMs)
      Sets the period at which TrolieClient.subscribeToDefaultMonitoringSetUpdates(MonitoringSetsSubscribedReceiver) and similar methods poll for monitoring sets. Defaults to 60 seconds
      Parameters:
      monitoringSetPollMs - new poll periodicity in milliseconds
      Returns:
      fluent builder

    • seasonalRatingsPollMs

      public TrolieClientBuilder seasonalRatingsPollMs(int seasonalRatingsPollMs)
      Sets the period at which TrolieClient.subscribeToInUseSeasonalSnapshotUpdates(SeasonalSnapshotSubscribedReceiver) and similar methods for forecast ratings poll for new ratings. Defaults to 30 seconds
      Parameters:
      seasonalRatingsPollMs - new poll periodicity in milliseconds
      Returns:
      fluent builder

    • withSppAuthentication

      public TrolieClientBuilder withSppAuthentication(String screenName, String apiKey)
      Configures this client to authenticate with an SPP system using the SPP Two-Factor Authentication (TFA) protocol.
      Parameters:
      screenName - the SPP-assigned screen name
      apiKey - the Base64-encoded API key assigned by SPP
      Returns:
      this builder
      See Also:

    • build

      public TrolieClient build()
      Construct a new client
      Returns:
      new client