self.philbrown.droidQuery
Class AjaxOptions

java.lang.Object
  extended by self.philbrown.droidQuery.AjaxOptions

public class AjaxOptions
extends Object

Build an Ajax Request

Author:
Phil Brown

Constructor Summary
AjaxOptions()
          Default Constructor
AjaxOptions(JSONObject json)
          Construct a new AjaxOptions Object with the given JSONObject of Ajax Options values.
AjaxOptions(Map<String,Object> settings)
          Constructs a new AjaxOptions Object with the given Key-Value Mapping of Ajax Options values.
AjaxOptions(String json)
          Construct with JSON string.
AjaxOptions(String url, Map<String,Object> settings)
          Constructs a new AjaxOptions Object with the given URL and the Key-Value Mapping of Ajax Options values.
 
Method Summary
 String accepts()
          Get the content type sent in the request header that tells the server what kind of response it will accept in return.
 AjaxOptions accepts(String accepts)
          Set the content type sent in the request header that tells the server what kind of response it will accept in return.
static void ajaxSetup(AjaxOptions options)
          Set options to be included in all ajax requests.
 boolean async()
          Get the asynchronous nature of the Task.
 AjaxOptions async(boolean async)
          Set the asynchronous nature of the Task.
 Function beforeSend()
          Gets the function that is registered to call before the Ajax Task begins
 AjaxOptions beforeSend(Function beforeSend)
          Sets the function that is registered to call before the Ajax Task begins
 boolean cache()
          Get whether or not the most recent responses will be cached.
 AjaxOptions cache(boolean cache)
          Set whether or not the most recent responses will be cached.
 long cacheTimeout()
          Get the amount of time required, in milliseconds, between the current response and a cached response, in order to update the response data and cache the new response.
 AjaxOptions cacheTimeout(long cacheTimeout)
          Set the amount of time required, in milliseconds, between the current response and a cached response, in order to update the response data and cache the new response.
 Function complete()
          Gets the function that is registered to call when the task has completed
 AjaxOptions complete(Function complete)
          Sets the function that is registered to when the task has completed.
 String contentType()
          Get the content type of the data sent to the server.
 AjaxOptions contentType(String contentType)
          Set the content type of the data sent to the server.
 Context context()
          Get the context
 AjaxOptions context(Context context)
          Set the context.
 Map<String,String> cookies()
          Get the Key-Value mapping of cookies to send in the Ajax request.
 void cookies(JSONObject cookies)
          Set the Key-Value mapping of cookies to send in the Ajax request.
 void cookies(Map<String,String> cookies)
          Set the Key-Value mapping of cookies to send in the Ajax request.
 CustomHttpUriRequest customRequest()
          Get a new instance of the subclass of CustomHttpUriRequest that is used when the type option is set to "CUSTOM".
 AjaxOptions customRequest(String customRequestClass)
          Set the class name of the subclass of CustomHttpUriRequest that is used when the type option is set to "CUSTOM".
 SAXParser customXMLParser()
          Get the custom parser for handling XML with a SAX parser instead of converting it to a Document.
 AjaxOptions customXMLParser(SAXParser customXMLParser)
          Set the custom parser for handling XML with a SAX parser, instead of converting it to a Document Object.
 Object data()
          Get the data to be sent to the server
 AjaxOptions data(Object data)
          Set the data to be sent to the server.
 Function dataFilter()
          Get the function to be used to handle the raw response data.
 AjaxOptions dataFilter(Function dataFilter)
          Set the function to be used to handle the raw response data.
 String dataType()
          Gets the type of the data that the request expects from the server
 AjaxOptions dataType(String dataType)
          Sets the type of the data that the request expects from the server.
 boolean debug()
          Get whether or not Ajax debug output will be pushed to the logcat
 AjaxOptions debug(boolean debug)
          Sets whether or not Ajax debug output will be pushed to the logcat
 Function error()
          Get the function to be called if the request fails.
 AjaxOptions error(Function error)
          Set the function to be called if the request fails.
 byte[] getEncodedCredentials()
          As a security feature, this class will not allow queries of authentication passwords.
 boolean global()
          Get whether to trigger global Ajax event handlers for this request.
 AjaxOptions global(boolean global)
          Set whether to trigger global Ajax event handlers for this request.
 Headers headers()
          Get the HTTP Headers for the request
 AjaxOptions headers(Headers headers)
          Set the HTTP Headers for the request
 boolean ifModified()
          Get whether or not the response is only considered successful if it has been changed since the last request.
 AjaxOptions ifModified(boolean ifModified)
          Set whether or not the response is only considered successful if it has been changed since the last request.
 int imageHeight()
          Get the output bitmap height for requests that set the type attribute to "IMAGE".
 AjaxOptions imageHeight(int height)
          Set the output bitmap height for requests that set the type attribute to "IMAGE".
 int imageWidth()
          Get the output bitmap width for requests that set the type attribute to "IMAGE".
 AjaxOptions imageWidth(int width)
          Set the output bitmap width for requests that set the type attribute to "IMAGE".
 AjaxOptions password(String password)
          Set the password to use if prompted with an HTTP access authentication request.
 String processData()
          Get the name of a class that extends DataProcessor that is meant to handle raw data to send in the HTTP request, in order to prevent it from being converted to a String.
 AjaxOptions processData(String processDataClass)
          Set the name of a class that extends DataProcessor in order to handle raw data to send in the HTTP request, in order to prevent it from being converted to a String.
 DefaultHandler SAXContentHandler()
          Get the SAX parser Content Handler
 AjaxOptions SAXContentHandler(DefaultHandler SAXContentHandler)
          Set the Content Handler that should be used to handle SAX parsing.
 Map<Integer,Function> statusCode()
          Get a mapping of numeric HTTP codes to functions to be called when the response has the corresponding code.
 AjaxOptions statusCode(Integer code, Function function)
          Adds a Key-Value entry to the status code mapping of numeric HTTP codes to functions to be called when the response has the corresponding code.
 AjaxOptions statusCode(Map<Integer,Function> statusCode)
          Sets a mapping of numeric HTTP codes to functions to be called when the response has the corresponding code.
 Function success()
          Gets the function that will be called if the request succeeds.
 AjaxOptions success(Function success)
          Sets the function that will be called if the request succeeds.
 int timeout()
          Get the request (and socket) timeout (in milliseconds) for the request.
 AjaxOptions timeout(int timeout)
          Set the timeout (in milliseconds) for the request.
 String type()
          Get the type of request to make.
 AjaxOptions type(String type)
          Set the type of request to make.
 String url()
          Get the request URL
 AjaxOptions url(String url)
          Set the request URL
 String username()
          Get the username to use if prompted with an HTTP access authentication request.
 AjaxOptions username(String username)
          Set the username to use if prompted with an HTTP access authentication request
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AjaxOptions

