com.veriplace.web
Class Veriplace

java.lang.Object
  com.veriplace.web.Veriplace

public class Veriplace
extends java.lang.Object

Veriplace client for web applications. The web client hides many of the details of Veriplace's OAuth-based authorization process, providing a persistent state across transactions that may involve redirects and callbacks.

An instance of Veriplace manages the following resources:

• A Client which handles communication with the Veriplace server. This is the lower-level client API, which you can still access if desired.
• Asynchronous request managers which allow time-consuming requests to run on background threads.
• Token caches to preserve user access tokens transparently across callbacks.
• A Redirector allowing Veriplace to perform browser redirects transparently.
• An optional StatusViewRenderer allowing Veriplace to display error or waiting pages automatically.

All of this class's methods operate on a VeriplaceState object, which holds all the information that is associated with the current HTTP request. When a request completes successfully, it updates the VeriplaceState's properties.

If a request cannot be completed, it throws a subclass of VeriplaceException. The web client defines several new exception classes for non-error conditions that can interrupt the handling of a request: RespondedException, which usually means that the user has been redirected to the Veriplace site, and WaitingException, which means that the application is waiting for an asynchronous request and may wish to display an intermediate status page.

The standard Veriplace frameworks for servlets (AbstractVeriplaceServlet) and Spring servlets (VeriplaceInterceptor), and the JSP tag library, take care of creating and configuring the Veriplace instance and calling the appropriate methods to acquire user or location data; applications using those frameworks will usually just interact with the VeriplaceState class to get the data.

Constructor Summary

protected	Veriplace()
	Veriplace(Client client) Creates a Veriplace instance using an existing Client.
	Veriplace(ClientFactory clientFactory) Creates a Veriplace instance using a specific ClientFactory.
	Veriplace(java.util.Properties properties) Creates a Veriplace instance and initializes its Client using a Properties object, with the keys defined by DefaultClientFactory.
	Veriplace(java.lang.String propertiesFileName) Creates a Veriplace instance and initializes its Client using properties file, with the keys defined by ClientFactory.
	Veriplace(Veriplace fromInstance, Client newClient) Creates a Veriplace instance with the same properties as another instance, but using a different Veriplace client.

Method Summary

java.lang.String	getCallbackUrl(VeriplaceState state) Constructs a URL for returning to the current request from an external page, and passing along any necessary attributes to recreate the current state.
Client	getClient() Returns the Client that handles lower-level communications with the Veriplace server.
ClientFactory	getClientFactory() Returns the currently configured ClientFactory, if any.
GetLocationRequestManager	getGetLocationRequestManager() See setGetLocationRequestManager(GetLocationRequestManager).
UserTokenStore	getGetLocationTokenStore() See setGetLocationTokenStore(UserTokenStore).
java.util.Properties	getProperties()
Redirector	getRedirector() See setRedirector(Redirector).
StatusViewRenderer	getStatusViewRenderer() See setStatusViewRenderer(StatusViewRenderer).
VeriplaceState	open(HttpServletRequest request, HttpServletResponse response) Creates a new VeriplaceState object for the current HTTP request.
void	requireGetLocationPermission(VeriplaceState state) Deprecated.
void	requireGetLocationPermissionImmediate(VeriplaceState state) Deprecated.
void	requireLocation(VeriplaceState state) Deprecated.
void	requireLocation(VeriplaceState state, long locationId) Deprecated.
void	requireUser(VeriplaceState state) Deprecated.
void	requireUser(VeriplaceState state, UserDiscoveryParameters parameters) Deprecated.
void	requireUserImmediate(VeriplaceState state) Deprecated.
void	setGetLocationRequestManager(GetLocationRequestManager lrm) Designates a GetLocationRequestManager object to provide background processing of location requests.
void	setGetLocationTokenStore(UserTokenStore store) Designates a UserTokenStore object to provide cacheing of Veriplace access tokens.
void	setRedirector(Redirector redirector) Designates a Redirector object which will take care of sending redirect responses.
void	setStatusViewRenderer(StatusViewRenderer statusViewRenderer) Designates a StatusViewRenderer object which will be used to display special status pages (errors, or a "please wait" page) if appropriate.
protected void	tryStatusView(VeriplaceState state, java.lang.Exception e, java.lang.String callbackUrl)

Methods inherited from class java.lang.Object

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

Constructor Detail

Veriplace

protected Veriplace()

Veriplace

public Veriplace(Client client)

Creates a Veriplace instance using an existing Client.

Veriplace

public Veriplace(ClientFactory clientFactory)
          throws ConfigurationException

Creates a Veriplace instance using a specific ClientFactory.

Throws:

ConfigurationException - if a configuration property is invalid

Veriplace

public Veriplace(java.util.Properties properties)
          throws ConfigurationException

Creates a Veriplace instance and initializes its Client using a Properties object, with the keys defined by DefaultClientFactory.

Throws:

ConfigurationException - if a configuration property is invalid

Veriplace

public Veriplace(java.lang.String propertiesFileName)
          throws java.io.IOException,
                 ConfigurationException

