android.webkit.gears
Class HttpRequestAndroid

java.lang.Object
  android.webkit.gears.HttpRequestAndroid

public final class HttpRequestAndroid
extends Object

Performs the underlying HTTP/HTTPS GET and POST requests.

These are performed synchronously (blocking). The caller should ensure that it is in a background thread if asynchronous behavior is required. All data is pushed, so there is no need for JNI native callbacks.

This uses the java.net.HttpURLConnection class to perform most of the underlying network activity. The Android brower's cache, android.webkit.CacheManager, is also used when caching is enabled, and updated with new data. The android.webkit.CookieManager is also queried and updated as necessary.

The public interface is designed to be called by native code through JNI, and to simplify coding none of the public methods will surface a checked exception. Unchecked exceptions may still be raised but only if the system is in an ill state, such as out of memory.

TODO: This isn't plumbed into LocalServer yet. Mutually dependent on LocalServer - will attach the two together once both are submitted.

Field Summary

static int	HEADERS_MAP_INDEX_KEY The first element of the String[] value in a headers map is the unmodified (case-sensitive) key.
static int	HEADERS_MAP_INDEX_VALUE The second element of the String[] value in a headers map is the associated value.
static String	KEY_CONTENT_LENGTH Case-sensitive header keys
static String	KEY_CONTENT_TYPE
static String	KEY_ETAG
static String	KEY_EXPIRES
static String	KEY_LAST_MODIFIED
static String	KEY_LOCATION

Constructor Summary

HttpRequestAndroid()

Method Summary

boolean	appendCacheResult(byte[] data, int bytes) Add data from the response body to the CacheResult created with createCacheResult().
boolean	connectToRemote() Perform an HTTP request on the network.
boolean	createCacheResult(String url, int responseCode, String mimeType, String encoding) Create a CacheResult for this URL.
static void	enableLogging(boolean on) Turn on/off logging in this class.
String	getAllResponseHeaders() Return all response headers, separated by CR-LF line endings, and ending with a trailing blank line.
static String	getCookieForUrl(String url) Get the cookie for the given URL.
String	getRequestHeader(String name) Returns the value associated with the given request header.
String	getResponseHeader(String name) Returns the value associated with the given response header.
String	getResponseLine() Get the complete response line of the HTTP request.
void	initChildThread() Initialize childThread using the TLS value of Thread.currentThread().
void	interrupt() Interrupt a blocking IO operation.
boolean	open(String method, String url) Analagous to the native-side HttpRequest::open() function.
boolean	parseHeaders() Receive all headers from the server and populate responseHeaders.
int	receive(byte[] buf) Receive the next sequential bytes of the response body after successful connection.
boolean	saveCacheResult() Save the completed CacheResult into the CacheManager.
boolean	sendPostData(byte[] data, int bytes) For POST method requests, send a stream of data provided by the native side in repeated callbacks.
static void	setCookieForUrl(String url, String cookie) Set the cookie for the given URL.
void	setRequestHeader(String name, String value) Set a header to send with the HTTP request.
boolean	useCacheResult(String url) Perform a request using the cache result if present.
boolean	useLocalServerResult(String url) Perform a request using LocalServer if possible.

Methods inherited from class java.lang.Object

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

Field Detail

KEY_CONTENT_LENGTH

public static final String KEY_CONTENT_LENGTH

Case-sensitive header keys

See Also:

Constant Field Values

KEY_EXPIRES

public static final String KEY_EXPIRES

See Also:

Constant Field Values

KEY_LAST_MODIFIED

public static final String KEY_LAST_MODIFIED

See Also:

Constant Field Values

KEY_ETAG

public static final String KEY_ETAG

See Also:

Constant Field Values

KEY_LOCATION

public static final String KEY_LOCATION

See Also:

Constant Field Values

KEY_CONTENT_TYPE

public static final String KEY_CONTENT_TYPE

See Also:

Constant Field Values

HEADERS_MAP_INDEX_KEY

public static final int HEADERS_MAP_INDEX_KEY

The first element of the String[] value in a headers map is the unmodified (case-sensitive) key.

See Also:

Constant Field Values

HEADERS_MAP_INDEX_VALUE

public static final int HEADERS_MAP_INDEX_VALUE

The second element of the String[] value in a headers map is the associated value.

See Also:

Constant Field Values

Constructor Detail

HttpRequestAndroid

public HttpRequestAndroid()

Method Detail

enableLogging

public static void enableLogging(boolean on)

Turn on/off logging in this class.

Parameters:

on - Logging enable state.

initChildThread

public void initChildThread()

Initialize childThread using the TLS value of Thread.currentThread(). Called on start up of the native child thread.

open

public boolean open(String method,
                    String url)

Analagous to the native-side HttpRequest::open() function. This initializes an underlying java.net.HttpURLConnection, but does not go to the wire. On success, this enables a call to send() to initiate the transaction.

