com.veriplace.client
Class UserDiscoveryAPI

java.lang.Object
  com.veriplace.client.UserDiscoveryAPI

public class UserDiscoveryAPI
extends java.lang.Object

Interface for obtaining user identity information from Veriplace. To access an instance of this class, use Client.getUserDiscoveryAPI().

User identity can be obtained in one of two ways:

• Using some known personally identifiable information, such as an email address
• Using User Agent redirection to get the current user to identify themself

Both requests use OAuth; in the former case, the application-specific Access Token is used to sign the protected resource request whereas in the latter case, a successful redirect results in Veriplace issuing a one-time Access Token.

A typical flow involving User Agent redirection will look something like:

 // construct a callback URL
 String callback = client.prepareCallback(request) + "/callback";
 // construct the redirect URL for user authorization
 String redirectUrl = client.getUserDiscoveryAPI().getRedirectURL(callback,null);
 // 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) {
     // get user
     User user = client.getUserDiscoveryAPI().getUser(accessToken);
   }
 }
 

See Also:

Veriplace Developer Guide: Using the User Discovery API

Field Summary

static java.lang.String	EMAIL
static java.lang.String	MOBILE
static java.lang.String	OPENID

Method Summary

java.lang.String	getRedirectURL(java.lang.String callback) Get the URL to use for OAuth redirection to obtain the current user ID.
java.lang.String	getRedirectURL(java.lang.String callback, boolean immediate) Get the URL to use for OAuth redirection to obtain the current user ID.
java.lang.String	getRedirectURL(java.lang.String callback, User user) Deprecated. Use #getRedirectURL(String).
java.lang.String	getRedirectURL(java.lang.String callback, User user, boolean immediate) Deprecated. Use #getRedirectURL(String, boolean).
User	getUser(Token accessToken) Find an enrolled user by supplying a one-time Access Token.
User	getUserByEmail(java.lang.String email) Find an enrolled user by supplying a known email address.
User	getUserByMobileNumber(java.lang.String mobileNumber) Find an enrolled user by supplying a known mobile number.
User	getUserByOpenId(java.lang.String openId) Find an enrolled user by supplying a known OpenId.
User	getUserByParameters(UserDiscoveryParameters parameters) Find an enrolled user by supplying one of the supported identifying parameters in UserDiscoveryParameters.
java.util.Map<UserDiscoveryParameters,User>	getUsersByParameters(java.util.List<UserDiscoveryParameters> list) Find multiple users by supplying the supported identifying parameters in UserDiscoveryParameters.

Methods inherited from class java.lang.Object

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

Field Detail

EMAIL

public static final java.lang.String EMAIL

See Also:

Constant Field Values

MOBILE

public static final java.lang.String MOBILE

See Also:

Constant Field Values

OPENID

public static final java.lang.String OPENID

See Also:

Constant Field Values

Method Detail

getRedirectURL

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

Get the URL to use for OAuth redirection to obtain the current user ID. By default, the user will be allowed to log in interactively if necessary.

Parameters:

callback - the OAuth callback url

Returns:

the OAuth redirection url

Throws:

TransportException

VeriplaceOAuthException

getRedirectURL

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

Get the URL to use for OAuth redirection to obtain the current user ID.

Parameters:

callback - the OAuth callback url

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

Returns:

the OAuth redirection url

Throws:

TransportException

VeriplaceOAuthException

getUserByParameters

public User getUserByParameters(UserDiscoveryParameters parameters)
                         throws UserDiscoveryException,
                                UnexpectedException

Find an enrolled user by supplying one of the supported identifying parameters in UserDiscoveryParameters.

This request uses the application-specific Access Token.

Parameters:

parameters - a UserDiscoveryParameters object

Returns:

the user or null if none

Throws:

UserDiscoveryException - if the server refused the user discovery request

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

getUserByEmail

public User getUserByEmail(java.lang.String email)
                    throws UserDiscoveryException,
                           UnexpectedException

Find an enrolled user by supplying a known email address.

This request uses the application-specific Access Token.

Parameters:

email - the user's email address

Returns:

the user or null if none

Throws:

UserDiscoveryException - if the server refused the user discovery request

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

getUserByMobileNumber

public User getUserByMobileNumber(java.lang.String mobileNumber)
                           throws UserDiscoveryException,
                                  UnexpectedException

Find an enrolled user by supplying a known mobile number. See UserDiscoveryParameters for acceptable mobile number formats.

This request uses the application-specific Access Token.

Parameters:

mobileNumber - the user's mobile number

Returns:

the user or null if none

Throws:

UserDiscoveryException - if the server refused the user discovery request

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

getUserByOpenId

public User getUserByOpenId(java.lang.String openId)
                     throws UserDiscoveryException,
                            UnexpectedException

Find an enrolled user by supplying a known OpenId.

This request uses the application-specific Access Token.

Parameters:

openId - the user's OpenID

Returns:

the user or null if none

Throws:

UserDiscoveryException - if the server refused the user discovery request

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

getUser

public User getUser(Token accessToken)
             throws UserDiscoveryException,
                    UnexpectedException

Find an enrolled user by supplying a one-time Access Token.

Parameters:

accessToken - the access token permitting the user to be discovered

Returns:

the user or null if none

Throws:

UserDiscoveryException - if the server refused the user discovery request

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

getUsersByParameters

public java.util.Map<UserDiscoveryParameters,User> getUsersByParameters(java.util.List<UserDiscoveryParameters> list)
                                                                 throws UserDiscoveryException,
                                                                        UnexpectedException

Find multiple users by supplying the supported identifying parameters in UserDiscoveryParameters.

This request uses the application-specific Access Token.

Parameters:

list - a list of UserDiscoveryParameters object

Throws:

UserDiscoveryException - if the server refused the user discovery request

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

getRedirectURL

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

Deprecated. Use #getRedirectURL(String).

Throws:

TransportException

VeriplaceOAuthException

getRedirectURL

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

Deprecated. Use #getRedirectURL(String, boolean).

Throws:

TransportException

VeriplaceOAuthException