com.veriplace.client
Class GetLocationAPI

java.lang.Object
  com.veriplace.client.AsyncCapableAPI<LocationRequestStatus>
      com.veriplace.client.GetLocationAPI

public class GetLocationAPI
extends AsyncCapableAPI<LocationRequestStatus>

Interface for obtaining a user's location from Veriplace. To access an instance of this class, use Client.getGetLocationAPI().

User location can only be obtained by referencing a valid Veriplace User. Users can be identified using the UserDiscoveryAPI.

An OAuth Access Token is required to obtain a User's location, which may be retrieved by redirecting the User Agent to Veriplace as part of the OAuth user authorization process. Access Tokens may be cached.

A typical update flow will look something like:

 // construct a callback URL
 String callback = client.prepareCallback(request) + "/callback";
 // construct the redirect URL for user authorization
 String redirectUrl = client.getGetLocationAPI().getRedirectURL(callback,user);
 // redirect the User Agent
 response.sendRedirect(redirectUrl);
 ...
 // handle the callback
 if (client.isCallback(request)) {
   // retrieve the Access Token, if any
   Token accessToken = client.getAccessToken(request);
   if (accessToken != null) {
     // update location
     Location location = client.getGetLocationAPI().getLocation(accessToken,user);
   }
 }
 

GetLocationAPI also supports querying the list of users who have granted location permission to your application (getPermittedUsers()).

See Also:

Veriplace Developer Guide: Using the Get Location API, Veriplace Developer Guide: Using the Past Location API, Veriplace Developer Guide: Using the Get Permissions API

Method Summary

LocationRequestStatus	getCallbackResult(HttpServletRequest request, HttpServletResponse response) Process the parameters of an HTTP callback that was posted from Veriplace in response to an asynchronous location request.
java.lang.String	getDefaultLocationMode() Get the default location mode for this client, if any.
Location	getLocation(Token accessToken, User user) Deprecated. Use getLocation(User, Token).
Location	getLocation(Token accessToken, User user, int timeout) Deprecated. Use getLocation(User, Token, LocationOptions).
Location	getLocation(Token accessToken, User user, java.lang.String mode) Deprecated. Use getLocation(User, Token, LocationOptions).
Location	getLocation(Token accessToken, User user, java.lang.String mode, java.lang.Integer timeout) Deprecated. Use getLocation(User, Token, LocationOptions).
Location	getLocation(User user, Token accessToken) Get a user's location.
Location	getLocation(User user, Token accessToken, LocationOptions options) Get a user's location, specifying optional properties of the request.
Token	getLocationAccessToken(User user) Get an access token representing permission to locate a user, if the user has previously granted that permission.
Location	getLocationById(Token accessToken, User user, long locationId) Deprecated. Use getLocationById(User, long, Token, LocationOptions).
Location	getLocationById(User user, long locationId, Token accessToken, LocationOptions options) Get a previously obtained location again by its location ID, specifying optional properties of the request.
LocationFilter	getLocationFilter() Get the LocationFilter implementation for this client, if any.
java.util.List<User>	getPermittedUsers() Get a list of users granting permission.
java.util.List<User>	getPermittedUsers(int first, int max) Get a list of users granting permission with paging.
java.lang.String	getRedirectURL(java.lang.String callback, User user) Get the URL to use for OAuth redirection to get permission to locate a user.
java.lang.String	getRedirectURL(java.lang.String callback, User user, boolean immediate) Get the URL to use for OAuth redirection to get permission to locate a user.
LocationRequestStatus	getResult(LocationRequestStatus request) Attempt to retrieve the result of an asynchronous request that was previously submitted with requestLocation(Token, User, String, String).
LocationRequestStatus	requestLocation(Token accessToken, User user, java.lang.String mode, java.lang.String callback) Deprecated. Use requestLocation(User, Token, String, LocationOptions).
LocationRequestStatus	requestLocation(User user, Token accessToken, LocationOptions locationOptions, CallbackOptions callbackOptions) Submit an asynchronous request for a user's location, with options for extended callback behavior.
LocationRequestStatus	requestLocation(User user, Token accessToken, java.lang.String callback, LocationOptions options) Submit an asynchronous request for a user's location.

Methods inherited from class java.lang.Object

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

Method Detail

getRedirectURL

public java.lang.String getRedirectURL(java.lang.String callback,
                                       User user)
                                throws TransportException,
                                       VeriplaceOAuthException

Get the URL to use for OAuth redirection to get permission to locate a user. By default, the user will be allowed to log in interactively if necessary.

Parameters:

callback - the OAuth callback url

user - the user to be located

Returns:

the OAuth redirection url

Throws:

TransportException

VeriplaceOAuthException

getRedirectURL

public java.lang.String getRedirectURL(java.lang.String callback,
                                       User user,
                                       boolean immediate)
                                throws TransportException,
                                       VeriplaceOAuthException