public AjaxOptions()
Default Constructor


AjaxOptions

public AjaxOptions(String json)
            throws JSONException
Construct with JSON string. To support versions 0.1.0-0.1.3, this method can also accept a URL.

Parameters:
json - JSON options
Throws:
JSONException

AjaxOptions

public AjaxOptions(String url,
                   Map<String,Object> settings)
Constructs a new AjaxOptions Object with the given URL and the Key-Value Mapping of Ajax Options values.

Parameters:
url - the request URL
settings - mapping of Ajax Options values. Can include all types - Strings, Functions, etc.

AjaxOptions

public AjaxOptions(Map<String,Object> settings)
Constructs a new AjaxOptions Object with the given Key-Value Mapping of Ajax Options values.

Parameters:
settings - mapping of Ajax Options values. Can include all types - Strings, Functions, etc.

AjaxOptions

public AjaxOptions(JSONObject json)
            throws JSONException
Construct a new AjaxOptions Object with the given JSONObject of Ajax Options values.

Parameters:
json - the JSONObject
Throws:
JSONException - if the json is malformed
Method Detail

accepts

public String accepts()
Get the content type sent in the request header that tells the server what kind of response it will accept in return.


accepts

public AjaxOptions accepts(String accepts)
Set the content type sent in the request header that tells the server what kind of response it will accept in return.


async

public boolean async()
Get the asynchronous nature of the Task.

Returns:
true if the task should be asynchronous (default). false Otherwise.

async

public AjaxOptions async(boolean async)
Set the asynchronous nature of the Task.

Parameters:
async - true if the task should be asynchronous (default). false Otherwise.
Returns:
this

beforeSend

public Function beforeSend()
Gets the function that is registered to call before the Ajax Task begins

Returns:
the Function

beforeSend

