org.spiffyui.client.rest
Class RESTility

java.lang.Object
  extended by org.spiffyui.client.rest.RESTility

public final class RESTility
extends java.lang.Object

A set of utilities for calling REST from GWT.


Nested Class Summary
 class RESTility.HTTPMethod
          This is a helper type class so we can pass the HTTP method as a type safe object instead of a string.
 
Field Summary
static RESTility.HTTPMethod DELETE
          This method represents an HTTP DELETE request
static RESTility.HTTPMethod GET
          This method represents an HTTP GET request
static RESTility.HTTPMethod POST
          This method represents an HTTP POST request
static RESTility.HTTPMethod PUT
          This method represents an HTTP PUT request
 
Method Summary
static void addLoginListener(RESTLoginCallBack callback)
          Add login listeners
static void callREST(java.lang.String url, RESTCallback callback)
          Make a rest call using an HTTP GET to the specified URL.
static void callREST(java.lang.String url, java.lang.String data, RESTCallback callback)
          Make a rest call using an HTTP GET to the specified URL including the specified data..
static void callREST(java.lang.String url, java.lang.String data, RESTility.HTTPMethod method, RESTCallback callback)
          Make an HTTP call and get the results as a JSON object.
static void callREST(java.lang.String url, java.lang.String data, RESTility.HTTPMethod method, RESTCallback callback, boolean isLoginRequest, boolean shouldReplay, java.lang.String etag)
          Make an HTTP call and get the results as a JSON object.
protected static void callREST(java.lang.String url, java.lang.String data, RESTility.HTTPMethod method, RESTCallback callback, boolean isLoginRequest, java.lang.String etag)
          Make an HTTP call and get the results as a JSON object.
static void callREST(java.lang.String url, java.lang.String data, RESTility.HTTPMethod method, RESTCallback callback, java.lang.String etag)
          Make an HTTP call and get the results as a JSON object.
static void doLocalLogout()
          Upon logout, delete cookie and clear out all member variables
protected static void finishRESTCalls()
          In some cases, like login, the original REST call returns an error and we need to run it again.
protected static void fireLoginSuccess()
          Fire the login success event to all listeners if it hasn't been fired already.
static RESTAuthProvider getAuthProvider()
          Gets the current auth provider which will be used for future REST calls.
protected static java.lang.String getBestLocale()
          Returns best matched locale
static java.lang.String getFullAuthToken()
          Returns user's full authentication token, prefixed with "X-OPAQUE"
static java.util.List<RESTLoginCallBack> getLoginListeners()
           
static java.lang.String getSessionCookiePath()
          Get the path of the session cookie.
protected static java.lang.String getTokenServerLogoutUrl()
          Returns authentication server logout url
protected static java.lang.String getTokenServerUrl()
          Returns the authentication server url
static java.lang.String getTokenType()
          Returns user's authentication token type
static java.lang.String getUsername()
          Returns the name of the currently logged in user or null if the current user is not logged in.
static java.lang.String getUserToken()
          Returns user's authentication token
static boolean hasUserLoggedIn()
          Returns a boolean flag indicating whether user has logged in or not
static void login(RESTCallback callback, Response response, java.lang.String url, java.lang.String errorCode)
          Make a login request using RESTility authentication framework.
static RESTility.HTTPMethod parseString(java.lang.String method)
          Returns HTTPMethod corresponding to method name.
static void removeLoginListener(RESTLoginCallBack callback)
          Remove login listeners
static void setAuthProvider(RESTAuthProvider authProvider)
           Sets the authentication provider used for future REST requests.
static void setBestLocale(java.lang.String locale)
          We can't know the best locale until after the user logs in because we need to consider their locale from the identity vault.
static void setSessionCookiePath(java.lang.String newPath)
           Set the path for the Spiffy_Session cookie.
protected static void setTokenServerLogoutURL(java.lang.String url)
          Set the authentication server logout url in JavaScript memory and and saves it in a cookie.
protected static void setTokenServerURL(java.lang.String url)
          Set the authentication server url in JavaScript memory and and saves it in a cookie.
static void setTokenType(java.lang.String type)
           Set the type of token RESTility will pass.
