Package com.targomo.client.api.request

Class GeocodingRequest

java.lang.Object
com.targomo.client.api.request.GeocodingRequest
All Implemented Interfaces:
GetRequest<String,GeocodingResponse>
public class GeocodingRequest extends Object implements GetRequest<String,GeocodingResponse>
The GeocodingRequest uses the ESRI webservice to request a coordinate candidates for one or more addresses. Multiple requests can be made with one GeocodingRequest object.
See Also:

  • Constructor Details

    • GeocodingRequest

      public GeocodingRequest(javax.ws.rs.client.Client client)
      Creation of a default geo coding request without ESRI credentials (for batch requests slower than with credentials)

      Note1: The client's lifecycle is not handled here. Please make sure to properly close the client when not needed anymore.
      Note2: For the parallel batch requests it may be required to set a certain connection pool size when client is created. (e.g. this was necessary for a JBoss client but not for the Jersey client)

      Parameters:
      client - specified Client implementation to be used, e.g. Jersey or jBoss client

    • GeocodingRequest

      public GeocodingRequest(javax.ws.rs.client.Client client, Map<GeocodingRequest.Option,String> extraOptions)
      Use a custom client implementation for the geo coding request with non-default request parameters and no ESRI credentials)

      Note1: The client's lifecycle is not handled here. Please make sure to properly close the client when not needed anymore.
      Note2: For the parallel batch requests it may be required to set a certain connection pool size when client is created. (e.g. this was necessary for a JBoss client but not for the Jersey client)

      Parameters:
      client - specified Client implementation to be used, e.g. Jersey or jBoss client
      extraOptions - see GeocodingRequest.Option for possibilities - null pointer and empty strings will be ignored

    • GeocodingRequest

      public GeocodingRequest(javax.ws.rs.client.Client client, ESRIAuthenticationDetails authenticationDetails)
      Creation of a default geo coding request with ESRI credentials.

      Note1: The client's lifecycle is not handled here. Please make sure to properly close the client when not needed anymore.
      Note2: For the parallel batch requests it may be required to set a certain connection pool size when client is created. (e.g. this was necessary for a JBoss client but not for the Jersey client)

      Parameters:
      client - specified Client implementation to be used, e.g. Jersey or jBoss client
      authenticationDetails - the authentication details with which accessToken will be retrieved

    • GeocodingRequest

      public GeocodingRequest(javax.ws.rs.client.Client client, int requestTimeOutInMs)
      Creation of a default geo coding request with customizable timeout.

      Note1: The client's lifecycle is not handled here. Please make sure to properly close the client when not needed anymore.
      Note2: For the parallel batch requests it may be required to set a certain connection pool size when client is created. (e.g. this was necessary for a JBoss client but not for the Jersey client)

      Parameters:
      client - specified Client implementation to be used, e.g. Jersey or jBoss client
      requestTimeOutInMs - the timeout before an request fails with TargomoClientException

    • GeocodingRequest

      public GeocodingRequest(javax.ws.rs.client.Client client, ESRIAuthenticationDetails authenticationDetails, Map<GeocodingRequest.Option,String> extraOptions, int requestTimeOutInMs)
      Use a custom client implementation for the geo coding request with non-default request parameters and ESRI credentials).

      Note1: The client's lifecycle is not handled here. Please make sure to properly close the client when not needed anymore.
      Note2: For the parallel batch requests it may be required to set a certain connection pool size when client is created. (e.g. this was necessary for a JBoss client but not for the Jersey client)

      Parameters:
      client - specified Client implementation to be used, e.g. Jersey or jBoss client
      authenticationDetails - the authentication details with which accessToken will be retrieved
      extraOptions - see GeocodingRequest.Option for possibilities - null pointer and empty strings will be ignored
      requestTimeOutInMs - the timeout before an request fails with TargomoClientException

  • Method Details

    • get

      public GeocodingResponse get(String singleLineAddress) throws TargomoClientException, javax.ws.rs.ProcessingException
      Invokes a simple request to geocode one address. The address is given in a single String.
      Specified by:
      get in interface GetRequest<String,GeocodingResponse>
      Parameters:
      singleLineAddress - e.g. "Chausseestr. 101, 10115 Berlin"
      Returns:
      the parsed REST service response
      Throws:
      TargomoClientException - when error occurs during request. This does not query a Targomo Service.
      javax.ws.rs.ProcessingException - when connection error occurs

    • get

      public GeocodingResponse get(Address address) throws TargomoClientException, javax.ws.rs.ProcessingException
      Invokes a simple request to geocode one address. The address is given in an Address. Empty or null fields will be ignored by the request.
      Parameters:
      address - e.g. 
      new Address("Chausseestr. 101","","Berlin","10115",null);
      Returns:
      the parsed REST service response
      Throws:
      TargomoClientException - when error occurs during request. This does not query a Targomo Service.
      javax.ws.rs.ProcessingException - when connection error occurs

    • getBatchParallel

      public GeocodingResponse[] getBatchParallel(int parallelThreads, int triesBeforeFail, String... addresses) throws TargomoClientException, javax.ws.rs.ProcessingException
      Facilitating a parallel batch request for geocoding multiple addresses given as single String. It uses an ExecutorService with a specified thread pool size. These threads are used to request single geocoding results in parallel. Due to temporal unavailability of the service the request may be repeated a number of times before failing.
      Parameters:
      parallelThreads - greater than or equal to 1 (==1 means sequential processing) - be careful to not create too many Threads
      triesBeforeFail - greater than or equal to 1
      addresses - not null and with at least on element
      Returns:
      the resulting individual responses - same order as input addresses
      Throws:
      TargomoClientException - when error occurs during request. This does not query a Targomo Service.
      javax.ws.rs.ProcessingException - when connection error occurs
      See Also:

    • getBatchParallel

      public GeocodingResponse[] getBatchParallel(int parallelThreads, int triesBeforeFail, Address... addresses) throws TargomoClientException, javax.ws.rs.ProcessingException
      Facilitating a parallel batch request for geocoding multiple Addresses. It uses an ExecutorService with a specified thread pool size. These threads are used to request single geocoding results in parallel. Due to temporal unavailability of the service the request may be repeated a number of times before failing.
      Parameters:
      parallelThreads - greater than or equal to 1 (==1 means sequential processing) - be careful to not create too many Threads
      triesBeforeFail - greater than or equal to 1
      addresses - not null and with at least on element
      Returns:
      the resulting individual responses - same order as input addresses
      Throws:
      TargomoClientException - when error occurs during request. This does not query a Targomo Service.
      javax.ws.rs.ProcessingException - when connection error occurs
      See Also:

    • getBatchSequential

      public GeocodingResponse[] getBatchSequential(String... addresses) throws TargomoClientException, javax.ws.rs.ProcessingException
      Facilitating a sequential batch request for geocoding multiple addresses each given as single String.
      Parameters:
      addresses - not null and with at least on element
      Returns:
      the resulting individual responses - same order as input addresses
      Throws:
      TargomoClientException - when error occurs during request. This does not query a Targomo Service.
      javax.ws.rs.ProcessingException - when connection error occurs
      See Also:

    • getBatchSequential

      public GeocodingResponse[] getBatchSequential(Address... addresses) throws TargomoClientException, javax.ws.rs.ProcessingException
      Facilitating a sequential batch request for geocoding multiple Addresses.
      Parameters:
      addresses - not null and with at least on element
      Returns:
      the resulting individual responses - same order as input addresses
      Throws:
      TargomoClientException - when error occurs during request. This does not query a Targomo Service.
      javax.ws.rs.ProcessingException - when connection error occurs
      See Also:

    • getCurrentAccessToken

      public String getCurrentAccessToken()