com.veriplace.client
Class Client

java.lang.Object
  com.veriplace.client.Client

public class Client
extends java.lang.Object

Veriplace client implementation in Java.

Users of the Veriplace client will minimally require an oauth_consumer_key and an oauth_consumer_secret representing their application. In addition, some (but not all) API functions will require an application-specific Access Token. As a convenience, these and other parameters can be specified more concisely by using the DefaultClientFactory.

Users of the Veriplace client will primarily operate through one of the standard APIs:

• UserDiscoveryAPI
• GetLocationAPI
• PermissionAPI
• InvitationAPI
• PollingAPI

Field Summary

static java.lang.String	ACCESS_TOKEN_PATH The URL path, after the baseUrl, for access token requests.
static java.lang.String	APPLICATION_INFO_PATH The URL path, after the baseUrl, for request token requests.
static java.lang.String	LONG_TIMEOUT
static java.lang.String	PRETTY_USER_DISCOVERY_USER_AUTHORIZATION_PATH The URL path, after the baseUrl, for user authorization requests, for user discovery.
static java.lang.String	REQUEST_TOKEN_PATH The URL path, after the baseUrl, for request token requests.
static java.lang.String	USER_AUTHORIZATION_PATH The URL path, after the baseUrl, for user authorization requests.

Constructor Summary

Client(ClientConfiguration config)

Client(java.lang.String consumerKey, java.lang.String consumerSecret)
Minimal client constructor, requiring only a consumer key and secret.

Client(java.lang.String consumerKey, java.lang.String consumerSecret, Revision revision)
Deprecated. Obsolete; use ClientConfiguration constructor instead.

Client(java.lang.String consumerKey, java.lang.String consumerSecret, Revision revision, Token applicationToken)
Deprecated. Obsolete; use ClientConfiguration constructor instead.

Client(java.lang.String consumerKey, java.lang.String consumerSecret, Revision revision, Token applicationToken, java.lang.String baseUrl, CallbackFactory callbackFactory, TokenStore requestTokenStore, java.lang.String defaultLocationMode)
Deprecated. Obsolete; use ClientConfiguration constructor instead.

Client(java.lang.String consumerKey, java.lang.String consumerSecret, Revision revision, Token applicationToken, java.lang.String baseUrl, java.lang.String callbackServerName, java.lang.Integer callbackServerPort, TokenStore requestTokenStore)
Deprecated. Obsolete; use ClientConfiguration constructor instead.

Client(java.lang.String consumerKey, java.lang.String consumerSecret, Revision revision, Token applicationToken, java.lang.String baseUrl, TokenStore requestTokenStore)
Deprecated. Obsolete; use ClientConfiguration constructor instead.

Method Summary

Token	getAccessToken(HttpServletRequest request) Get an access token for an OAuth callback request
java.lang.String	getApplicationInfoUrl() Constructs a URL, using the previously configured application consumer key, which will display the application's information page on the Veriplace web site.
Token	getApplicationToken()
java.lang.String	getBaseUrl() Deprecated. Obsolete; use getServerUri().
java.lang.String	getBaseUrlWithHttps() Deprecated. Obsolete; use getServerDirectUri().
CallbackFactory	getCallbackFactory()
Consumer	getConsumer()
GetLocationAPI	getGetLocationAPI() Get the GetLocation API client.
InvitationAPI	getInvitationAPI() Get the Invitation API client.
PermissionAPI	getPermissionAPI() Get the Permission API client.
PollingAPI	getPollingAPI() Get the Polling API client.
java.lang.String	getPreferredEncoding()
protected Response	getProtectedResource(com.veriplace.client.APIInfo info, ParameterSet parameters, Token accessToken) Utility method for retrieving the protected resource used by a particular API.
protected Response	getProtectedResource(com.veriplace.client.APIInfo info, ParameterSet parameters, Token accessToken, java.lang.Integer timeout) Utility method for retrieving the protected resource used by a particular API.
protected java.lang.String	getRedirectURL(java.lang.String callback, boolean immediate, java.lang.String uriPath) Utility method for constructing a Veriplace redirect URL for OAuth user authorization.
protected java.lang.String	getRedirectURL(Token requestToken, java.lang.String callback, boolean immediate, java.lang.String uriPath) Utility method for constructing a Veriplace redirect URL for OAuth user authorization, given an OAuth request token.
java.lang.String	getRequestToken(HttpServletRequest request) Returns the request token value from the OAuth callback request.
protected Token	getRequestToken(java.lang.String callback) Utility method for obtaining an OAuth request token.
protected TokenStore	getRequestTokenStore()
java.lang.String	getServerDirectUri() Returns the base URI for all direct communications with the Veriplace server (all requests except user authorization redirects).
java.lang.String	getServerUri() Returns the base URI for the Veriplace server.
boolean	getUseHttps() Deprecated. Obsolete; use isSecure().
UserDiscoveryAPI	getUserDiscoveryAPI() Get the UserDiscovery API client.
java.lang.String	getUserDiscoveryRequestToken(java.lang.String callback) Obtains a request token value which can be used to perform user discovery.
java.lang.String	getUserDiscoveryUrl(java.lang.String requestToken) Constructs a URL, using a request token previously obtained from getUserDiscoveryRequestToken(String), which will tell the Veriplace server to initiate user discovery and then call your application (using the callback previously specified in getUserDiscoveryRequestToken).
boolean	hasApplicationToken()
boolean	isCallback(HttpServletRequest request) Is this request an OAuth callback.
boolean	isSecure()