Creates a Veriplace instance and initializes its Client using properties file, with the keys defined by ClientFactory.

Throws:

ConfigurationException - if a configuration property is invalid

java.io.IOException

Veriplace

public Veriplace(Veriplace fromInstance,
                 Client newClient)

Creates a Veriplace instance with the same properties as another instance, but using a different Veriplace client. You may wish to do this if your application needs to change its configuration on the fly for certain requests, without interfering with requests that are being handled on other threads.

Method Detail

getClient

public Client getClient()

Returns the Client that handles lower-level communications with the Veriplace server. This object provides several capabilities that don't have corresponding methods in the web client API, simply because they don't require any transaction state management and are not needed by most applications, such as the methods in PermissionAPI.

getClientFactory

public ClientFactory getClientFactory()

Returns the currently configured ClientFactory, if any.

getProperties

public java.util.Properties getProperties()

getRedirector

public Redirector getRedirector()

See setRedirector(Redirector).

setRedirector

public void setRedirector(Redirector redirector)

Designates a Redirector object which will take care of sending redirect responses. If you don't specify otherwise, it uses DefaultRedirector.

getStatusViewRenderer

public StatusViewRenderer getStatusViewRenderer()

See setStatusViewRenderer(StatusViewRenderer).

setStatusViewRenderer

public void setStatusViewRenderer(StatusViewRenderer statusViewRenderer)

Designates a StatusViewRenderer object which will be used to display special status pages (errors, or a "please wait" page) if appropriate. This should normally be an instance of ServletStatusViewRenderer, except for Spring applications which should use SpringStatusViewRenderer. If you do not have a ViewRenderer, you can still make a request but you will have to catch errors (or WaitingException) and handle them appropriately.

getGetLocationRequestManager

public GetLocationRequestManager getGetLocationRequestManager()

See setGetLocationRequestManager(GetLocationRequestManager).

setGetLocationRequestManager

public void setGetLocationRequestManager(GetLocationRequestManager lrm)

Designates a GetLocationRequestManager object to provide background processing of location requests. By default, it will use an implementation based on MemoryRequestStore.

getGetLocationTokenStore

public UserTokenStore getGetLocationTokenStore()

See setGetLocationTokenStore(UserTokenStore).

setGetLocationTokenStore

public void setGetLocationTokenStore(UserTokenStore store)

Designates a UserTokenStore object to provide cacheing of Veriplace access tokens. By default, it will use a MemoryUserTokenStore.

open

public VeriplaceState open(HttpServletRequest request,
                           HttpServletResponse response)

Creates a new VeriplaceState object for the current HTTP request. This object receives the results of user and location queries, and maintains other information (access tokens and callback state) that allow operations to be carried out across multiple requests and callbacks.

requireUser

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

Deprecated.

Deprecated. Use VeriplaceState.requireUser().

Throws:

RespondedException

UserDiscoveryException

UnexpectedException

ServletException

requireUser

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

Deprecated.

Deprecated. Use VeriplaceState.requireUser(UserDiscoveryParameters).

Throws:

RespondedException

UserDiscoveryException

UnexpectedException

ServletException

requireUserImmediate

public void requireUserImmediate(VeriplaceState state)
                          throws UserDiscoveryNotPermittedException,
                                 UnexpectedException,
                                 ServletException

Deprecated.

Deprecated. Use VeriplaceState.requireUserImmediate().

Throws:

UserDiscoveryNotPermittedException

UnexpectedException

ServletException

requireGetLocationPermission

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

Deprecated.

Deprecated. Use VeriplaceState.requireGetLocationPermission().

Throws:

RespondedException

RequestDeniedException

UnexpectedException

ServletException

requireGetLocationPermissionImmediate

public void requireGetLocationPermissionImmediate(VeriplaceState state)
                                           throws GetLocationNotPermittedException,
                                                  UserDiscoveryException,
                                                  UnexpectedException

Deprecated.

Deprecated. Use VeriplaceState.requireGetLocationPermissionImmediate().

Throws:

GetLocationNotPermittedException

UserDiscoveryException

UnexpectedException

requireLocation

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

Deprecated.

Deprecated. Use VeriplaceState.requireLocation().

Throws:

RespondedException

WaitingException

RequestDeniedException

UnexpectedException

ServletException

requireLocation

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

Deprecated.

Deprecated. Use VeriplaceState.requireLocation(long).

Throws:

RespondedException

RequestDeniedException

UnexpectedException

ServletException

getCallbackUrl

public java.lang.String getCallbackUrl(VeriplaceState state)

Constructs a URL for returning to the current request from an external page, and passing along any necessary attributes to recreate the current state. You will normally not need to call this method yourself.

tryStatusView

protected void tryStatusView(VeriplaceState state,
                             java.lang.Exception e,
                             java.lang.String callbackUrl)
                      throws RespondedWithStatusViewException,
                             UnexpectedException,
                             ServletException

Throws:

RespondedWithStatusViewException

UnexpectedException

ServletException