Spiffy UI Framework

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(RESTOptions options)
           Make an HTTP call and get the results as a JSON object.
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.
static void callREST(java.lang.String url, java.lang.String data, RESTility.HTTPMethod method, RESTCallback callback, boolean isLoginRequest, boolean shouldReplay, java.lang.String etag, java.util.Map<java.lang.String,java.lang.String> headers)
           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, 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 callREST(java.lang.String url, java.lang.String data, RESTility.HTTPMethod method, RESTCallback callback, java.lang.String etag, java.util.Map<java.lang.String,java.lang.String> headers)
           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
static void finishRESTCalls()
          In some cases, like login, the original REST call returns an error and we need to run it again.
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.
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 getSessionCookieName()
          Gets the current name of the Spiffy UI session cookie.
static java.lang.String getSessionCookiePath()
          Get the path of the session cookie.
static java.lang.String getTokenServerLogoutUrl()
          Returns authentication server logout url
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, RESTException exception)
          Make a login request using RESTility authentication framework.
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 boolean requiresSecureCookies()
          Determines if RESTility will force all cookies to require SSL.
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 setOAuthProvider(RESTOAuthProvider oAuthProvider)
          Set the OAuth provider for this application.
static void setRequireSecureCookies(boolean secure)
           Sets if RESTility cookies should only be sent via SSL.
static void setSessionCookieName(java.lang.String name)
           Sets the name of the Spiffy UI session cookie.
static void setSessionCookiePath(java.lang.String newPath)
           Set the path for the Spiffy_Session cookie.
static void setTokenServerLogoutURL(java.lang.String url)
          Set the authentication server logout url in JavaScript memory and and saves it in a cookie.
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.
static void setUsername(java.lang.String username)
          Set the user name in JavaScript memory and and saves it in a cookie.
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 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

setOAuthProvider

public static void setOAuthProvider(RESTOAuthProvider oAuthProvider)
Set the OAuth provider for this application.

Parameters:
oAuthProvider - the oAuth provider

setSessionCookieName

public static void setSessionCookieName(java.lang.String name)

Sets the name of the Spiffy UI session cookie.

Spiffy UI uses a local cookie to save the current user token. This cookie has the name Spiffy_Session by default. This method will change the name of the cookie to something else.

Calling this method will not change the name of the cookie until a REST call is made which causes the cookie to be reset.

Parameters:
name - the name of the cookie Spiffy UI session cookie

getSessionCookieName

public static java.lang.String getSessionCookieName()
Gets the current name of the Spiffy UI session cookie.

Returns:
the name of the session cookie

setRequireSecureCookies

public static void setRequireSecureCookies(boolean secure)

Sets if RESTility cookies should only be sent via SSL.

RESTility stores a small amount of information locally so users can refresh the page without logging out or resetting their locale. This information is sometimes stored in cookies. These cookies are normally not sent back to the server, but can be in some cases.

If your application is concerned with sercurity you might want to require all cookies are only sent via a secure connection (SSL). Set this method true to make all cookies stored be RESTility and Spiffy UI require an SSL connection before they are sent.

The default value of this field is false.

Parameters:
secure - true if cookies should require SSL and false otherwise

requiresSecureCookies

public static boolean requiresSecureCookies()
Determines if RESTility will force all cookies to require SSL.

Returns:
true if cookies require SSL and false otherwise

getAuthProvider

public static 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

login

public static void login(RESTCallback callback,
                         Response response,
                         java.lang.String url,
                         RESTException exception)
                  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
exception - the RESTException which prompted this login
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

public 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

public 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

public 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

public 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

public 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

public 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

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

Returns:
authentication server url

getTokenServerLogoutUrl

public 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

public 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

public 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,
                            java.lang.String etag,
                            java.util.Map<java.lang.String,java.lang.String> headers)

Make an HTTP call and get the results as a JSON object. This method handles allows the caller to override any HTTP headers in the request.

By default RESTility sets two HTTP headers: Accept=application/json and Accept-Charset=UTF-8. Other headers are added by the browser running this application.

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
headers - a map containing the headers to the HTTP request. Any item in this map will override the default headers.

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

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,
                            java.util.Map<java.lang.String,java.lang.String> headers)

Make an HTTP call and get the results as a JSON object. This method handles cases like login, error parsing, and configuration requests.

By default RESTility sets two HTTP headers: Accept=application/json and Accept-Charset=UTF-8. Other headers are added by the browser running this application.

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
headers - a map containing the headers to the HTTP request. Any item in this map will override the default headers.

callREST

public static void callREST(RESTOptions options)

Make an HTTP call and get the results as a JSON object. This method handles cases like login, error parsing, and configuration requests.

Parameters:
options - the options for the REST 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

Spiffy UI Framework