Get the URL to use for OAuth redirection to get permission to locate a user.

Parameters:

callback - the OAuth callback url

user - the user to be located

immediate - should responses return immediately if user interaction would be required?

Returns:

the OAuth redirection url

Throws:

TransportException

VeriplaceOAuthException

getDefaultLocationMode

public java.lang.String getDefaultLocationMode()

Get the default location mode for this client, if any.

Since:

2.0

getLocationFilter

public LocationFilter getLocationFilter()

Get the LocationFilter implementation for this client, if any.

Since:

2.1

getLocation

public Location getLocation(User user,
                            Token accessToken)
                     throws GetLocationException,
                            UnexpectedException

Get a user's location.

Parameters:

user - the user

accessToken - the access token permitting the user to be located

Returns:

the user's location

Throws:

GetLocationException - if the server refused the location request

UnexpectedException - if there was an unexpected I/O error or OAuth error

getLocation

public Location getLocation(User user,
                            Token accessToken,
                            LocationOptions options)
                     throws GetLocationException,
                            UnexpectedException

Get a user's location, specifying optional properties of the request.

Parameters:

user - the user

accessToken - the access token permitting the user to be located

options - a LocationOptions object allowing the location mode and other properties to be overriden for this request; null to use default options

Returns:

the user's location

Throws:

GetLocationException - if the server refused the location request

UnexpectedException - if there was an unexpected I/O error or OAuth error

Since:

2.7

getLocationById

public Location getLocationById(User user,
                                long locationId,
                                Token accessToken,
                                LocationOptions options)
                         throws GetLocationException,
                                UnexpectedException

Get a previously obtained location again by its location ID, specifying optional properties of the request.

Parameters:

user - the user who was previously located

locationId - a unique location result identifier previously obtained from Location.getId()

accessToken - an access token for permission to locate the user in question

