Package com.cercalia.sdk

Class CercaliaClient

java.lang.Object
com.cercalia.sdk.CercaliaClient
Direct Known Subclasses:
GeocodingService, GeofencingService, GeomentService, IsochroneService, PoiService, ProximityService, ReverseGeocodingService, RoutingService, SnapToRoadService, StaticMapsService, SuggestService
public abstract class CercaliaClient extends Object
Abstract base class for all Cercalia API services.

This class provides the core HTTP request-response cycle infrastructure, including connection pooling, request authentication, retry mechanisms, and standard Cercalia XML/JSON response parsing.

Subclasses implement specific Cercalia services by defining parameters and mapping the results to high-level POJOs.

  • Field Details

    • config

      protected final CercaliaConfig config

    • httpClient

      protected final okhttp3.OkHttpClient httpClient

    • objectMapper

      protected final com.fasterxml.jackson.databind.ObjectMapper objectMapper

    • logger

      protected final Logger logger

  • Constructor Details

    • CercaliaClient

      protected CercaliaClient(@NotNull @NotNull CercaliaConfig config)
      Creates a new CercaliaClient with the specified configuration.
      Parameters:
      config - the Cercalia configuration

    • CercaliaClient

      protected CercaliaClient(@NotNull @NotNull CercaliaConfig config, @NotNull @NotNull okhttp3.OkHttpClient httpClient)
      Creates a new CercaliaClient with a custom OkHttpClient.
      Parameters:
      config - the Cercalia configuration
      httpClient - the custom HTTP client

  • Method Details

    • getConfig

      @NotNull public @NotNull CercaliaConfig getConfig()
      Returns the configuration for this client.
      Returns:
      the configuration

    • request

      protected com.fasterxml.jackson.databind.JsonNode request(@NotNull @NotNull Map<String,String> params, @NotNull @NotNull String operationName)
      Makes a synchronous request to the Cercalia API.
      Parameters:
      params - the query parameters
      operationName - the operation name for logging
      Returns:
      the "cercalia" node from the response
      Throws:
      CercaliaException - if the request fails or returns an error

    • request

      protected com.fasterxml.jackson.databind.JsonNode request(@NotNull @NotNull Map<String,String> params, @NotNull @NotNull String operationName, String baseUrl)
      Makes a synchronous request to the Cercalia API with a custom base URL.
      Parameters:
      params - the query parameters
      operationName - the operation name for logging
      baseUrl - the base URL (optional, uses config.baseUrl if null)
      Returns:
      the "cercalia" node from the response
      Throws:
      CercaliaException - if the request fails or returns an error

    • requestAsync

      protected CompletableFuture<com.fasterxml.jackson.databind.JsonNode> requestAsync(@NotNull @NotNull Map<String,String> params, @NotNull @NotNull String operationName)
      Makes an asynchronous request to the Cercalia API.
      Parameters:
      params - the query parameters
      operationName - the operation name for logging
      Returns:
      a CompletableFuture with the "cercalia" node from the response

    • requestAsync

      protected CompletableFuture<com.fasterxml.jackson.databind.JsonNode> requestAsync(@NotNull @NotNull Map<String,String> params, @NotNull @NotNull String operationName, String baseUrl)
      Makes an asynchronous request to the Cercalia API with a custom base URL.
      Parameters:
      params - the query parameters
      operationName - the operation name for logging
      baseUrl - the base URL (optional, uses config.baseUrl if null)
      Returns:
      a CompletableFuture with the "cercalia" node from the response

    • newParams

      protected Map<String,String> newParams()
      Creates a new parameter map.
      Returns:
      a new HashMap for parameters

    • newParams

      protected Map<String,String> newParams(String cmd)
      Creates a new parameter map with the specified command.
      Parameters:
      cmd - the command
      Returns:
      a new HashMap with the command set

    • addIfPresent

      protected void addIfPresent(Map<String,String> params, String key, String value)
      Adds a parameter to the map if the value is not null or empty.
      Parameters:
      params - the parameter map
      key - the parameter key
      value - the parameter value

    • addIfPresent

      protected void addIfPresent(Map<String,String> params, String key, Integer value)
      Adds a parameter to the map if the value is not null.
      Parameters:
      params - the parameter map
      key - the parameter key
      value - the parameter value

    • addIfPresent

      protected void addIfPresent(Map<String,String> params, String key, Double value)
      Adds a parameter to the map if the value is not null.
      Parameters:
      params - the parameter map
      key - the parameter key
      value - the parameter value

    • addIfTrue

      protected void addIfTrue(Map<String,String> params, String key, Boolean value, String trueValue)
      Adds a boolean parameter to the map if the value is true.
      Parameters:
      params - the parameter map
      key - the parameter key
      value - the parameter value
      trueValue - the string value to use when true