com.geotab.api

Class GeotabApi

java.lang.Object

com.geotab.api.GeotabApi

All Implemented Interfaces:

Api, Closeable, AutoCloseable

public class GeotabApi
extends Object
implements Api

Nested Class Summary

Nested classes/interfaces inherited from interface com.geotab.api.Api

Api.EntityDescriptor<E extends Entity,S extends Search>, Api.MethodDescriptor<P extends AuthenticatedParameters,R>, Api.MultiCallBuilder

Field Summary

Fields

Modifier and Type	Field and Description
protected AtomicReference<LoginResult>	auth
protected Credentials	credentials
static String	DEFAULT_SERVER
protected AtomicReference<ServerInvoker>	invoker
static String	PROTOCOL
protected String	server
static String	THIS_SERVER
protected int	timeout

Fields inherited from interface com.geotab.api.Api

Add, Get, GetCountOf, GetFeed, Remove, Set

Constructor Summary

Constructors

Constructor and Description
GeotabApi(Credentials credentials) Create new api instance.
GeotabApi(Credentials credentials, String server, int timeout) Create new api instance.
GeotabApi(Credentials credentials, String server, int timeout, String servicePath, org.apache.hc.client5.http.impl.classic.CloseableHttpClient httpClient) Create new api instance.

Method Summary

Modifier and Type	Method and Description
LoginResult	authenticate() Authenticates a user and provides a LoginResult if successful.
Api.MultiCallBuilder	buildMultiCall() Builds a type-safe API multi-call.
protected ServerInvoker	buildServerInvoker(String url, Integer timeout, String servicePath, org.apache.hc.client5.http.impl.classic.CloseableHttpClient httpClient)
<O extends BaseResponse<T>,T> Optional<T>	call(AuthenticatedRequest<?> in, Class<O> outT) Makes a custom method API call specifying the response type.
Optional<Id>	callAdd(AuthenticatedRequest<?> in) Makes an Add call.
<T extends Entity> Optional<List<T>>	callGet(AuthenticatedRequest<?> in, Class<T> outT) Makes a Get call.
Optional<Integer>	callGetCountOf(AuthenticatedRequest<?> in) Makes a GetCountOf call.
<T extends Entity> Optional<FeedResult<T>>	callGetFeed(AuthenticatedRequest<?> in, Class<T> outT) Makes a GetFeed call.
<P extends AuthenticatedParameters,R> Optional<R>	callMethod(Api.MethodDescriptor<P,R> method, P params) Makes a web method call.
void	callRemove(AuthenticatedRequest<?> in) Makes a Remove call.
<T> Optional<T>	callResult(AuthenticatedRequest<?> in, Class<T> outT) Makes a custom method API call specifying the result type.
<T> Optional<List<T>>	callResultList(AuthenticatedRequest<?> in, Class<T> outT) Makes a custom method API call specifying the element type of list result type.
void	callSet(AuthenticatedRequest<?> in) Makes a Set call.
void	close()
void	disconnect()
boolean	isAuthenticated() Check if the API is authenticated.
<O extends BaseResponse<T>,T> Optional<T>	multiCall(MultiCallRequest in, Class<O> outT) Makes a type-safe API multi-call.
<T> Optional<List<T>>	uniformMultiCall(List<? extends BaseRequest<?>> calls, Class<T> outT) Makes a uniform type-safe API multi-call.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.geotab.api.Api

callAdd, callAdd, callGet, callGet, callGet, callGetAll, callGetById, callGetCountOf, callGetCountOf, callGetFeed, callGetFeed, callRemove, callRemove, callSet, callSet, entity, method

Field Detail

THIS_SERVER

public static final String THIS_SERVER

See Also:

Constant Field Values

DEFAULT_SERVER

public static final String DEFAULT_SERVER

See Also:

Constant Field Values

PROTOCOL

public static final String PROTOCOL

See Also:

Constant Field Values

credentials

protected final Credentials credentials

server

protected final String server

timeout

protected final int timeout

auth

protected final AtomicReference<LoginResult> auth

invoker

protected final AtomicReference<ServerInvoker> invoker

Constructor Detail

GeotabApi

public GeotabApi(Credentials credentials)

Create new api instance.

Parameters:

credentials - Credentials used to authenticate.

GeotabApi

public GeotabApi(Credentials credentials,
                 String server,
                 int timeout)

Create new api instance.

Parameters:

credentials - Credentials used to authenticate.

server - Server url without protocol. Example: my.geotab.com

timeout - Request timeout

GeotabApi

public GeotabApi(Credentials credentials,
                 String server,
                 int timeout,
                 String servicePath,
                 org.apache.hc.client5.http.impl.classic.CloseableHttpClient httpClient)

Create new api instance.

Parameters:

credentials - Credentials used to authenticate.

server - Server url without protocol. Example: my.geotab.com

timeout - Request timeout

servicePath - Service path. Default value is: apiv1

httpClient - Custom HttpClient in case custom configuration is needed

Method Detail

isAuthenticated

public boolean isAuthenticated()

