com.veriplace.client
Class PermissionAPI

java.lang.Object
  com.veriplace.client.PermissionAPI

public class PermissionAPI
extends java.lang.Object

Interface for verifying or removing an application's permissions for specific resources in the Veriplace platform. These are direct requests to the Veriplace server, and can be used without user interaction and without a web front-end. To access an instance of this class, use Client.getPermissionAPI().

The verify(Token) and delete(Token) methods operate on specific OAuth Access Tokens, representing permissions to locate specific users. An application may wish to verify an Access Token if it was previously cached, because users may have changed their privacy settings so that the token is no longer valid and location requests will fail; in this case the application may choose to restart the OAuth User Authorization process to obtain a new token. An application can also delete the Access Token that it previously used to locate a user; this has the same effect as the user revoking permission for that application through the Veriplace website.

The verifyCarrierLocatability(String) method does not check whether the application has permission to locate the user, but whether it can ever have permission, based on whether the given mobile number is on a mobile carrier that is supported by Veriplace and authorized for the application.

Since:

2.0

See Also:

Veriplace Developer Guide: Using the Verify Permission API, Veriplace Developer Guide: Using the Delete Permission API, Veriplace Developer Guide: Using the Verify Locatability API

Method Summary

void	delete(Token accessToken) Remove an access token, so the application will no longer have permission to locate that user.
boolean	verify(Token accessToken) Verify an access token.
boolean	verifyCarrierLocatability(java.lang.String mobileNumber) Verify that a mobile number is theoretically accessible by this application, based only on its mobile carrier and the application's launch status.

Methods inherited from class java.lang.Object

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

Method Detail

verify

public boolean verify(Token accessToken)
               throws UnexpectedException

Verify an access token.

Parameters:

accessToken - the access token permitting the user to be located

Returns:

whether the access token is valid for the GetLocationAPI

Throws:

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

delete

public void delete(Token accessToken)
            throws UnknownTokenException,
                   UnexpectedException

Remove an access token, so the application will no longer have permission to locate that user.

Parameters:

accessToken - the access token permitting the user to be located

Throws:

UnknownTokenException - if the token was not valid

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

verifyCarrierLocatability

public boolean verifyCarrierLocatability(java.lang.String mobileNumber)
                                  throws BadParameterException,
                                         UnexpectedException

Verify that a mobile number is theoretically accessible by this application, based only on its mobile carrier and the application's launch status. If this method returns false, then a user with that mobile number would not be able to grant location permission to your application.

Even if the number does not have a registered Veriplace account, Veriplace can determine whether it is a valid number belonging to a supported carrier. If your application has been launched, it may only be certified for certain carriers and not for others.

If your application is still in development and has not been certified for any carrier, then the only mobile numbers that are allowed are the ones you have designated as test phones on the Veriplace Developer Portal (subject to the user's approval: users of those phones can still choose to opt out of "developer mode", in which case they will be unavailable to your application).

If this method returns true, it does not mean that your application can locate the user; you still need to have the user's permission. To check for an existing permission token, use GetLocationAPI.getLocationAccessToken(User). To ask for permission interactively in a web application using an OAuth redirect, use GetLocationAPI.getRedirectURL(String, User). To ask for permission via an SMS messge, use InvitationAPI.

Parameters:

mobileNumber - the mobile number

Returns:

true if the mobile number is valid and is on a carrier that is supported for this application; false if not

Throws:

BadParameterException - if the mobile number was not in a valid format (see UserDiscoveryParameters for acceptable formats)

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