Parameters:

method - The HTTP method, e.g GET or POST.

url - The URL to open.

Returns:

True on success with a complete HTTP response. False on failure.

interrupt

public void interrupt()

Interrupt a blocking IO operation. This will cause the child thread to expediently return from an operation if it was stuck at the time. Note that this inherently races, and unfortunately requires the caller to loop.

setRequestHeader

public void setRequestHeader(String name,
                             String value)

Set a header to send with the HTTP request. Will not take effect on a transaction already in progress. The key is associated case-insensitive, but stored case-sensitive.

Parameters:

name - The name of the header, e.g "Set-Cookie".

value - The value for this header, e.g "text/html".

getRequestHeader

public String getRequestHeader(String name)

Returns the value associated with the given request header.

Parameters:

name - The name of the request header, non-null, case-insensitive.

Returns:

The value associated with the request header, or null if not set, or error.

getResponseHeader

public String getResponseHeader(String name)

Returns the value associated with the given response header.

Parameters:

name - The name of the response header, non-null, case-insensitive.

Returns:

The value associated with the response header, or null if not set or error.

getAllResponseHeaders

public String getAllResponseHeaders()

Return all response headers, separated by CR-LF line endings, and ending with a trailing blank line. This mimics the format of the raw response header up to but not including the body.

Returns:

A string containing the entire response header.

getResponseLine

public String getResponseLine()

Get the complete response line of the HTTP request. Only valid on completion of the transaction.

Returns:

The complete HTTP response line, e.g "HTTP/1.0 200 OK".

getCookieForUrl

public static String getCookieForUrl(String url)

Get the cookie for the given URL.

Parameters:

url - The fully qualified URL.

Returns:

A string containing the cookie for the URL if it exists, or null if not.

setCookieForUrl

public static void setCookieForUrl(String url,
                                   String cookie)

Set the cookie for the given URL.

Parameters:

url - The fully qualified URL.

cookie - The new cookie value.

useLocalServerResult

public boolean useLocalServerResult(String url)

Perform a request using LocalServer if possible. Initializes class members so that receive() will obtain data from the stream provided by the response.

Parameters:

url - The fully qualified URL to try in LocalServer.

Returns:

True if the url was found and is now setup to receive. False if not found, with no side-effect.

useCacheResult

public boolean useCacheResult(String url)

Perform a request using the cache result if present. Initializes class members so that receive() will obtain data from the cache.

Parameters:

url - The fully qualified URL to try in the cache.

Returns:

True is the url was found and is now setup to receive from cache. False if not found, with no side-effect.

createCacheResult

public boolean createCacheResult(String url,
                                 int responseCode,
                                 String mimeType,
                                 String encoding)

Create a CacheResult for this URL. This enables the repsonse body to be sent in calls to appendCacheResult().

Parameters:

url - The fully qualified URL to add to the cache.

responseCode - The response code returned for the request, e.g 200.

mimeType - The MIME type of the body, e.g "text/plain".

encoding - The encoding, e.g "utf-8". Use "" for unknown.

appendCacheResult

public boolean appendCacheResult(byte[] data,
                                 int bytes)

Add data from the response body to the CacheResult created with createCacheResult().

Parameters:

data - A byte array of the next sequential bytes in the response body.

bytes - The number of bytes to write from the start of the array.

Returns:

True if all bytes successfully written, false on failure.

saveCacheResult

public boolean saveCacheResult()

Save the completed CacheResult into the CacheManager. This must have been created first with createCacheResult().

Returns:

Returns true if the entry has been successfully saved.

connectToRemote

public boolean connectToRemote()

Perform an HTTP request on the network. The underlying HttpURLConnection is connected to the remote server and the response headers are received.

Returns:

True if the connection succeeded and headers have been received. False on connection failure.

parseHeaders

public boolean parseHeaders()

Receive all headers from the server and populate responseHeaders. This converts from the slightly odd format returned by java.net.HttpURLConnection to a simpler java.util.Map.

Returns:

True if headers are successfully received, False on connection error.

receive

public int receive(byte[] buf)

Receive the next sequential bytes of the response body after successful connection. This will receive up to the size of the provided byte array. If there is no body, this will return 0 bytes on the first call after connection.

Parameters:

buf - A pre-allocated byte array to receive data into.

Returns:

The number of bytes from the start of the array which have been filled, 0 on EOF, or negative on error.

sendPostData

public boolean sendPostData(byte[] data,
                            int bytes)

For POST method requests, send a stream of data provided by the native side in repeated callbacks.

Parameters:

data - A byte array containing the data to sent, or null if indicating EOF.

bytes - The number of bytes from the start of the array to send, or 0 if indicating EOF.

Returns:

True if all bytes were successfully sent, false on error.