jsimple.net

Class HttpRequest

java.lang.Object

jsimple.net.HttpRequest

Direct Known Subclasses:

JavaHttpRequest

public abstract class HttpRequest
extends java.lang.Object

This class handles HTTP connectivity. It's based on a subset of the standard Java java.net.HttpURLConnection class, with some changes (to improve names, get rid of checked exceptions, etc.).

From the doc for java.net.HttpURLConnection: Each instance of this class is used to make a single request but the underlying network connection to the HTTP server may be transparently shared by other instances. Calling the close() methods on the InputStream or OutputStream of an HttpURLConnection after a request may free network resources associated with this instance but has no effect on any shared persistent connection. Calling the disconnect() method may close the underlying socket if a persistent connection is otherwise idle at that time.

This class is platform independent. Platforms (Java, C# for .Net, etc.) should define a subclass called "HttpRequest" which is what all the code will instantiate and use. That subclass should implement the abstract methods below and can implement other, platform specific, methods. Handling platform specific classes this way has a few advantages: There are no factory classes to define/implement nor a need to set a factory at app startup. And platform specific code can freely use platform specific methods implemented on the subclass with no casting required.

Since:

10/6/12 12:58 AM

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	HttpRequest.HttpRequestFactory

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	HEADER_ACCEPT
static java.lang.String	HEADER_CONTENT_LENGTH
static java.lang.String	HEADER_CONTENT_TYPE
static java.lang.String	HEADER_USER_AGENT
static java.lang.String	METHOD_DELETE
static java.lang.String	METHOD_GET
static java.lang.String	METHOD_POST
static java.lang.String	METHOD_PUT

Constructor Summary

Constructors

Constructor and Description
HttpRequest()

Method Summary

Modifier and Type	Method and Description
static HttpRequest	create(java.lang.String url) Create an HttpRequest, using the global factory.
abstract OutputStream	createRequestBodyStream() Returns an output stream that writes to this connection.
abstract java.lang.String	getHeader(java.lang.String name) Returns the value of the named header or null if it's not set.
abstract HttpResponse	send() Opens a communications link to the resource referenced by this URL, if such a connection has not already been established.
void	setContentTypeAndAcceptHeaders(java.lang.String contentType, java.lang.String accept) This is a convenience method to set both the Content-Type and Accept headers, at the same time.
static void	setFactory(HttpRequest.HttpRequestFactory httpRequestFactory) Set the global (default) factory used to create http requests.
abstract void	setHeader(java.lang.String name, java.lang.String value) Sets the specified HTTP request header to the specified value.
abstract void	setMethod(java.lang.String method) Set the method for the request, one of: GET POST HEAD OPTIONS PUT DELETE TRACE are legal, subject to protocol restrictions.
abstract void	setTimeout(int timeoutInMillis) Sets a specified timeout value, in milliseconds, to be used when doing connecting/reading/writing to the server.

Methods inherited from class java.lang.Object

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

Field Detail

METHOD_GET

public static final java.lang.String METHOD_GET

See Also:

Constant Field Values

METHOD_POST

public static final java.lang.String METHOD_POST

See Also:

Constant Field Values

METHOD_PUT

public static final java.lang.String METHOD_PUT

See Also:

Constant Field Values

METHOD_DELETE

public static final java.lang.String METHOD_DELETE

See Also:

Constant Field Values

HEADER_CONTENT_LENGTH

public static final java.lang.String HEADER_CONTENT_LENGTH

See Also:

Constant Field Values

HEADER_CONTENT_TYPE

public static final java.lang.String HEADER_CONTENT_TYPE

See Also:

Constant Field Values

HEADER_USER_AGENT

public static final java.lang.String HEADER_USER_AGENT

See Also:

Constant Field Values

HEADER_ACCEPT

public static final java.lang.String HEADER_ACCEPT

See Also:

Constant Field Values

Constructor Detail

HttpRequest

public HttpRequest()

Method Detail

create

public static HttpRequest create(java.lang.String url)

Create an HttpRequest, using the global factory. This method is the normal way to create an HttpRequest, using the default implementation appropriate for the current platform.

Parameters:

url - URL

Returns:

HttpRequest object

setFactory

public static void setFactory(@Nullable
                              HttpRequest.HttpRequestFactory httpRequestFactory)

Set the global (default) factory used to create http requests. Clients normally don't call this method directly and just call JSimpleIO.init at app startup instead, which sets the factory to the default implementation appropriate for the current platform.

Parameters:

httpRequestFactory - factory

setMethod

public abstract void setMethod(java.lang.String method)

Set the method for the request, one of:

GET POST HEAD OPTIONS PUT DELETE TRACE

are legal, subject to protocol restrictions. The default method is GET.

Parameters:

method - the HTTP method

setContentTypeAndAcceptHeaders

public void setContentTypeAndAcceptHeaders(java.lang.String contentType,
                                           java.lang.String accept)

This is a convenience method to set both the Content-Type and Accept headers, at the same time. For example, it can be used to set them both to "application/json", for a typical REST API JSON request that expects a JSON response.

Parameters:

contentType - Content-Type header value

accept - Accept header value

setTimeout

public abstract void setTimeout(int timeoutInMillis)

Sets a specified timeout value, in milliseconds, to be used when doing connecting/reading/writing to the server. A timeout of zero is interpreted as an infinite timeout. If the timeout expires before the operation is complete, an exception is raised (e.g. java.net.SocketTimeoutException for the Java version for connect timeouts).

For now, we just have one timeout value rather than multiple settings per operation type, as that makes cross platform support easier and is generally good enough for clients.

Parameters:

timeoutInMillis - an int that specifies the connect timeout value in milliseconds

setHeader

public abstract void setHeader(java.lang.String name,
                               java.lang.String value)

Sets the specified HTTP request header to the specified value. If a header with the key already exists, overwrite its value with the new value.

NOTE: HTTP requires all request headers which can legally have multiple instances with the same key to use a comma-separated list syntax which enables multiple values to be appended into a single header. This method replaces an existing header with the specified name; get the existing header and append to it if you wish to make it multi-valued.

Parameters:

name - the header name (e.g., "Accept")

value - the value associated with it

getHeader

public abstract java.lang.String getHeader(java.lang.String name)

Returns the value of the named header or null if it's not set.

Parameters:

name - the header name (e.g., "Accept").

Returns:

the value of the header

createRequestBodyStream

public abstract OutputStream createRequestBodyStream()

Returns an output stream that writes to this connection. If your app needs to set the value of the ContentLength header, then this must be done before retrieving the stream (which, for one thing, is enforced on .NET). You must close the stream after you finish writing to it; failing to do that may make the system run out of connections (another .NET warning & good practice in general).

Returns:

an output stream that writes to this connection.

Throws:

IOException - if an I/O error occurs while opening the connection.

send

public abstract HttpResponse send()

Opens a communications link to the resource referenced by this URL, if such a connection has not already been established.

If the connect method is called when the connection has already been opened.

HttpRequest objects go through two phases: first they are created, then they are connected. After being created, and before being connected, various options can be specified (e.g., doInput and UseCaches). After connecting, it is an error to try to set them. Operations that depend on being connected, like getContentLength, will implicitly perform the connection, if necessary.

Throws:

SocketTimeoutException - if the timeout expires before the connection can be established

IOException - if an I/O error occurs while opening the connection.

See Also:

setTimeout(int)