Methods inherited from class java.lang.Object

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

Field Detail

REQUEST_TOKEN_PATH

public static final java.lang.String REQUEST_TOKEN_PATH

The URL path, after the baseUrl, for request token requests.

See Also:

Constant Field Values

USER_AUTHORIZATION_PATH

public static final java.lang.String USER_AUTHORIZATION_PATH

The URL path, after the baseUrl, for user authorization requests.

See Also:

Constant Field Values

ACCESS_TOKEN_PATH

public static final java.lang.String ACCESS_TOKEN_PATH

The URL path, after the baseUrl, for access token requests.

See Also:

Constant Field Values

PRETTY_USER_DISCOVERY_USER_AUTHORIZATION_PATH

public static final java.lang.String PRETTY_USER_DISCOVERY_USER_AUTHORIZATION_PATH

The URL path, after the baseUrl, for user authorization requests, for user discovery.

This form uses a "pretty" URL that is more suitable for out-of-band communications.

See Also:

Constant Field Values

APPLICATION_INFO_PATH

public static final java.lang.String APPLICATION_INFO_PATH

The URL path, after the baseUrl, for request token requests.

See Also:

Constant Field Values

LONG_TIMEOUT

public static final java.lang.String LONG_TIMEOUT

See Also:

Constant Field Values

Constructor Detail

Client

public Client(java.lang.String consumerKey,
              java.lang.String consumerSecret)
       throws ConfigurationException

Minimal client constructor, requiring only a consumer key and secret. This shortcut is equivalent to constructing a ClientConfiguration with the same parameters.

This constructor uses the default baseUrl and requestTokenStore implementations, does not configure an application-specific access token, and uses OAuth Core 1.0 Rev A.

Parameters:

consumerKey - the OAuth consumer key, which is required

consumerSecret - the OAuth consumer secret, which is required

Throws:

ConfigurationException

Client

@Deprecated
public Client(java.lang.String consumerKey,
                         java.lang.String consumerSecret,
                         Revision revision)
       throws ConfigurationException

Deprecated. Obsolete; use ClientConfiguration constructor instead.

Throws:

ConfigurationException

Client

@Deprecated
public Client(java.lang.String consumerKey,
                         java.lang.String consumerSecret,
                         Revision revision,
                         Token applicationToken)
       throws ConfigurationException

Deprecated. Obsolete; use ClientConfiguration constructor instead.

Throws:

ConfigurationException

Client

@Deprecated
public Client(java.lang.String consumerKey,
                         java.lang.String consumerSecret,
                         Revision revision,
                         Token applicationToken,
                         java.lang.String baseUrl,
                         TokenStore requestTokenStore)
       throws ConfigurationException

Deprecated. Obsolete; use ClientConfiguration constructor instead.

Throws:

ConfigurationException

Client

@Deprecated
public Client(java.lang.String consumerKey,
                         java.lang.String consumerSecret,
                         Revision revision,
                         Token applicationToken,
                         java.lang.String baseUrl,
                         java.lang.String callbackServerName,
                         java.lang.Integer callbackServerPort,
                         TokenStore requestTokenStore)
       throws ConfigurationException

Deprecated. Obsolete; use ClientConfiguration constructor instead.

Throws:

ConfigurationException

Client

@Deprecated
public Client(java.lang.String consumerKey,
                         java.lang.String consumerSecret,
                         Revision revision,
                         Token applicationToken,
                         java.lang.String baseUrl,
                         CallbackFactory callbackFactory,
                         TokenStore requestTokenStore,
                         java.lang.String defaultLocationMode)
       throws ConfigurationException

Deprecated. Obsolete; use ClientConfiguration constructor instead.

Throws:

ConfigurationException

Client

public Client(ClientConfiguration config)
       throws ConfigurationException

Throws:

ConfigurationException

Method Detail

getUserDiscoveryAPI

public UserDiscoveryAPI getUserDiscoveryAPI()

Get the UserDiscovery API client.

getGetLocationAPI

public GetLocationAPI getGetLocationAPI()

Get the GetLocation API client.

getPermissionAPI

public PermissionAPI getPermissionAPI()

Get the Permission API client.

Since:

2.0

getInvitationAPI

public InvitationAPI getInvitationAPI()

Get the Invitation API client.

Since:

2.3

getPollingAPI

public PollingAPI getPollingAPI()

Get the Polling API client.

Since:

2.4

getCallbackFactory

public CallbackFactory getCallbackFactory()

isCallback

public boolean isCallback(HttpServletRequest request)

Is this request an OAuth callback.

Parameters:

request - the callback request

getRequestToken

public java.lang.String getRequestToken(HttpServletRequest request)
                                 throws InvalidCallbackException