options - a LocationOptions object which can specify additional information to obtain on the location (see LocationOptions.withExtraInfo(com.veriplace.client.LocationOptions.ExtraInfo...) and/or a timeout for the request; null to use default options

Returns:

the location data

Throws:

GetLocationException - if the server refused the location request

UnexpectedException - if there was an unexpected I/O error or OAuth error

Since:

2.7

requestLocation

public LocationRequestStatus requestLocation(User user,
                                             Token accessToken,
                                             java.lang.String callback,
                                             LocationOptions options)
                                      throws GetLocationException,
                                             UnexpectedException

Submit an asynchronous request for a user's location.

You may poll for the result with getResult(LocationRequestStatus), or specify a callback URI, in which case Veriplace will send an HTTP POST message to that URI when the result is ready; you can process the callback message with getCallbackResult(HttpServletRequest, HttpServletResponse). This version generates only a summary message in the callback; to get the full result by callback, use requestLocation(User, Token, LocationOptions, CallbackOptions).

Parameters:

user - the user

accessToken - the access token permitting the user to be located

callback - a callback URI to which Veriplace should post the result when it is ready, or null if you will poll for the result

options - a LocationOptions object allowing the location mode and other properties to be overridden for this request; null to use default options

Returns:

a LocationRequestStatus that uniquely identifies the request

Throws:

GetLocationException - if the server refused the location request

UnexpectedException - if there was an unexpected I/O error or OAuth error

Since:

2.7

requestLocation

public LocationRequestStatus requestLocation(User user,
                                             Token accessToken,
                                             LocationOptions locationOptions,
                                             CallbackOptions callbackOptions)
                                      throws GetLocationException,
                                             UnexpectedException

Submit an asynchronous request for a user's location, with options for extended callback behavior.

This version of the method takes a CallbackOptions parameter, which, if not null, can specify both a callback URI for receiving the result of the request and additional options for the format of the result message. You can process the callback message with getCallbackResult(HttpServletRequest, HttpServletResponse). If you don't specify a callback, use getResult(LocationRequestStatus) to poll for the result.

Parameters:

user - the user

accessToken - the access token permitting the user to be located

locationOptions - a LocationOptions object allowing the location mode and other properties to be overridden for this request; null to use default options

callbackOptions - an optional CallbackOptions object specifying how Veriplace should post the result back to you when ready; null if you will poll for the result

Returns:

a LocationRequestStatus that uniquely identifies the request

Throws:

GetLocationException - if the server refused the location request

UnexpectedException - if there was an unexpected I/O error or OAuth error

Since:

2.8

getResult

public LocationRequestStatus getResult(LocationRequestStatus request)
                                throws RequestNotFoundException,
                                       UnexpectedException

Attempt to retrieve the result of an asynchronous request that was previously submitted with requestLocation(Token, User, String, String). Use this method if you did not specify a callback URI in the original request.

If the request is still in progress, this will return the same request status object. If the request has completed, either successfully or unsuccessfully, it will return an updated request status object whose AsyncRequestStatus.isReady() method will return true, and which will either contain a Location object (LocationRequestStatus.getLocation()) or an error (LocationRequestStatus.getException()).

Overrides:

getResult in class AsyncCapableAPI<LocationRequestStatus>

Parameters:

request - the original request status object

Returns:

an updated request status object of the same type

Throws:

RequestNotFoundException - if the request is no longer valid, i.e. it has expired or the result was already delivered via a callback notification

UnexpectedException - if there was an unexpected OAuth error or I/O error, or if the request is no longer valid

getCallbackResult

public LocationRequestStatus getCallbackResult(HttpServletRequest request,
                                               HttpServletResponse response)
                                        throws UnexpectedException

Process the parameters of an HTTP callback that was posted from Veriplace in response to an asynchronous location request.

The resulting LocationRequestStatus object will contain either a location ID (LocationRequestStatus.getLocationId() or an error (LocationRequestStatus.getException()). It will not contain the actual location details; Veriplace does not deliver those by callback, for security reasons. Instead, you can pass the location ID to getLocationById(Token, User, long) to get the location details.

The status object's AsyncRequestStatus.getId() method will return the same unique identifier that was generated by the original request, which you can use to associate any previously stored request state with the result.

To confirm receipt of the callback, this method also sends an immediate HTTP 200 ("OK") response to Veriplace, completing the HTTP response. Do not try to do anything else with the response object after this; if your application returned anything else, or did not respond, Veriplace would repeat the callback.

Overrides:

getCallbackResult in class AsyncCapableAPI<LocationRequestStatus>

Parameters:

request - the current HTTP request

response - the current HTTP response (see above)

Returns:

a LocationRequestStatus object

Throws:

UnexpectedException - if the request did not contain valid parameters

getLocationAccessToken

public Token getLocationAccessToken(User user)
                             throws GetLocationNotPermittedException,
                                    UnexpectedException

Get an access token representing permission to locate a user, if the user has previously granted that permission. If so, the token can then be passed to getLocation(Token, User) to get the location; or you can simply use this method to test whether permission is available.

Parameters:

user - the user

Returns:

the access token; will not be null

Throws:

GetLocationNotPermittedException - if permission is not available

UnexpectedException - if there was an unexpected I/O error or OAuth error

Since:

2.0

getPermittedUsers

public java.util.List<User> getPermittedUsers()
                                       throws UserDiscoveryNotPermittedException,
                                              UnexpectedException

Get a list of users granting permission.

Throws:

UserDiscoveryNotPermittedException - if the service refused the get permissions request

UnexpectedException - if there was an unexpected I/O error or OAuth error

Since:

2.2

getPermittedUsers

public java.util.List<User> getPermittedUsers(int first,
                                              int max)
                                       throws UserDiscoveryNotPermittedException,
                                              UnexpectedException

Get a list of users granting permission with paging.

Parameters:

first - the index of the first result, starting with zero

max - the maximum number of results

Throws:

UserDiscoveryNotPermittedException - if the service refused the get permissions request

UnexpectedException - if there was an unexpected I/O error or OAuth error

Since:

2.2

getLocation

@Deprecated
public Location getLocation(Token accessToken,
                                       User user)
                     throws GetLocationException,
                            UnexpectedException

Deprecated. Use getLocation(User, Token).

Throws:

GetLocationException

UnexpectedException

getLocation

@Deprecated
public Location getLocation(Token accessToken,
                                       User user,
                                       int timeout)
                     throws GetLocationException,
                            UnexpectedException

Deprecated. Use getLocation(User, Token, LocationOptions).

Throws:

GetLocationException

UnexpectedException

getLocation

@Deprecated
public Location getLocation(Token accessToken,
                                       User user,
                                       java.lang.String mode)
                     throws GetLocationException,
                            UnexpectedException

Deprecated. Use getLocation(User, Token, LocationOptions).

Throws:

GetLocationException

UnexpectedException

getLocation

@Deprecated
public Location getLocation(Token accessToken,
                                       User user,
                                       java.lang.String mode,
                                       java.lang.Integer timeout)
                     throws GetLocationException,
                            UnexpectedException

Deprecated. Use getLocation(User, Token, LocationOptions).

Throws:

GetLocationException

UnexpectedException

getLocationById

@Deprecated
public Location getLocationById(Token accessToken,
                                           User user,
                                           long locationId)
                         throws GetLocationException,
                                UnexpectedException

Deprecated. Use getLocationById(User, long, Token, LocationOptions).

Throws:

GetLocationException

UnexpectedException

requestLocation

@Deprecated
public LocationRequestStatus requestLocation(Token accessToken,
                                                        User user,
                                                        java.lang.String mode,
                                                        java.lang.String callback)
                                      throws GetLocationException,
                                             UnexpectedException

Deprecated. Use requestLocation(User, Token, String, LocationOptions).

Throws:

GetLocationException

UnexpectedException