net.motionintelligence.client.api.request

Class GeocodingRequest

java.lang.Object

net.motionintelligence.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:

Documentation

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GeocodingRequest.Option Special Geocoding request options that can be set at creation of the request.

Constructor Summary

Constructors

Constructor and Description
GeocodingRequest(javax.ws.rs.client.Client client) Creation of a default geo coding request without ESRI credentials (for batch requests slower than with credentials)
GeocodingRequest(javax.ws.rs.client.Client client, ESRIAuthenticationDetails authenticationDetails) Creation of a default geo coding request with ESRI credentials.
GeocodingRequest(javax.ws.rs.client.Client client, ESRIAuthenticationDetails authenticationDetails, Map<GeocodingRequest.Option,String> extraOptions) Use a custom client implementation for the geo coding request with non-default request parameters and ESRI credentials).
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)

Method Summary

Modifier and Type	Method and Description
GeocodingResponse	get(Address address) Invokes a simple request to geocode one address.
GeocodingResponse	get(String singleLineAddress) Invokes a simple request to geocode one address.
GeocodingResponse[]	getBatchParallel(int parallelThreads, int triesBeforeFail, Address... addresses) Facilitating a parallel batch request for geocoding multiple Addresses.
GeocodingResponse[]	getBatchParallel(int parallelThreads, int triesBeforeFail, String... addresses) Facilitating a parallel batch request for geocoding multiple addresses given as single String.
GeocodingResponse[]	getBatchSequential(Address... addresses) Facilitating a sequential batch request for geocoding multiple Addresses.
GeocodingResponse[]	getBatchSequential(String... addresses) Facilitating a sequential batch request for geocoding multiple addresses each given as single String.
String	getCurrentAccessToken()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

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,
                        ESRIAuthenticationDetails authenticationDetails,
                        Map<GeocodingRequest.Option,String> extraOptions)

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

Method Detail

get

public GeocodingResponse get(String singleLineAddress)
                      throws Route360ClientException,
                             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:

Route360ClientException - when error occurs during request

javax.ws.rs.ProcessingException - when connection error occurs

get

public GeocodingResponse get(Address address)
                      throws Route360ClientException,
                             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:

Route360ClientException - when error occurs during request

javax.ws.rs.ProcessingException - when connection error occurs

getBatchParallel

public GeocodingResponse[] getBatchParallel(int parallelThreads,
                                            int triesBeforeFail,
                                            String... addresses)
                                     throws Route360ClientException,
                                            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:

Route360ClientException - when error occurs during request

javax.ws.rs.ProcessingException - when connection error occurs

See Also:

get(String)

getBatchParallel

public GeocodingResponse[] getBatchParallel(int parallelThreads,
                                            int triesBeforeFail,
                                            Address... addresses)
                                     throws Route360ClientException,
                                            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:

Route360ClientException - when error occurs during request

javax.ws.rs.ProcessingException - when connection error occurs

See Also:

get(Address)

getBatchSequential

public GeocodingResponse[] getBatchSequential(String... addresses)
                                       throws Route360ClientException,
                                              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:

Route360ClientException - when error occurs during request

javax.ws.rs.ProcessingException - when connection error occurs

See Also:

get(String)

getBatchSequential

public GeocodingResponse[] getBatchSequential(Address... addresses)
                                       throws Route360ClientException,
                                              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:

Route360ClientException - when error occurs during request

javax.ws.rs.ProcessingException - when connection error occurs

See Also:

get(Address)

getCurrentAccessToken

public String getCurrentAccessToken()