# This guide provides a comprehensive Java implementation for integrating with JUHE API using Spring Boot, featuring enterprise-grade error handling, resilience patterns, and best practices. ## Prerequisites * Java 11 or higher * Maven or Gradle build tool * Basic understanding of Spring Boot * IDE such as IntelliJ IDEA or Eclipse ## Project Setup ### Maven Dependencies Add the following dependencies to your `pom.xml`: ```xml org.springframework.boot spring-boot-starter-web org.apache.httpcomponents httpclient 4.5.13 com.fasterxml.jackson.core jackson-databind io.github.resilience4j resilience4j-spring-boot2 1.7.1 com.github.ben-manes.caffeine caffeine org.projectlombok lombok true ``` ### Gradle Dependencies Or if you're using Gradle, add to your `build.gradle`: ```plain text dependencies { implementation 'org.springframework.boot:spring-boot-starter-web' implementation 'org.apache.httpcomponents:httpclient:4.5.13' implementation 'com.fasterxml.jackson.core:jackson-databind' implementation 'io.github.resilience4j:resilience4j-spring-boot2:1.7.1' implementation 'com.github.ben-manes.caffeine:caffeine' compileOnly 'org.projectlombok:lombok' annotationProcessor 'org.projectlombok:lombok' } ``` ## API Client Implementation ### Model Classes First, let's create the model classes for the responses: ```java // Location.java package com.example.juhe.model; import com.fasterxml.jackson.annotation.JsonProperty; import lombok.Data; @Data public class Location { private String name; private String country; @JsonProperty("lat") private double latitude; @JsonProperty("lon") private double longitude; } ``` ```java // WeatherCondition.java package com.example.juhe.model; import lombok.Data; @Data public class WeatherCondition { private String text; private String icon; } ``` ```java // CurrentWeather.java package com.example.juhe.model; import com.fasterxml.jackson.annotation.JsonProperty; import lombok.Data; @Data public class CurrentWeather { @JsonProperty("temp_c") private double temperatureCelsius; @JsonProperty("temp_f") private double temperatureFahrenheit; private WeatherCondition condition; private int humidity; @JsonProperty("wind_kph") private double windSpeedKph; @JsonProperty("wind_mph") private double windSpeedMph; } ``` ```java // WeatherResponse.java package com.example.juhe.model; import lombok.Data; @Data public class WeatherResponse { private String status; private WeatherData data; } @Data class WeatherData { private Location location; private CurrentWeather current; } ``` ```java // ForecastDay.java package com.example.juhe.model; import com.fasterxml.jackson.annotation.JsonProperty; import lombok.Data; @Data public class ForecastDay { private String date; @JsonProperty("max_temp_c") private double maxTemperatureCelsius; @JsonProperty("min_temp_c") private double minTemperatureCelsius; private String condition; @JsonProperty("chance_of_rain") private int chanceOfRain; } ``` ```java // ForecastResponse.java package com.example.juhe.model; import lombok.Data; import java.util.List; @Data public class ForecastResponse { private String status; private ForecastData data; } @Data class ForecastData { private Location location; private List forecast; } ``` ### API Exception Handling Create a custom exception for API errors: ```java // JuheApiException.java package com.example.juhe.exception; import lombok.Getter; @Getter public class JuheApiException extends RuntimeException { private final String errorCode; private final int statusCode; public JuheApiException(String message, String errorCode, int statusCode) { super(message); this.errorCode = errorCode; this.statusCode = statusCode; } public JuheApiException(String message, String errorCode, int statusCode, Throwable cause) { super(message, cause); this.errorCode = errorCode; this.statusCode = statusCode; } } ``` ### API Client Now, let's implement the robust API client: ```java // JuheApiClient.java package com.example.juhe.client; import com.example.juhe.exception.JuheApiException; import com.example.juhe.model.ForecastResponse; import com.example.juhe.model.WeatherResponse; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker; import io.github.resilience4j.retry.annotation.Retry; import lombok.extern.slf4j.Slf4j; import org.apache.http.client.config.RequestConfig; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClientBuilder; import org.apache.http.impl.conn.PoolingHttpClientConnectionManager; import org.springframework.beans.factory.annotation.Value; import org.springframework.cache.annotation.Cacheable; import org.springframework.http.HttpEntity; import org.springframework.http.HttpHeaders; import org.springframework.http.HttpMethod; import org.springframework.http.ResponseEntity; import org.springframework.http.client.HttpComponentsClientHttpRequestFactory; import org.springframework.stereotype.Component; import org.springframework.web.client.HttpStatusCodeException; import org.springframework.web.client.RestTemplate; import org.springframework.web.util.UriComponentsBuilder; import java.io.IOException; import java.util.Collections; import java.util.Map; @Component @Slf4j public class JuheApiClient { private final RestTemplate restTemplate; private final ObjectMapper objectMapper; private final String apiKey; private final String baseUrl; public JuheApiClient( ObjectMapper objectMapper, @Value("${juhe.api.key}") String apiKey, @Value("${juhe.api.base-url:}") String baseUrl) { this.objectMapper = objectMapper; this.apiKey = apiKey; this.baseUrl = baseUrl; this.restTemplate = createRestTemplate(); } private RestTemplate createRestTemplate() { // Configure connection pooling PoolingHttpClientConnectionManager connectionManager = new PoolingHttpClientConnectionManager(); connectionManager.setMaxTotal(100); connectionManager.setDefaultMaxPerRoute(20); // Configure timeouts RequestConfig requestConfig = RequestConfig.custom() .setConnectTimeout(5000) .setSocketTimeout(10000) .build(); // Build HttpClient CloseableHttpClient httpClient = HttpClientBuilder.create() .setConnectionManager(connectionManager) .setDefaultRequestConfig(requestConfig) .build(); // Create request factory with the HttpClient HttpComponentsClientHttpRequestFactory requestFactory = new HttpComponentsClientHttpRequestFactory(httpClient); return new RestTemplate(requestFactory); } /** * Make a GET request to the JUHE API. * * @param endpoint API endpoint * @param params Query parameters * @param responseType Response class * @param Response type * @return API response */ @CircuitBreaker(name = "juheApi") @Retry(name = "juheApi") public T get(String endpoint, Map params, Class responseType) { try { // Add API key to parameters UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl(baseUrl + endpoint); // Add query parameters if (params != null) { params.forEach(builder::queryParam); } // Add API key builder.queryParam("key", apiKey); // Set up headers HttpHeaders headers = new HttpHeaders(); headers.set("Authorization", "Bearer " + apiKey); // Make the request ResponseEntity response = restTemplate.exchange( builder.toUriString(), HttpMethod.GET, new HttpEntity<>(headers), String.class ); // Check for error in response String responseBody = response.getBody(); JsonNode root = objectMapper.readTree(responseBody); if ("error".equals(root.path("status").asText())) { String errorCode = root.path("code").asText("UNKNOWN_ERROR"); String errorMessage = root.path("message").asText("Unknown error occurred"); throw new JuheApiException(errorMessage, errorCode, response.getStatusCodeValue()); } // Parse successful response return objectMapper.readValue(responseBody, responseType); } catch (HttpStatusCodeException e) { // Handle HTTP errors try { JsonNode errorBody = objectMapper.readTree(e.getResponseBodyAsString()); String errorCode = errorBody.path("code").asText("HTTP_ERROR"); String errorMessage = errorBody.path("message").asText(e.getStatusText()); throw new JuheApiException(errorMessage, errorCode, e.getRawStatusCode(), e); } catch (IOException ioException) { throw new JuheApiException(e.getStatusText(), "HTTP_ERROR", e.getRawStatusCode(), e); } } catch (IOException e) { // Handle JSON parsing errors throw new JuheApiException("Error parsing API response", "PARSE_ERROR", 500, e); } catch (JuheApiException e) { // Rethrow API exceptions throw e; } catch (Exception e) { // Handle other exceptions throw new JuheApiException("Unexpected error: " + e.getMessage(), "UNEXPECTED_ERROR", 500, e); } } /** * Get current weather for a location. * * @param location Location name * @return Weather response */ @Cacheable(value = "weatherCache", key = "#location") public WeatherResponse getCurrentWeather(String location) { log.info("Fetching current weather for location: {}", location); return get("/weather/current", Collections.singletonMap("location", location), WeatherResponse.class); } /** * Get weather forecast for a location. * * @param location Location name * @param days Number of days (default: 5) * @return Forecast response */ @Cacheable(value = "forecastCache", key = "#location + '-' + #days") public ForecastResponse getWeatherForecast(String location, int days) { log.info("Fetching {}-day forecast for location: {}", days, location); Map params = Map.of( "location", location, "days", days ); return get("/weather/forecast", params, ForecastResponse.class); } } ``` ## Service Layer Let's create a service layer that uses our API client: ```java // WeatherService.java package com.example.juhe.service; import com.example.juhe.client.JuheApiClient; import com.example.juhe.exception.JuheApiException; import com.example.juhe.model.CurrentWeather; import com.example.juhe.model.ForecastDay; import com.example.juhe.model.ForecastResponse; import com.example.juhe.model.WeatherResponse; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.stereotype.Service; import java.util.List; @Service @RequiredArgsConstructor @Slf4j public class WeatherService { private final JuheApiClient apiClient; /** * Get current weather for a location. * * @param location Location name * @return Current weather data */ public CurrentWeather getCurrentWeather(String location) { try { WeatherResponse response = apiClient.getCurrentWeather(location); return response.getData().getCurrent(); } catch (JuheApiException e) { log.error("Error fetching current weather for {}: {} - {}", location, e.getErrorCode(), e.getMessage()); throw e; } } /** * Get weather forecast for a location. * * @param location Location name * @param days Number of forecast days * @return List of forecast days */ public List getWeatherForecast(String location, int days) { try { ForecastResponse response = apiClient.getWeatherForecast(location, days); return response.getData().getForecast(); } catch (JuheApiException e) { log.error("Error fetching forecast for {}: {} - {}", location, e.getErrorCode(), e.getMessage()); throw e; } } } ``` ## Controller Layer Now, let's create REST endpoints that use our service: ```java // WeatherController.java package com.example.juhe.controller; import com.example.juhe.exception.JuheApiException; import com.example.juhe.model.CurrentWeather; import com.example.juhe.model.ForecastDay; import com.example.juhe.service.WeatherService; import lombok.RequiredArgsConstructor; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; import java.util.HashMap; import java.util.List; import java.util.Map; @RestController @RequestMapping("/api/weather") @RequiredArgsConstructor public class WeatherController { private final WeatherService weatherService; @GetMapping("/{location}") public ResponseEntity

API Documentation

In this section

Batch Processing

Custom Extraction Rules

Performance Optimization