com.veriplace.web
Class VeriplaceState

java.lang.Object
  com.veriplace.web.VeriplaceState

public class VeriplaceState
extends java.lang.Object

Veriplace user, location, and permission information associated with the current HTTP request.

When you start processing a request, call Veriplace.open(HttpServletRequest, HttpServletResponse) on the Veriplace object to obtain an instance of VeriplaceState. (The state object is cached, so you can always obtain the same one by passing the same request to open().) Whenever a method such as Veriplace.requireLocation(VeriplaceState) completes successfully, it updates the properties of the VeriplaceState.

Constructor Summary

VeriplaceState(Veriplace veriplace, HttpServletRequest request, HttpServletResponse response)

Method Summary

java.lang.String	getAllFields() Creates HTML hidden form fields for all currently defined persistent attributes.
java.util.Map<java.lang.String,java.lang.String[]>	getCallbackParameters() Returns the names and values of all HTTP query string or form parameters that will be preserved across a redirect and callback.
static VeriplaceState	getFromRequest(HttpServletRequest request) Returns a VeriplaceState instance if one has previously been attached to the given HTTP request using Veriplace.open(HttpServletRequest, HttpServletResponse), or null if there is none.
Token	getGetLocationPermissionToken() Returns the current permission token for getting location, if any.
VeriplaceException	getLastErrorException() Returns the last VeriplaceException that occurred for the current request, or null if the last request was successful.
Location	getLocation() Returns the Location object describing the last acquired location of the current Veriplace user, or null if you have not acquired a location.
java.lang.String	getLocationMode() See setLocationMode(String).
LocationOptions	getLocationOptions() Gets a LocationOptions object which can be used to specify optional properties of the next location request, such as location mode and additional geographic queries.
HttpServletRequest	getRequest() Returns the current HttpServletRequest.
HttpServletResponse	getResponse() Returns the current HttpServletResponse.
User	getUser() Returns the User object representing the current Veriplace user, or null if the user has not yet been determined.
java.lang.String	getUserFields() Creates HTML hidden form fields for the current user identity.
Veriplace	getVeriplace() Returns the current Veriplace instance.
boolean	hasGetLocationPermission() Returns true if you have obtained permission to get a user's location.
boolean	isAsynchronousRequestAllowed() See setAsynchronousRequestAllowed(boolean).
boolean	isCallback() Returns true if this request originated in a callback from the Veriplace website.
boolean	isError() Returns true if the last request caused an error.
boolean	isUserInteractionAllowed() See setUserInteractionAllowed(boolean).
void	requireGetLocationPermission() Attempts to obtain permission to locate the current Veriplace user, if that permission isn't already present in the current state.
void	requireGetLocationPermissionImmediate() Attempts to obtain permission to locate the current Veriplace user, if that permission isn't already present in the current state.
void	requireLocation() Attempts to locate the current Veriplace user, if a location isn't already present in the current state.
void	requireLocation(long locationId) Attempts to retrieve a previously retrieved location again, using its ID (from Location.getId()).
void	requireUser() Attempts to acquire the current Veriplace user identifier, if it isn't already present in the current state.
void	requireUser(UserDiscoveryParameters parameters) Attempts to acquire the current Veriplace user identifier using identifying information in UserDiscoveryParameters.
void	requireUserImmediate() Attempts to acquire the current Veriplace user identifier, if it isn't already present in the current state, without providing any identifying properties and without redirecting.
void	setAsynchronousRequestAllowed(boolean asynchronousRequestAllowed) Specifies whether the Veriplace client can perform location requests asynchronously using a background thread.
void	setCallbackParameter(java.lang.String name, java.lang.Long value) Specifies an additional HTTP parameter to be preserved across redirects and callbacks.
void	setCallbackParameter(java.lang.String name, java.lang.String value) Specifies an additional HTTP parameter to be preserved across redirects and callbacks.
void	setCallbackParameter(java.lang.String name, java.lang.String[] values) Specifies an additional HTTP parameter to be preserved across redirects and callbacks.
void	setGetLocationPermissionToken(Token token) Specifies an access token for getting location.
void	setLocationMode(java.lang.String locationModeName) Sets the location mode to be used for subsequent location requests on this state.
void	setLocationOptions(LocationOptions locationOptions) Specifies a LocationOptions object whose properties will be used for the next location request.
void	setUser(long userId) Sets the current Veriplace user.
void	setUser(User user) Sets the current Veriplace user.
void	setUserInteractionAllowed(boolean userInteractionAllowed) Specifies whether the Veriplace server is allowed to prompt the end user to log in or to grant location permission.