public AjaxOptions beforeSend(Function beforeSend)
Sets the function that is registered to call before the Ajax Task begins

Parameters:
beforeSend - the Function to call. This will receive a null Object for the droidQuery parameter unless context is non-null. If that is the case, beforeSend will receive a droidQuery instance with that context. The varargs parameter will include these options, so that they can be manipulated.
Returns:
this

complete

public Function complete()
Gets the function that is registered to call when the task has completed

Returns:
the Function

complete

public AjaxOptions complete(Function complete)
Sets the function that is registered to when the task has completed. The function will receive no varargs, It will also receive a null Object for the droidQuery parameter unless context is non-null. If that is the case, complete will receive a droidQuery instance with that context.

Parameters:
complete - the Function to call
Returns:
this

contentType

public String contentType()
Get the content type of the data sent to the server. Default is "application/x-www-form-urlencoded; charset=UTF-8", which is fine for most cases.

Returns:
the content type

contentType

public AjaxOptions contentType(String contentType)
Set the content type of the data sent to the server. Default is "application/x-www-form-urlencoded; charset=UTF-8", which is fine for most cases.

Parameters:
contentType -
Returns:
this

context

public Context context()
Get the context

Returns:
the context

context

public AjaxOptions context(Context context)
Set the context. Setting this to a non-null value will allow the callback Functions (such as success, error, beforeSend, and complete) to pass a non-null droidQuery instance.

Parameters:
context -
Returns:
this

data

public Object data()
Get the data to be sent to the server

Returns:
the data to be sent to the server

data

public AjaxOptions data(Object data)
Set the data to be sent to the server. Will be converted to String unless processData is set to false.

Parameters:
data -
Returns:
this

debug

public boolean debug()
Get whether or not Ajax debug output will be pushed to the logcat

Returns:
true if the debug information will be printed. Otherwise false

debug

public AjaxOptions debug(boolean debug)
Sets whether or not Ajax debug output will be pushed to the logcat

Parameters:
debug - true if the debug information will be printed. Otherwise false. Default is false.
Returns:
this

dataFilter

public Function dataFilter()
Get the function to be used to handle the raw response data.

Returns:
the function to be used to handle the raw response data.

dataFilter

public AjaxOptions dataFilter(Function dataFilter)
Set the function to be used to handle the raw response data. This is a pre-filtering function to sanitize the response. You should return the sanitized data. The function accepts two varargs: The raw data returned from the server (HttpResponse) and the 'dataType' parameter (String). It will also receive a null Object for the droidQuery parameter unless context is non-null. If that is the case, dataFilter will receive a droidQuery instance with that context.

Parameters:
dataFilter -
Returns:
this

dataType

public String dataType()
Gets the type of the data that the request expects from the server

Returns:
the type of the data that the request expects from the server

dataType

public AjaxOptions dataType(String dataType)
Sets the type of the data that the request expects from the server. Can be one of: "xml": Returns a XML document that can be processed via droidQuery. Note that if customXMLParser() or SAXContentHandler() have been set, no Document will be returned. Instead, it will pass a descriptive String. "html": Returns HTML as plain text. "script": Evaluates the response as bourne (NOT bash) script and returns it as plain text. "json": Evaluates the response as JSON and returns a JSONObject object. The JSON data is parsed in a strict manner; any malformed JSON is rejected and a parse error is thrown. (See json.org for more information on proper JSON formatting.) "text": A plain text string. "image" : returns a bitmap object

Parameters:
dataType -
Returns:
this

SAXContentHandler

public AjaxOptions SAXContentHandler(DefaultHandler SAXContentHandler)
Set the Content Handler that should be used to handle SAX parsing. This will cause success() to NOT pass a XML Document variable as a parameter. Instead, it will pass a descriptive String.

Parameters:
SAXContentHandler -
Returns:
this

SAXContentHandler

public DefaultHandler SAXContentHandler()
Get the SAX parser Content Handler

Returns:
the handler

customXMLParser

public AjaxOptions customXMLParser(SAXParser customXMLParser)
Set the custom parser for handling XML with a SAX parser, instead of converting it to a Document Object. This will cause success() to NOT pass a XML Document variable as a parameter.Instead, it will pass a descriptive String.

Parameters:
customXMLParser -
Returns:
this

customXMLParser

public SAXParser customXMLParser()
Get the custom parser for handling XML with a SAX parser instead of converting it to a Document.

