Package com.github.trelawnm.weathersdk

Class WeatherSDK

java.lang.Object
com.github.trelawnm.weathersdk.WeatherSDK
public class WeatherSDK extends Object
Weather SDK - lightweight Java library for OpenWeatherMap API. Provides a simple interface to retrieve weather data in JSON format.

Operation Modes:

  • ON_DEMAND - Lazy polling: data is fetched on request with TTL-based caching
  • POLLING - True polling: background agent periodically updates all cached cities

Usage Example (ON_DEMAND mode): 

 
 WeatherSDK sdk = new WeatherSDK.Builder("your-api-key")
     .endpoint("https://api.openweathermap.org/data/2.5/")
     .mode(WeatherSDKMode.ON_DEMAND)
     .build();
 String weatherJson = sdk.getWeather("London");
 System.out.println(weatherJson);
 
 // Don't forget to cleanup when done
 sdk.shutdown();

Usage Example (POLLING mode): 

 
 // SDK automatically starts background polling agent
 WeatherSDK sdk = new WeatherSDK.Builder("your-api-key")
     .mode(WeatherSDKMode.POLLING)
     .pollingInterval(Duration.ofMinutes(10))
     .maxSize(15)
     .build();
 
 // Immediate response from cache (zero latency)
 String weatherJson = sdk.getWeather("London");
 System.out.println(weatherJson);
 
 // Don't forget to cleanup when done
 sdk.shutdown();

Resource Management: For POLLING mode, always call shutdown() to stop background threads and release resources when the SDK is no longer needed.

Version:
1.0
Author:
trelawnm
See Also:

  • Method Details

    • getKey

      public String getKey()
      Returns the API key used for authentication with OpenWeatherMap service
      Returns:
      the API key as String

    • getEndpoint

      public String getEndpoint()
      Returns the endpoint URL for OpenWeatherMap API requests
      Returns:
      the endpoint URL as String

    • getMode

      public WeatherSDKMode getMode()
      Returns the operation mode of the SDK (ON_DEMAND or POLLING)
      Returns:
      the current operation mode

    • getPollingInterval

      public Duration getPollingInterval()
      Returns the polling interval used in POLLING mode
      Returns:
      the polling interval as Duration

    • getWeatherObj

      public WeatherResponse getWeatherObj(String cityName)
      Gets current weather data for specified city
      Parameters:
      cityName - the name of the city
      Returns:
      weather data in JSON format
      Throws:
      IllegalArgumentException - if request fails or city not found

    • getWeather

      public String getWeather(String cityName)
      Gets current weather data for specified city in JSON format. Implements different caching strategies based on operation mode: - ON_DEMAND: Lazy polling with TTL-based cache validation - POLLING: Immediate response from pre-refreshed cache
      Parameters:
      cityName - the name of the city to query
      Returns:
      weather data as JSON string
      Throws:
      RuntimeException - if city not found or API request fails

    • shutdown

      public void shutdown()
      Gracefully shuts down background polling agent (if enabled) and releases resources. Should be called when SDK is no longer needed, especially in POLLING mode. No-op if scheduler is not initialized (ON_DEMAND mode).

    • clearCache

      public void clearCache()
      Clears all cached weather data. Useful for freeing memory or resetting SDK state.