Methods inherited from class java.lang.Object

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

Constructor Detail

VeriplaceState

public VeriplaceState(Veriplace veriplace,
                      HttpServletRequest request,
                      HttpServletResponse response)

Method Detail

getFromRequest

public static VeriplaceState getFromRequest(HttpServletRequest request)

Returns a VeriplaceState instance if one has previously been attached to the given HTTP request using Veriplace.open(HttpServletRequest, HttpServletResponse), or null if there is none.

getVeriplace

public Veriplace getVeriplace()

Returns the current Veriplace instance.

getRequest

public HttpServletRequest getRequest()

Returns the current HttpServletRequest.

getResponse

public HttpServletResponse getResponse()

Returns the current HttpServletResponse.

getUser

public User getUser()

Returns the User object representing the current Veriplace user, or null if the user has not yet been determined. To discover the current user, call Veriplace.requireUser(VeriplaceState).

setUser

public void setUser(User user)

Sets the current Veriplace user. You may wish to do this directly if you had previously obtained a user with Veriplace.requireUser(VeriplaceState) and stored the user object for future reference.

See Also:

setUser(long)

setUser

public void setUser(long userId)

Sets the current Veriplace user. You may wish to do this directly if you had previously obtained a user with Veriplace.requireUser(VeriplaceState) and stored the user object for future reference.

See Also:

setUser(User)

getLocation

public Location getLocation()

Returns the Location object describing the last acquired location of the current Veriplace user, or null if you have not acquired a location. To acquire a location, call Veriplace.requireLocation(VeriplaceState).

getLocationMode

public java.lang.String getLocationMode()

See setLocationMode(String).

setLocationMode

public void setLocationMode(java.lang.String locationModeName)

Sets the location mode to be used for subsequent location requests on this state. See LocationMode for allowable values.

See Also:

getLocationOptions()

getLocationOptions

public LocationOptions getLocationOptions()

Gets a LocationOptions object which can be used to specify optional properties of the next location request, such as location mode and additional geographic queries.

setLocationOptions

public void setLocationOptions(LocationOptions locationOptions)

Specifies a LocationOptions object whose properties will be used for the next location request.

isUserInteractionAllowed

public boolean isUserInteractionAllowed()

See setUserInteractionAllowed(boolean).

setUserInteractionAllowed

public void setUserInteractionAllowed(boolean userInteractionAllowed)

Specifies whether the Veriplace server is allowed to prompt the end user to log in or to grant location permission. By default, it is. If you set this value to false, then user discovery or location requests may still redirect silently to the Veriplace server (because OAuth authentication requires this), but if the server does not already know the user's identity or if the user has not already granted permission, the request will immediately fail.

isAsynchronousRequestAllowed

public boolean isAsynchronousRequestAllowed()

See setAsynchronousRequestAllowed(boolean).

setAsynchronousRequestAllowed

public void setAsynchronousRequestAllowed(boolean asynchronousRequestAllowed)

Specifies whether the Veriplace client can perform location requests asynchronously using a background thread. By default, it will; this requires that the application be able to handle a WaitingException by displaying a progress page. Setting this flag to false causes the client to perform all requests on the main thread; it will never throw a WaitingException in that case.

hasGetLocationPermission

public boolean hasGetLocationPermission()

Returns true if you have obtained permission to get a user's location.

isCallback

public boolean isCallback()

Returns true if this request originated in a callback from the Veriplace website.

isError

public boolean isError()

Returns true if the last request caused an error. Call getLastErrorException() to get the details of the error.

getLastErrorException

public VeriplaceException getLastErrorException()

Returns the last VeriplaceException that occurred for the current request, or null if the last request was successful. Note that a WaitingException will not cause this property to be set, since it is not really an error.

getCallbackParameters

public java.util.Map<java.lang.String,java.lang.String[]> getCallbackParameters()

Returns the names and values of all HTTP query string or form parameters that will be preserved across a redirect and callback.

setCallbackParameter

public void setCallbackParameter(java.lang.String name,
                                 java.lang.String value)

Specifies an additional HTTP parameter to be preserved across redirects and callbacks.

setCallbackParameter

public void setCallbackParameter(java.lang.String name,
                                 java.lang.Long value)

Specifies an additional HTTP parameter to be preserved across redirects and callbacks.

setCallbackParameter

public void setCallbackParameter(java.lang.String name,
                                 java.lang.String[] values)