Returns the request token value from the OAuth callback request. This is mainly useful if you are receiving a callback from a user discovery process that was previously started with getUserDiscoveryUrl(String), and need to match the current callback to the previously stored token for a particular user.

Parameters:

request -

Returns:

a request token (not including the token secret) or null if none.

Throws:

InvalidCallbackException

getAccessToken

public Token getAccessToken(HttpServletRequest request)
                     throws InvalidCallbackException,
                            TransportException,
                            VeriplaceOAuthException

Get an access token for an OAuth callback request

Parameters:

request - the callback request

Returns:

a valid access token or null if none

Throws:

InvalidCallbackException

TransportException

VeriplaceOAuthException

getRedirectURL

protected java.lang.String getRedirectURL(java.lang.String callback,
                                          boolean immediate,
                                          java.lang.String uriPath)
                                   throws TransportException,
                                          VeriplaceOAuthException

Utility method for constructing a Veriplace redirect URL for OAuth user authorization.

This version obtains an OAuth request token before constructing the redirect URL.

Parameters:

callback - the OAuth callback

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

uriPath - the resource for which authorization is requested (e.g. location)

Throws:

TransportException

VeriplaceOAuthException

getRequestToken

protected Token getRequestToken(java.lang.String callback)
                         throws TransportException,
                                VeriplaceOAuthException

Utility method for obtaining an OAuth request token.

Parameters:

callback - the OAuth callback, which is required for Rev A.

Throws:

TransportException

VeriplaceOAuthException

getRedirectURL

protected java.lang.String getRedirectURL(Token requestToken,
                                          java.lang.String callback,
                                          boolean immediate,
                                          java.lang.String uriPath)
                                   throws TransportException,
                                          VeriplaceOAuthException

Utility method for constructing a Veriplace redirect URL for OAuth user authorization, given an OAuth request token.

Parameters:

requestToken - the OAuth request token

callback - the OAuth callback

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

uriPath - the resource for which authorization is requested (e.g. location)

Throws:

TransportException

VeriplaceOAuthException

getProtectedResource

protected Response getProtectedResource(com.veriplace.client.APIInfo info,
                                        ParameterSet parameters,
                                        Token accessToken)
                                 throws TransportException,
                                        VeriplaceOAuthException

Utility method for retrieving the protected resource used by a particular API.

Returns:

the successful response; will not be null

Throws:

TransportException - if there is an I/O error in communication with the server

VeriplaceOAuthException - if the server denied the request

getProtectedResource

protected Response getProtectedResource(com.veriplace.client.APIInfo info,
                                        ParameterSet parameters,
                                        Token accessToken,
                                        java.lang.Integer timeout)
                                 throws TransportException,
                                        VeriplaceOAuthException

Utility method for retrieving the protected resource used by a particular API.

Returns:

the successful response; will not be null

Throws:

TransportException - if there is an I/O error in communication with the server

VeriplaceOAuthException - if the server denied the request

getServerUri

public java.lang.String getServerUri()

Returns the base URI for the Veriplace server.

Since:

2.1

See Also:

getServerDirectUri()

getBaseUrl

@Deprecated
public java.lang.String getBaseUrl()

Deprecated. Obsolete; use getServerUri().

getServerDirectUri

public java.lang.String getServerDirectUri()

Returns the base URI for all direct communications with the Veriplace server (all requests except user authorization redirects). If isSecure() is true then this will use HTTPS.

Since:

2.1

getBaseUrlWithHttps

@Deprecated
public java.lang.String getBaseUrlWithHttps()

Deprecated. Obsolete; use getServerDirectUri().

getPreferredEncoding

public java.lang.String getPreferredEncoding()

Since:

2.7

isSecure

public boolean isSecure()

Since:

2.1

getUseHttps

@Deprecated
public boolean getUseHttps()

Deprecated. Obsolete; use isSecure().

getConsumer

public Consumer getConsumer()

hasApplicationToken

public boolean hasApplicationToken()

getApplicationToken

public Token getApplicationToken()

getRequestTokenStore

protected TokenStore getRequestTokenStore()

getUserDiscoveryRequestToken

public java.lang.String getUserDiscoveryRequestToken(java.lang.String callback)
                                              throws TransportException,
                                                     VeriplaceOAuthException

Obtains a request token value which can be used to perform user discovery. Pass this value to getUserDiscoveryUrl(String), and also save the request token value so you can identify which user the callback is coming from (see getRequestToken(HttpServletRequest)).

Parameters:

callback - the callback URL to which Veriplace should redirect the user after user discovery has finished

Returns:

a request token string (not including the token secret)

Throws:

TransportException

VeriplaceOAuthException

getUserDiscoveryUrl

public java.lang.String getUserDiscoveryUrl(java.lang.String requestToken)

Constructs a URL, using a request token previously obtained from getUserDiscoveryRequestToken(String), which will tell the Veriplace server to initiate user discovery and then call your application (using the callback previously specified in getUserDiscoveryRequestToken). You can then ask an end user to visit this URL to sign up with Veriplace.

getApplicationInfoUrl

public java.lang.String getApplicationInfoUrl()

Constructs a URL, using the previously configured application consumer key, which will display the application's information page on the Veriplace web site.