protected static void setUsername(java.lang.String username)
          Set the user name in JavaScript memory and and saves it in a cookie.
protected static void setUserToken(java.lang.String token)
          Set the user token in JavaScript memory and and saves it in a cookie.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

GET

public static final RESTility.HTTPMethod GET
This method represents an HTTP GET request


PUT

public static final RESTility.HTTPMethod PUT
This method represents an HTTP PUT request


POST

public static final RESTility.HTTPMethod POST
This method represents an HTTP POST request


DELETE

public static final RESTility.HTTPMethod DELETE
This method represents an HTTP DELETE request

Method Detail

setAuthProvider

public static final void setAuthProvider(RESTAuthProvider authProvider)

Sets the authentication provider used for future REST requests.

By default authentication is provided by the AuthUtil class, but this class may be replaced to provide support for custom authentication schemes.

Parameters:
authProvider - the new authentication provider
See Also:
AuthUtil

getAuthProvider

public static final RESTAuthProvider getAuthProvider()
Gets the current auth provider which will be used for future REST calls.

Returns:
The current auth provider

login

public static void login(RESTCallback callback,
                         Response response,
                         java.lang.String url,
                         java.lang.String errorCode)
                  throws RESTException
Make a login request using RESTility authentication framework.

Parameters:
callback - the rest callback called when the login is complete
response - the response from the server requiring the login
url - the URL of the authentication server
errorCode - the error code from the server returned with the 401
Throws:
RESTException - if there was an exception when making the login request

parseString

public static RESTility.HTTPMethod parseString(java.lang.String method)
Returns HTTPMethod corresponding to method name. If the passed in method does not match any, GET is returned.

Parameters:
method - a String representation of a http method
Returns:
the HTTPMethod corresponding to the passed in String method representation.

doLocalLogout

public static void doLocalLogout()
Upon logout, delete cookie and clear out all member variables


finishRESTCalls

protected static void finishRESTCalls()
In some cases, like login, the original REST call returns an error and we need to run it again. This call gets the same REST request information and tries the request again.


callREST

public static void callREST(java.lang.String url,
                            RESTCallback callback)
Make a rest call using an HTTP GET to the specified URL.

Parameters:
callback - the callback to invoke
url - the properly encoded REST url to call

callREST

public static void callREST(java.lang.String url,
                            java.lang.String data,
                            RESTCallback callback)
Make a rest call using an HTTP GET to the specified URL including the specified data..

Parameters:
url - the properly encoded REST url to call
data - the data to pass to the URL
callback - the callback to invoke

setUserToken

protected static void setUserToken(java.lang.String token)
Set the user token in JavaScript memory and and saves it in a cookie.

Parameters:
token - user token

setTokenServerURL

protected static void setTokenServerURL(java.lang.String url)
Set the authentication server url in JavaScript memory and and saves it in a cookie.

Parameters:
url - authentication server url

fireLoginSuccess

protected static void fireLoginSuccess()
Fire the login success event to all listeners if it hasn't been fired already.


setTokenType

public static void setTokenType(java.lang.String type)

Set the type of token RESTility will pass.

Most of the time the token type is specified by the REST server and the client does not have to specify this value. This method is mostly used for testing.

Parameters:
type - the token type

setUsername

protected static void setUsername(java.lang.String username)
Set the user name in JavaScript memory and and saves it in a cookie.

Parameters:
username - user name

setTokenServerLogoutURL

protected static void setTokenServerLogoutURL(java.lang.String url)
Set the authentication server logout url in JavaScript memory and and saves it in a cookie.

Parameters:
url - authentication server logout url

setBestLocale

public static void setBestLocale(java.lang.String locale)
We can't know the best locale until after the user logs in because we need to consider their locale from the identity vault. So we get the locale as part of the identity information and then store this in a cookie. If the cookie doesn't match the current locale then we need to refresh the page so we can reload the JavaScript libraries.

Parameters:
locale - the locale

setSessionCookiePath

public static void setSessionCookiePath(java.lang.String newPath)

Set the path for the Spiffy_Session cookie.

When Spiffy UI uses token based authentication it saves token and user information in a cookie named Spiffy_Session. This cookie allows the user to remain logged in after they refresh the page the reset JavaScript memory.