Specifies an additional HTTP parameter to be preserved across redirects and callbacks.

getGetLocationPermissionToken

public Token getGetLocationPermissionToken()

Returns the current permission token for getting location, if any. If an asynchronous location request is currently in progress, then this method will reutrn null even though a permission token has been obtained.

setGetLocationPermissionToken

public void setGetLocationPermissionToken(Token token)

Specifies an access token for getting location. Use this only if you're reusing a stored access token that you know to be valid; otherwise just call Veriplace.requireGetLocationPermission(VeriplaceState).

getUserFields

public java.lang.String getUserFields()

Creates HTML hidden form fields for the current user identity. Using JSP expression syntax, if the attribute name "state" refers to the VeriplaceState, you can simply write ${state.userFields} to include these fields in a form.

getAllFields

public java.lang.String getAllFields()

Creates HTML hidden form fields for all currently defined persistent attributes. Using JSP expression syntax, if the attribute name "state" refers to the VeriplaceState, you can simply write ${state.allFields} to include these fields in a form.

requireUser

public void requireUser()
                 throws RespondedException,
                        UserDiscoveryException,
                        UnexpectedException,
                        ServletException

Attempts to acquire the current Veriplace user identifier, if it isn't already present in the current state. After this method returns, call getUser() on the VeriplaceState to get the Veriplace User object.

If the user has already been acquired, or set explicitly with setUser(com.veriplace.client.User), the method returns immediately. Otherwise, it redirects to the Veriplace server to begin a user discovery transaction. If the server can detect the current user without interaction, it redirects immediately back to your application; otherwise it prompts the user to log in (unless you have disabled this with setUserInteractionAllowed(boolean)) and redirects back once they have done so.

When your application receives the callback, it will be to the same URL and with the same HTTP parameters as the initial request, but with an additional token to indicate that the user is now available. You do not need to check for this token; just call requireUser() as you did before, and this time the method will return normally.

Throws:

RespondedException - if the client has sent a redirect response; you should simply stop handling the request and return in this case

UserDiscoveryException - if the current user could not be determined

UnexpectedException - if there was an unexpected I/O error or OAUth error from the server

ServletException

requireUser

public void requireUser(UserDiscoveryParameters parameters)
                 throws RespondedException,
                        UserDiscoveryException,
                        UnexpectedException,
                        ServletException

Attempts to acquire the current Veriplace user identifier using identifying information in UserDiscoveryParameters. In order to do this, you must have specified an application token and token secret in your Veriplace client configuration (see ClientFactory).

If the user has already been acquired, or set explicitly with setUser(com.veriplace.client.User), the method returns immediately. Otherwise, it submits a request to the Veriplace server which will either succeed or immediately fail; there are no redirects. If the method returns with no exceptions, call getUser() to get the user object.

Parameters:

parameters - the identifying properties of the desired user

Throws:

RespondedException - can happen only if you've configured an automatic error response page; return immediately in this case

UserDiscoveryException - if the user could not be found or your application lacks privileges

UnexpectedException - if there was an unexpected I/O error or OAUth error from the server

ServletException

requireUserImmediate

public void requireUserImmediate()
                          throws UserDiscoveryNotPermittedException,
                                 UnexpectedException,
                                 ServletException

Attempts to acquire the current Veriplace user identifier, if it isn't already present in the current state, without providing any identifying properties and without redirecting. This will only work if you have just received a callback from a successful user discovery transaction.

If the user has already been acquired, or set explicitly with setUser(com.veriplace.client.User), the method returns immediately. Otherwise, it submits a request to the Veriplace server which will either succeed or immediately fail; there are no redirects.

If the method returns with no exceptions, call getUser() to get the user object.

Throws:

UserDiscoveryNotPermittedException - if you do not have a valid user discovery access token

UnexpectedException - if there was an unexpected I/O error or OAUth error from the server

ServletException

requireGetLocationPermission

public void requireGetLocationPermission()
                                  throws RespondedException,
                                         RequestDeniedException,
                                         UnexpectedException,
                                         ServletException

Attempts to obtain permission to locate the current Veriplace user, if that permission isn't already present in the current state. If you haven't already identified the user using requireUser() or setUser(com.veriplace.client.User), then this calls requireUser() first.

If this method returns with no exceptions, permission is now available. You can call getGetLocationPermissionToken() to get the permisison token, if you need to save it for future reuse. Note: if an asynchronous location request is currently in progress, then getGetLocationPermissionToken() will return null even though permission has been obtained, so make sure the value is non-null before you try to do anything with the token.