Returns:
the parser

error

public Function error()
Get the function to be called if the request fails. Receives original Request, the integer Status, and the String Error


error

public AjaxOptions error(Function error)
Set the function to be called if the request fails. Receives an AjaxTask.AjaxError error, the integer Status, and the String Error for varargs. It will also receive a null Object for the droidQuery parameter unless context is non-null. If that is the case, error will receive a droidQuery instance with that context.


global

public boolean global()
Get whether to trigger global Ajax event handlers for this request.

Returns:

global

public AjaxOptions global(boolean global)
Set whether to trigger global Ajax event handlers for this request. The default is true. Set to false to prevent the global handlers like ajaxStart or ajaxStop from being triggered. This can be used to control various Ajax Events.


headers

public Headers headers()
Get the HTTP Headers for the request

Returns:
the HTTP Headers for the request

headers

public AjaxOptions headers(Headers headers)
Set the HTTP Headers for the request

Parameters:
headers - the HTTP Headers for the request

cache

public boolean cache()
Get whether or not the most recent responses will be cached.

Returns:
true if the most recent responses will be cached. Otherwise, false.

cache

public AjaxOptions cache(boolean cache)
Set whether or not the most recent responses will be cached.

Parameters:
cache - If set to true, the most recent responses will be cached. The length of time that a cached response is considered valid can be set using the cacheTimeout option. Default is false.
Returns:
this

cacheTimeout

public long cacheTimeout()
Get the amount of time required, in milliseconds, between the current response and a cached response, in order to update the response data and cache the new response. This is only used when the cache option is set to true.

Returns:
the time, in milliseconds

cacheTimeout

public AjaxOptions cacheTimeout(long cacheTimeout)
Set the amount of time required, in milliseconds, between the current response and a cached response, in order to update the response data and cache the new response. This is only used when the cache option is set to true.

Parameters:
cacheTimeout - the time, in milliseconds
Returns:
this

cookies

public Map<String,String> cookies()
Get the Key-Value mapping of cookies to send in the Ajax request.

Returns:
the Key-Value mapping of cookies to send

cookies

public void cookies(Map<String,String> cookies)
Set the Key-Value mapping of cookies to send in the Ajax request.

Parameters:
cookies -

cookies

public void cookies(JSONObject cookies)
             throws JSONException
Set the Key-Value mapping of cookies to send in the Ajax request.

Parameters:
cookies -
Throws:
JSONException - if the JSON is malformed

ifModified

public boolean ifModified()
Get whether or not the response is only considered successful if it has been changed since the last request. This is done by checking the Last-Modified header.

Returns:
true to enable the check. Otherwise false.

ifModified

public AjaxOptions ifModified(boolean ifModified)
Set whether or not the response is only considered successful if it has been changed since the last request. This is done by checking the Last-Modified header. Default value is false, ignoring the header.

Parameters:
{@code - true} to enable the check. Otherwise false.
Returns:
this

password

public AjaxOptions password(String password)
Set the password to use if prompted with an HTTP access authentication request. There is no password() method in order to protect the password.

Parameters:
password - the password to use for authentication
Returns:
this
See Also:
username(), getEncodedCredentials()

processData

public String processData()
Get the name of a class that extends DataProcessor that is meant to handle raw data to send in the HTTP request, in order to prevent it from being converted to a String. If null is returned, then no such class has been configured.

Returns:
the name of a class that extends DataProcessor

processData

public AjaxOptions processData(String processDataClass)
Set the name of a class that extends DataProcessor in order to handle raw data to send in the HTTP request, in order to prevent it from being converted to a String. This name should include the package name (for example: "com.example.android.MyDataProcessor").

Parameters:
processDataClass - the name of a class that extends DataProcessor
Returns:
this

statusCode

public Map<Integer,Function> statusCode()
Get a mapping of numeric HTTP codes to functions to be called when the response has the corresponding code.

Returns:
the mapping

statusCode

public AjaxOptions statusCode(Map<Integer,Function> statusCode)
Sets a mapping of numeric HTTP codes to functions to be called when the response has the corresponding code. The function will receive a null Object for the droidQuery parameter unless context is non-null. If that is the case, statusCode will receive a droidQuery instance with that context.

Parameters:
statusCode - the mapping
Returns:
this
See Also:
statusCode(Integer, Function)

statusCode

public AjaxOptions statusCode(Integer code,
                              Function function)