By default that cookie uses the path of the current page. If an application uses multiple pages it can make sense to use a more general path for this cookie to make it available to other URLs in the application.

The path must be set before the first authentication request. If it is called afterward the cookie path will not change.

Parameters:
newPath - the new path for the cookie or null if the cookie should use the path of the current page

getSessionCookiePath

public static java.lang.String getSessionCookiePath()
Get the path of the session cookie. By default this is null indicating a path of the current page will be used.

Returns:
the current session cookie path.

hasUserLoggedIn

public static boolean hasUserLoggedIn()
Returns a boolean flag indicating whether user has logged in or not

Returns:
boolean indicating whether user has logged in or not

getFullAuthToken

public static java.lang.String getFullAuthToken()
Returns user's full authentication token, prefixed with "X-OPAQUE"

Returns:
user's full authentication token prefixed with "X-OPAQUE"

getUserToken

public static java.lang.String getUserToken()
Returns user's authentication token

Returns:
user's authentication token

getTokenType

public static java.lang.String getTokenType()
Returns user's authentication token type

Returns:
user's authentication token type

getTokenServerUrl

protected static java.lang.String getTokenServerUrl()
Returns the authentication server url

Returns:
authentication server url

getTokenServerLogoutUrl

protected static java.lang.String getTokenServerLogoutUrl()
Returns authentication server logout url

Returns:
authentication server logout url

getUsername

public static java.lang.String getUsername()
Returns the name of the currently logged in user or null if the current user is not logged in.

Returns:
user name

getBestLocale

protected static java.lang.String getBestLocale()
Returns best matched locale

Returns:
best matched locale

getLoginListeners

public static java.util.List<RESTLoginCallBack> getLoginListeners()

callREST

public static void callREST(java.lang.String url,
                            java.lang.String data,
                            RESTility.HTTPMethod method,
                            RESTCallback callback)
Make an HTTP call and get the results as a JSON object. This method handles cases like login, error parsing, and configuration requests.

Parameters:
url - the properly encoded REST url to call
data - the data to pass to the URL
method - the HTTP method, defaults to GET
callback - the callback object for handling the request results

callREST

public static void callREST(java.lang.String url,
                            java.lang.String data,
                            RESTility.HTTPMethod method,
                            RESTCallback callback,
                            java.lang.String etag)
Make an HTTP call and get the results as a JSON object. This method handles cases like login, error parsing, and configuration requests.

Parameters:
url - the properly encoded REST url to call
data - the data to pass to the URL
method - the HTTP method, defaults to GET
callback - the callback object for handling the request results
etag - the option etag for this request

callREST

protected static void callREST(java.lang.String url,
                               java.lang.String data,
                               RESTility.HTTPMethod method,
                               RESTCallback callback,
                               boolean isLoginRequest,
                               java.lang.String etag)
Make an HTTP call and get the results as a JSON object. This method handles cases like login, error parsing, and configuration requests.

Parameters:
url - the properly encoded REST url to call
data - the data to pass to the URL
method - the HTTP method, defaults to GET
callback - the callback object for handling the request results
isLoginRequest - true if this is a request to login and false otherwise
etag - the option etag for this request

callREST

public static void callREST(java.lang.String url,
                            java.lang.String data,
                            RESTility.HTTPMethod method,
                            RESTCallback callback,
                            boolean isLoginRequest,
                            boolean shouldReplay,
                            java.lang.String etag)
Make an HTTP call and get the results as a JSON object. This method handles cases like login, error parsing, and configuration requests.

Parameters:
url - the properly encoded REST url to call
data - the data to pass to the URL
method - the HTTP method, defaults to GET
callback - the callback object for handling the request results
isLoginRequest - true if this is a request to login and false otherwise
shouldReplay - true if this request should repeat after a login request if this request returns a 401
etag - the option etag for this request

addLoginListener

public static void addLoginListener(RESTLoginCallBack callback)
Add login listeners

Parameters:
callback - listeners to be added

removeLoginListener

public static void removeLoginListener(RESTLoginCallBack callback)
Remove login listeners

Parameters:
callback - listeners to be removed