com.veriplace.client
Class CallbackOptions

java.lang.Object
  com.veriplace.client.CallbackOptions

public class CallbackOptions
extends java.lang.Object

Specifies optional parameters for an asynchronous request whose result will be delivered by HTTP callback.

If you pass a CallbackOptions instance with a non-null callback URI to an asynchronous Veriplace method, then when the result of the request is ready, Veriplace will send an HTTP POST message to that URI. There are two modes with different message formats:

• A summary callback contains only basic information about the result -- the unique identifier of the request, and whether it succeeded or failed -- as form-encoded content, i.e. a query string. You can use additional API methods such as GetLocationAPI.getLocationById(User, long, com.veriplace.oauth.consumer.Token, LocationOptions) to get the details. This was the only format supported prior to version 2.8. See createSummaryCallback(java.lang.String).
• An extended callback fully describes the result as an XML or JSON document, containing all the properties for LocationRequestStatus or InvitationStatus. If you use this mode, the callback URI must be secure (https:) since the result may contain protected information such as user location and mobile number; using an insecure callback URI with an extended callback will cause Veriplace to reject your request with a BadParameterException. See createExtendedCallback(String).

The APIs that support asynchronous requests also have methods for decoding the callback messages into result objects: GetLocationAPI.getCallbackResult(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse) and InvitationAPI.getCallbackResult(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse). If you are not using the SDK to decode callbacks -- i.e. if the callback URI points to a service on some other platform -- you may wish to use additional options for controlling the message format: see createExtendedCallback(String, String) and createFormEncodedExtendedCallback(String, String, String).

Since:

2.8

See Also:

GetLocationAPI.requestLocation(User, com.veriplace.oauth.consumer.Token, LocationOptions, CallbackOptions), InvitationAPI.inviteGetLocation(String, boolean, CallbackOptions)

Method Summary

static CallbackOptions	createExtendedCallback(java.lang.String uri) Constructs an instance with a callback URI, using the extended callback format.
static CallbackOptions	createExtendedCallback(java.lang.String uri, java.lang.String encoding) Constructs an instance with a callback URI, using the extended callback format and specifying the encoding.
static CallbackOptions	createFormEncodedExtendedCallback(java.lang.String uri, java.lang.String encoding, java.lang.String formParamName) Constructs an instance with a callback URI, using the extended callback format and specifying that the callback message should be wrapped in a form-encoded query string.
static CallbackOptions	createSummaryCallback(java.lang.String uri) Constructs an instance with only a callback URI.
java.lang.String	getCallbackUri() The URI to which the callback will be delivered.
java.lang.String	getEncoding() The desired encoding for the message, if it is an extended callback.
java.lang.String	getFormParamName() An optional parameter name for wrapping the entire callback content in a form-encoded parameter.
boolean	isExtendedCallback() Returns true if this is an extended callback.

Methods inherited from class java.lang.Object

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

Method Detail

getCallbackUri

public final java.lang.String getCallbackUri()

The URI to which the callback will be delivered.

getEncoding

public final java.lang.String getEncoding()

The desired encoding for the message, if it is an extended callback.

See Also:

createExtendedCallback(String, String), createFormEncodedExtendedCallback(String, String, String)

getFormParamName

public final java.lang.String getFormParamName()

An optional parameter name for wrapping the entire callback content in a form-encoded parameter.

See Also:

createFormEncodedExtendedCallback(String, String, String)

isExtendedCallback

public final boolean isExtendedCallback()

Returns true if this is an extended callback.

createSummaryCallback

public static CallbackOptions createSummaryCallback(java.lang.String uri)

Constructs an instance with only a callback URI. This leaves the encoding property empty, so the callback will use the summary format.

createExtendedCallback

public static CallbackOptions createExtendedCallback(java.lang.String uri)

Constructs an instance with a callback URI, using the extended callback format. The encoding defaults to XML.

Parameters:

uri - the callback URI (must be secure)

createExtendedCallback

public static CallbackOptions createExtendedCallback(java.lang.String uri,
                                                     java.lang.String encoding)

Constructs an instance with a callback URI, using the extended callback format and specifying the encoding.

You will normally not need to specify the encoding if you are using the Veriplace client to decode the callback message. However, if you are receiving callbacks via some other service that does not use the Veriplace SDK, you may find it more convenient to handle a JSON-encoded message rather than XML (the default).

Parameters:

uri - the callback URI (must be secure)

encoding - the preferred content type for the message; must be equal to ClientConfiguration.XML_CONTENT_TYPE or ClientConfiguration.JSON_CONTENT_TYPE

createFormEncodedExtendedCallback

public static CallbackOptions createFormEncodedExtendedCallback(java.lang.String uri,
                                                                java.lang.String encoding,
                                                                java.lang.String formParamName)

Constructs an instance with a callback URI, using the extended callback format and specifying that the callback message should be wrapped in a form-encoded query string.

This is equivalent to createExtendedCallback(String, String), except that the XML or JSON document will not be delivered directly in the message body, but will be converted to a query string in the form name=value, where name is the formParamName you specified and value is the result of URL-encoding the entire result document. The message will not contain form-encoded parameters for individual result properties; to get the individual properties, you will need to parse the XML or JSON document.

You may find this useful if you are receiving callbacks on some other platform, using a web gateway that only supports form-encoded messages.