Adds a Key-Value entry to the status code mapping of numeric HTTP codes to functions to be called when the response has the corresponding code. For example, the following will alert when the response status is a 404:
 $.ajax(new AjaxOptions(this).statusCode(404, new Function(){
        public void invoke(Object... params)
        {
                $.with(this).alert("Page not found");
        }
 }));
 

Parameters:
code - the code key for the given function
function - the function to call when the response returns the given code
Returns:
this

success

public Function success()
Gets the function that will be called if the request succeeds. The function gets passed two arguments:
  1. The data returned from the server, formatted according to the dataType parameter
  2. a string describing the status

Returns:
the function

success

public AjaxOptions success(Function success)
Sets the function that will be called if the request succeeds. The function will get passed two arguments for varargs:
  1. The data returned from the server, formatted according to the dataType parameter
  2. a string describing the status
It will also receive a null Object for the droidQuery parameter unless context is non-null. If that is the case, success will receive a droidQuery instance with that context.

Parameters:
success - the function
Returns:
this

timeout

public int timeout()
Get the request (and socket) timeout (in milliseconds) for the request.

Returns:
the timeout, in milliseconds

timeout

public AjaxOptions timeout(int timeout)
Set the timeout (in milliseconds) for the request. This will affect the request timeout and the socket timeout.

Parameters:
timeout - the timeout, in milliseconds
Returns:
this

type

public String type()
Get the type of request to make. The response String will be one of "POST", "GET", "DELETE", "PUT", "HEAD", "OPTIONS", "TRACE" or "CUSTOM"

Returns:
the response type
See Also:
customRequestClass

type

public AjaxOptions type(String type)
Set the type of request to make. The response String will be one of "POST", "GET", "DELETE", "PUT", "HEAD", "OPTIONS", "TRACE" or "CUSTOM"

Parameters:
type - the response type
Returns:
this
See Also:
customRequestClass

imageWidth

public int imageWidth()
Get the output bitmap width for requests that set the type attribute to "IMAGE".

Returns:
the scaled width, or -1 if the image width should not be scaled

imageWidth

public AjaxOptions imageWidth(int width)
Set the output bitmap width for requests that set the type attribute to "IMAGE".

Parameters:
width - the scaled width, or -1 if the image width should not be scaled
Returns:
this

imageHeight

public int imageHeight()
Get the output bitmap height for requests that set the type attribute to "IMAGE".

Returns:
the scaled height, or -1 if the image height should not be scaled

imageHeight

public AjaxOptions imageHeight(int height)
Set the output bitmap height for requests that set the type attribute to "IMAGE".

Parameters:
height - the scaled height, or -1 if the image height should not be scaled
Returns:
this

url

public String url()
Get the request URL

Returns:
the request URL

url

public AjaxOptions url(String url)
Set the request URL

Parameters:
url - the request URL
Returns:
this

username

public String username()
Get the username to use if prompted with an HTTP access authentication request.

Returns:
the String username
See Also:
password(String), getEncodedCredentials()

username

public AjaxOptions username(String username)
Set the username to use if prompted with an HTTP access authentication request

Parameters:
username - the String username
Returns:
this

customRequest

public CustomHttpUriRequest customRequest()
                                   throws Exception
Get a new instance of the subclass of CustomHttpUriRequest that is used when the type option is set to "CUSTOM".

Returns:
the new instance
Throws:
Exception - if the class name is null or is not a valid class name

customRequest

public AjaxOptions customRequest(String customRequestClass)
Set the class name of the subclass of CustomHttpUriRequest that is used when the type option is set to "CUSTOM". Once instantiated, the Object is used to pass a custom HTTP Request type to the HTTP Client.

Parameters:
customRequestClass - the name of the class. Should include the full package name. For example: "com.example.android.MyCustomHttpUriRequest".
Returns:
this

ajaxSetup

public static void ajaxSetup(AjaxOptions options)
Set options to be included in all ajax requests. Requests can manually override these options by setting them on a per-request basis.

Parameters:
options - options to be included in all ajax requests

getEncodedCredentials

public byte[] getEncodedCredentials()
As a security feature, this class will not allow queries of authentication passwords. This method will instead encode the security credentials (username and password) using Base64-encryption, and return the encrypted data as a byte array.

Returns:
the encrypted credentials
See Also:
username(), password(String)