Description copied from interface: Api

Check if the API is authenticated.

Should be authenticated only after explicit call to Api.authenticate() or any of the callXxx methods.

Specified by:

isAuthenticated in interface Api

authenticate

public LoginResult authenticate()

Description copied from interface: Api

Authenticates a user and provides a LoginResult if successful. It contains the Credentials property that can be used for further API calls. A result of LoginResult.Path = "ThisServer" occurs when the user is found on the current server. Otherwise, a server name is returned and the client must redirect to this new server name.

Maximum 10 Authentication requests per minute, per user.

Specified by:

authenticate in interface Api

call

public <O extends BaseResponse<T>,T> Optional<T> call(AuthenticatedRequest<?> in,
                                                      Class<O> outT)

Description copied from interface: Api

Makes a custom method API call specifying the response type. Always try to use one of the specific method variants * (Api.callGet(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>), Api.callGetFeed(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>), Api.callAdd(com.geotab.http.request.AuthenticatedRequest<?>), call{Method}, etc.) instead.

Specified by:

call in interface Api

callResult

public <T> Optional<T> callResult(AuthenticatedRequest<?> in,
                                  Class<T> outT)

Description copied from interface: Api

Makes a custom method API call specifying the result type. Always try to use one of the specific method variants (Api.callGet(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>), Api.callGetFeed(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>), Api.callAdd(com.geotab.http.request.AuthenticatedRequest<?>), call{Method}, etc.) instead.

Specified by:

callResult in interface Api

callMethod

public <P extends AuthenticatedParameters,R> Optional<R> callMethod(Api.MethodDescriptor<P,R> method,
                                                                    P params)

Description copied from interface: Api

Makes a web method call.

WARNING: Experimental API.

Specified by:

callMethod in interface Api

callResultList

public <T> Optional<List<T>> callResultList(AuthenticatedRequest<?> in,
                                            Class<T> outT)

Description copied from interface: Api

Makes a custom method API call specifying the element type of list result type.

Specified by:

callResultList in interface Api

callAdd

public Optional<Id> callAdd(AuthenticatedRequest<?> in)

Description copied from interface: Api

Makes an Add call.

Specified by:

callAdd in interface Api

callGet

public <T extends Entity> Optional<List<T>> callGet(AuthenticatedRequest<?> in,
                                                    Class<T> outT)

Description copied from interface: Api

Makes a Get call.

Specified by:

callGet in interface Api

callGetCountOf

public Optional<Integer> callGetCountOf(AuthenticatedRequest<?> in)

Description copied from interface: Api

Makes a GetCountOf call.

Specified by:

callGetCountOf in interface Api

callGetFeed

public <T extends Entity> Optional<FeedResult<T>> callGetFeed(AuthenticatedRequest<?> in,
                                                              Class<T> outT)

Description copied from interface: Api

Makes a GetFeed call.

Specified by:

callGetFeed in interface Api

callSet

public void callSet(AuthenticatedRequest<?> in)

Description copied from interface: Api

Makes a Set call.

Specified by:

callSet in interface Api

callRemove

public void callRemove(AuthenticatedRequest<?> in)

Description copied from interface: Api

Makes a Remove call.

Specified by:

callRemove in interface Api

multiCall

public <O extends BaseResponse<T>,T> Optional<T> multiCall(MultiCallRequest in,
                                                           Class<O> outT)

Description copied from interface: Api

Makes a type-safe API multi-call.

Response type needs to be constructed based on the multi-call response types expected. The API "result" is going to be an array, where each item is the result of the corresponding call.

Specified by:

multiCall in interface Api

Parameters:

in - MultiCallRequest request.

outT - Response type class, used to deserialize the response.

Returns:

The results for the multi-calls.

uniformMultiCall

public <T> Optional<List<T>> uniformMultiCall(List<? extends BaseRequest<?>> calls,
                                              Class<T> outT)

Description copied from interface: Api

Makes a uniform type-safe API multi-call.

All requests must return the same type. This method combine all responses sequentially into a single list. E.g. if 3 device search requests are made and each request returns 2 devices a single list with 6 devices is returned.

WARNING: Experimental API.

Specified by:

uniformMultiCall in interface Api

Parameters:

calls - List of requests. All request must have the same result type.

outT - The common type of all requests.

Returns:

A flat map of all the request.

buildMultiCall

public Api.MultiCallBuilder buildMultiCall()

Description copied from interface: Api

Builds a type-safe API multi-call. Accumulate request using Api.MultiCallBuilder.callResult(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>) and finalize it calling Api.MultiCallBuilder.execute(). The builder can not be reused and Api.MultiCallBuilder.execute() is always the last call.

WARNING: Experimental API.

Specified by:

buildMultiCall in interface Api

disconnect

public void disconnect()

close

public void close()

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

buildServerInvoker

protected ServerInvoker buildServerInvoker(String url,
                                           Integer timeout,
                                           String servicePath,
                                           org.apache.hc.client5.http.impl.classic.CloseableHttpClient httpClient)