Either the user discovery step or the permission step may cause a redirect to the Veriplace site. When Veriplace redirects back to your application, it will be to the same URL and with the same HTTP parameters as the initial request, but with an additional token to indicate that the permission is now available. You do not need to check for this token; just call requireGetLocationPermission(state) as you did before, and this time the method will return normally.

The Veriplace instance maintains a token cache containing the last known valid permission token for each user, which it will try to reuse if you call requireLocation(). However, it will not use this cache if you call requireGetLocationPermission separately from requireLocation, because the token might have expired and there would be no way to know this if you didn't go on to actually request a location. Therefore, requireGetLocationPermission always asks the Veriplace server for a current permission.

Throws:

RespondedException - if the client has sent a redirect response; you should simply stop handling the request and return in this case

RequestDeniedException - if either the user discovery request or the permission request was denied (check the subclass of the exception to see which one)

UnexpectedException - if there was an unexpected I/O error or OAUth error from the server

ServletException

requireGetLocationPermissionImmediate

public void requireGetLocationPermissionImmediate()
                                           throws GetLocationNotPermittedException,
                                                  UserDiscoveryException,
                                                  UnexpectedException

Attempts to obtain permission to locate the current Veriplace user, if that permission isn't already present in the current state. The user must already have been identified with requireUser() or setUser(com.veriplace.client.User). This method will not perform any redirects and will not ask the user for permission if it wasn't previously granted; it will simply fail in that case. If this method returns with no exceptions, permission is now available. You can call getGetLocationPermissionToken() to get the permission token, if you need to save it for future reuse.

The Veriplace instance maintains a token cache containing the last known valid permission token for each user, which it will try to reuse if you call requireLocation(). However, requireGetLocationPermissionImmediate does not use this cache; it always asks the Veriplace server for a current permission.

Throws:

GetLocationNotPermittedException - if the permission request was denied

UserDiscoveryException - if you did not provide a valid user

UnexpectedException - if there was an unexpected I/O error or OAUth error from the server

requireLocation

public void requireLocation()
                     throws RespondedException,
                            WaitingException,
                            RequestDeniedException,
                            UnexpectedException,
                            ServletException

Attempts to locate the current Veriplace user, if a location isn't already present in the current state. If you haven't already identified the user or obtained location permission, then this calls requireUser() and/or requireGetLocationPermission() first in the correct order.

If this method returns with no exceptions, call getLocation() on the VeriplaceState to get the location data.

Either the user discovery step or the permission step may cause a redirect to the Veriplace site. When Veriplace redirects back to your application, it will be to the same URL and with the same HTTP parameters as the initial request, but with an additional token to indicate that the location is now available. You do not need to check for this token; just call requireLocation(state) as you did before, and this time the method will return normally.

Since it can take a noticeable amount of time to acquire location (if a new GPS fix is required), by default all location requests are done asynchronously on a separate thread. This allows you to give the user some feedback in the meantime, such as a "please wait" page. Veriplace handles this by throwing a WaitingException, which contains a callback URL for continuing the current request; if you display a page that automatically redirects to that URL after a few seconds, your application will pick up where it left off, so that the next call to requireLocation(state) will either acquire the result or throw another WaitingException. (This process can be automated by designating a Waiting page ahead of time; see StatusViewRenderer. If you use that approach, you will never get a WaitingException.)

Throws:

RespondedException - if the client has sent a redirect response; you should simply stop handling the request and return in this case

RequestDeniedException - if either the user discovery request or the permission request was denied (check the subclass of the exception to see which one)

WaitingException - if an asynchronous request is in progress and you should display an intermediate status page

UnexpectedException - if there was an unexpected I/O error or OAUth error from the server

ServletException

requireLocation

public void requireLocation(long locationId)
                     throws RespondedException,
                            RequestDeniedException,
                            UnexpectedException,
                            ServletException

Attempts to retrieve a previously retrieved location again, using its ID (from Location.getId()). If you haven't already identified the user or obtained location permission, then this calls requireUser() and/or requireGetLocationPermission() first in the correct order, which may involve redirects. However, the location request itself happens synchronously as a single server call.

If this method returns with no exceptions, call getLocation() to get the location data.

Throws:

RespondedException - if the client has sent a redirect response; you should simply stop handling the request and return in this case

RequestDeniedException - if either the user discovery request or the permission request was denied (check the subclass of the exception to see which one)

UnexpectedException - if there was an unexpected I/O error or OAUth error from the server

ServletException