self.philbrown.droidQuery
Class AjaxOptions

java.lang.Object
  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)