|
MID Profile | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
This interface defines the necessary methods and constants for an HTTP connection.
HTTP is a request-response protocol in which the parameters of request must be set before the request is sent. The connection exists in one of three states:
setRequestMethod
setRequestProperty
The following methods cause the transition to the Connected state when the connection is in Setup state.
openInputStream
openDataInputStream
getLength
getType
getEncoding
getHeaderField
getResponseCode
getResponseMessage
getHeaderFieldInt
getHeaderFieldDate
getExpiration
getDate
getLastModified
getHeaderField
getHeaderFieldKey
The following methods may be invoked while the connection is in Setup or Connected state.
close
getRequestMethod
getRequestProperty
getURL
getProtocol
getHost
getFile
getRef
getPort
getQuery
After an output stream has been opened by the
openOutputStream
or openDataOutputStream
methods, attempts to change the request parameters via
setRequestMethod
or the setRequestProperty
are ignored. Once the request parameters have been sent,
these methods will throw an IOException
.
When an output stream is closed via the
OutputStream.close
or DataOutputStream.close
methods, the connection enters the Connected state.
When the output stream is flushed via the
OutputStream.flush
or DataOutputStream.flush
methods, the request parameters MUST be sent along with any data
written to the stream.
close
method and the closing all of the streams that were
opened from the connection.
Example using StreamConnection
Simple read of a URL using StreamConnection
.
No HTTP specific behavior is needed or used.
(Note: this example ignores all HTTP response
headers and the HTTP response code. Since a proxy or server
may have sent an error response page, an application
can not distinquish which data is retreived in
the InputStream
.)
Connector.open
is used to open URL and a
StreamConnection
is returned.
From the StreamConnection
the
InputStream
is opened.
It is used to read every character until end of file (-1).
If an exception is thrown the connection and stream are closed.
void getViaStreamConnection(String url) throws IOException { StreamConnection c = null; InputStream s = null; try { c = (StreamConnection)Connector.open(url); s = c.openInputStream(); int ch; while ((ch = s.read()) != -1) { ... } } finally { if (s != null) s.close(); if (c != null) c.close(); } }
Example using ContentConnection
Simple read of a URL using ContentConnection
.
No HTTP specific behavior is needed or used.
Connector.open
is used to open url and
a ContentConnection
is returned.
The ContentConnection
may be able to provide the length.
If the length is available, it is used to read the data in bulk.
From the ContentConnection
the
InputStream
is opened.
It is used to read every character until end of file (-1).
If an exception is thrown the connection and stream are closed.
void getViaContentConnection(String url) throws IOException { ContentConnection c = null; DataInputStream is = null; try { c = (ContentConnection)Connector.open(url); int len = (int)c.getLength(); dis = c.openDataInputStream(); if (len > 0) { byte[] data = new byte[len]; dis.readFully(data); } else { int ch; while ((ch = dis.read()) != -1) { ... } } } finally { if (dis != null) dis.close(); if (c != null) c.close(); } }
Example using HttpConnection
Read the HTTP headers and the data using HttpConnection
.
Connector.open
is used to open url and a
HttpConnection
is returned.
The HTTP headers are read and processed.
If the length is available, it is used to read the data in bulk.
From the HttpConnection
the
InputStream
is opened.
It is used to read every character until end of file (-1).
If an exception is thrown the connection and stream are closed.
void getViaHttpConnection(String url) throws IOException { HttpConnection c = null; InputStream is = null; int rc; try { c = (HttpConnection)Connector.open(url); // Getting the response code will open the connection, // send the request, and read the HTTP response headers. // The headers are stored until requested. rc = c.getResponseCode(); if (rc != HttpConnection.HTTP_OK) { throw new IOException("HTTP response code: " + rc); } is = c.openInputStream(); // Get the ContentType String type = c.getType(); // Get the length and process the data int len = (int)c.getLength(); if (len > 0) { int actual = 0; int bytesread = 0 ; byte[] data = new byte[len]; while ((bytesread != len) && (actual != -1)) { actual = is.read(data, bytesread, len - bytesread); bytesread += actual; } } else { int ch; while ((ch = is.read()) != -1) { ... } } } catch (ClassCastException e) { throw new IllegalArgumentException("Not an HTTP URL"); } finally { if (is != null) is.close(); if (c != null) c.close(); } }
Example using POST with HttpConnection
Post a request with some headers and content to the server and process the headers and content.
Connector.open
is used to open url and a
HttpConnection
is returned.
The request method is set to POST and request headers set.
A simple command is written and flushed.
The HTTP headers are read and processed.
If the length is available, it is used to read the data in bulk.
From the HttpConnection
the
InputStream
is opened.
It is used to read every character until end of file (-1).
If an exception is thrown the connection and stream is closed.
void postViaHttpConnection(String url) throws IOException { HttpConnection c = null; InputStream is = null; OutputStream os = null; int rc; try { c = (HttpConnection)Connector.open(url); // Set the request method and headers c.setRequestMethod(HttpConnection.POST); c.setRequestProperty("If-Modified-Since", "29 Oct 1999 19:43:31 GMT"); c.setRequestProperty("User-Agent", "Profile/MIDP-2.0 Configuration/CLDC-1.0"); c.setRequestProperty("Content-Language", "en-US"); // Getting the output stream may flush the headers os = c.openOutputStream(); os.write("LIST games\n".getBytes()); os.flush(); // Optional, getResponseCode will flush // Getting the response code will open the connection, // send the request, and read the HTTP response headers. // The headers are stored until requested. rc = c.getResponseCode(); if (rc != HttpConnection.HTTP_OK) { throw new IOException("HTTP response code: " + rc); } is = c.openInputStream(); // Get the ContentType String type = c.getType(); processType(type); // Get the length and process the data int len = (int)c.getLength(); if (len > 0) { int actual = 0; int bytesread = 0 ; byte[] data = new byte[len]; while ((bytesread != len) && (actual != -1)) { actual = is.read(data, bytesread, len - bytesread); bytesread += actual; } process(data); } else { int ch; while ((ch = is.read()) != -1) { process((byte)ch); } } } catch (ClassCastException e) { throw new IllegalArgumentException("Not an HTTP URL"); } finally { if (is != null) is.close(); if (os != null) os.close(); if (c != null) c.close(); } }
Simplified Stream Methods on Connector
Please note the following: The
Connector
class defines the following
convenience methods for retrieving an input or output stream directly
for a specified URL:
InputStream openInputStream(String url)
DataInputStream openDataInputStream(String url)
OutputStream openOutputStream(String url)
DataOutputStream openDataOutputStream(String url)
getRequestMethod()
setRequestMethod()
getRequestProperty()
setRequestProperty()
getLength()
getType()
getEncoding()
getHeaderField()
getResponseCode()
getResponseMessage()
getHeaderFieldInt
getHeaderFieldDate
getExpiration
getDate
getLastModified
getHeaderField
getHeaderFieldKey
Field Summary | |
static String |
GET
HTTP Get method. |
static String |
HEAD
HTTP Head method. |
static int |
HTTP_ACCEPTED
202: The request has been accepted for processing, but the processing has not been completed. |
static int |
HTTP_BAD_GATEWAY
502: The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request. |
static int |
HTTP_BAD_METHOD
405: The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. |
static int |
HTTP_BAD_REQUEST
400: The request could not be understood by the server due to malformed syntax. |
static int |
HTTP_CLIENT_TIMEOUT
408: The client did not produce a request within the time that the server was prepared to wait. |
static int |
HTTP_CONFLICT
409: The request could not be completed due to a conflict with the current state of the resource. |
static int |
HTTP_CREATED
201: The request has been fulfilled and resulted in a new resource being created. |
static int |
HTTP_ENTITY_TOO_LARGE
413: The server is refusing to process a request because the request entity is larger than the server is willing or able to process. |
static int |
HTTP_EXPECT_FAILED
417: The expectation given in an Expect request-header field could not be met by this server, or, if the server is a proxy, the server has unambiguous evidence that the request could not be met by the next-hop server. |
static int |
HTTP_FORBIDDEN
403: The server understood the request, but is refusing to fulfill it. |
static int |
HTTP_GATEWAY_TIMEOUT
504: The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI or some other auxiliary server it needed to access in attempting to complete the request. |
static int |
HTTP_GONE
410: The requested resource is no longer available at the server and no forwarding address is known. |
static int |
HTTP_INTERNAL_ERROR
500: The server encountered an unexpected condition which prevented it from fulfilling the request. |
static int |
HTTP_LENGTH_REQUIRED
411: The server refuses to accept the request without a defined Content- Length. |
static int |
HTTP_MOVED_PERM
301: The requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs. |
static int |
HTTP_MOVED_TEMP
302: The requested resource resides temporarily under a different URI. |
static int |
HTTP_MULT_CHOICE
300: The requested resource corresponds to any one of a set of representations, each with its own specific location, and agent- driven negotiation information is being provided so that the user (or user agent) can select a preferred representation and redirect its request to that location. |
static int |
HTTP_NO_CONTENT
204: The server has fulfilled the request but does not need to return an entity-body, and might want to return updated meta-information. |
static int |
HTTP_NOT_ACCEPTABLE
406: The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request. |
static int |
HTTP_NOT_AUTHORITATIVE
203: The returned meta-information in the entity-header is not the definitive set as available from the origin server. |
static int |
HTTP_NOT_FOUND
404: The server has not found anything matching the Request-URI. |
static int |
HTTP_NOT_IMPLEMENTED
501: The server does not support the functionality required to fulfill the request. |
static int |
HTTP_NOT_MODIFIED
304: If the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server SHOULD respond with this status code. |
static int |
HTTP_OK
200: The request has succeeded. |
static int |
HTTP_PARTIAL
206: The server has fulfilled the partial GET request for the resource. |
static int |
HTTP_PAYMENT_REQUIRED
402: This code is reserved for future use. |
static int |
HTTP_PRECON_FAILED
412: The precondition given in one or more of the request-header fields evaluated to false when it was tested on the server. |
static int |
HTTP_PROXY_AUTH
407: This code is similar to 401 (Unauthorized), but indicates that the client must first authenticate itself with the proxy. |
static int |
HTTP_REQ_TOO_LONG
414: The server is refusing to service the request because the Request-URI is longer than the server is willing to interpret. |
static int |
HTTP_RESET
205: The server has fulfilled the request and the user agent SHOULD reset the document view which caused the request to be sent. |
static int |
HTTP_SEE_OTHER
303: The response to the request can be found under a different URI and SHOULD be retrieved using a GET method on that resource. |
static int |
HTTP_TEMP_REDIRECT
307: The requested resource resides temporarily under a different URI. |
static int |
HTTP_UNAUTHORIZED
401: The request requires user authentication. |
static int |
HTTP_UNAVAILABLE
503: The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. |
static int |
HTTP_UNSUPPORTED_RANGE
416: A server SHOULD return a response with this status code if a request included a Range request-header field , and none of the range-specifier values in this field overlap the current extent of the selected resource, and the request did not include an If-Range request-header field. |
static int |
HTTP_UNSUPPORTED_TYPE
415: The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. |
static int |
HTTP_USE_PROXY
305: The requested resource MUST be accessed through the proxy given by the Location field. |
static int |
HTTP_VERSION
505: The server does not support, or refuses to support, the HTTP protocol version that was used in the request message. |
static String |
POST
HTTP Post method. |
Method Summary | |
long |
getDate()
Returns the value of the date header field. |
long |
getExpiration()
Returns the value of the expires header field. |
String |
getFile()
Returns the file portion of the URL of this HttpConnection . |
String |
getHeaderField(int n)
Gets a header field value by index. |
String |
getHeaderField(String name)
Returns the value of the named header field. |
long |
getHeaderFieldDate(String name,
long def)
Returns the value of the named field parsed as date. |
int |
getHeaderFieldInt(String name,
int def)
Returns the value of the named field parsed as a number. |
String |
getHeaderFieldKey(int n)
Gets a header field key by index. |
String |
getHost()
Returns the host information of the URL of this HttpConnection . |
long |
getLastModified()
Returns the value of the last-modified header field. |
int |
getPort()
Returns the network port number of the URL for this HttpConnection . |
String |
getProtocol()
Returns the protocol name of the URL of this HttpConnection . |
String |
getQuery()
Returns the query portion of the URL of this HttpConnection . |
String |
getRef()
Returns the ref portion of the URL of this HttpConnection . |
String |
getRequestMethod()
Get the current request method. |
String |
getRequestProperty(String key)
Returns the value of the named general request property for this connection. |
int |
getResponseCode()
Returns the HTTP response status code. |
String |
getResponseMessage()
Gets the HTTP response message, if any, returned along with the response code from a server. |
String |
getURL()
Return a string representation of the URL for this connection. |
void |
setRequestMethod(String method)
Set the method for the URL request, one of: GET POST HEAD are legal, subject to protocol restrictions. |
void |
setRequestProperty(String key,
String value)
Sets the general request property. |
Methods inherited from interface javax.microedition.io.ContentConnection |
getEncoding, getLength, getType |
Methods inherited from interface javax.microedition.io.InputConnection |
openDataInputStream, openInputStream |
Methods inherited from interface javax.microedition.io.Connection |
close |
Methods inherited from interface javax.microedition.io.OutputConnection |
openDataOutputStream, openOutputStream |
Field Detail |
public static final String HEAD
public static final String GET
public static final String POST
public static final int HTTP_OK
public static final int HTTP_CREATED
public static final int HTTP_ACCEPTED
public static final int HTTP_NOT_AUTHORITATIVE
public static final int HTTP_NO_CONTENT
public static final int HTTP_RESET
public static final int HTTP_PARTIAL
public static final int HTTP_MULT_CHOICE
public static final int HTTP_MOVED_PERM
public static final int HTTP_MOVED_TEMP
Location
header indicates where the application should resend
the request.)public static final int HTTP_SEE_OTHER
public static final int HTTP_NOT_MODIFIED
public static final int HTTP_USE_PROXY
public static final int HTTP_TEMP_REDIRECT
public static final int HTTP_BAD_REQUEST
public static final int HTTP_UNAUTHORIZED
public static final int HTTP_PAYMENT_REQUIRED
public static final int HTTP_FORBIDDEN
public static final int HTTP_NOT_FOUND
public static final int HTTP_BAD_METHOD
public static final int HTTP_NOT_ACCEPTABLE
public static final int HTTP_PROXY_AUTH
public static final int HTTP_CLIENT_TIMEOUT
public static final int HTTP_CONFLICT
public static final int HTTP_GONE
public static final int HTTP_LENGTH_REQUIRED
public static final int HTTP_PRECON_FAILED
public static final int HTTP_ENTITY_TOO_LARGE
public static final int HTTP_REQ_TOO_LONG
public static final int HTTP_UNSUPPORTED_TYPE
public static final int HTTP_UNSUPPORTED_RANGE
public static final int HTTP_EXPECT_FAILED
public static final int HTTP_INTERNAL_ERROR
public static final int HTTP_NOT_IMPLEMENTED
public static final int HTTP_BAD_GATEWAY
public static final int HTTP_UNAVAILABLE
public static final int HTTP_GATEWAY_TIMEOUT
public static final int HTTP_VERSION
Method Detail |
public String getURL()
public String getProtocol()
HttpConnection
. e.g., http or httpsHttpConnection
.public String getHost()
HttpConnection
. e.g. host name or IPv4 addressHttpConnection
.public String getFile()
HttpConnection
.HttpConnection
.
null
is returned if there is no file.public String getRef()
HttpConnection
.
RFC2396 specifies the optional fragment identifier as the
the text after the crosshatch (#) character in the URL.
This information may be used by the user agent as additional
reference information after the resource is successfully retrieved.
The format and interpretation of the fragment identifier is dependent
on the media type[RFC2046] of the retrieved information.HttpConnection
.
null
is returned if there is no value.public String getQuery()
HttpConnection
.
RFC2396 defines the query component as the text after the first
question-mark (?) character in the URL.HttpConnection
.
null
is returned if there is no value.public int getPort()
HttpConnection
.HttpConnection
.
The default HTTP port number (80) is returned if there was
no port number in the string passed to Connector.open
.public String getRequestMethod()
setRequestMethod(java.lang.String)
public void setRequestMethod(String method) throws IOException
method
- the HTTP methodIOException
- if the method cannot be reset or if
the requested method isn't valid for HTTP.getRequestMethod()
public String getRequestProperty(String key)
key
- the keyword by which the request property is
known (e.g., "accept").null
is returned.setRequestProperty(java.lang.String, java.lang.String)
public void setRequestProperty(String key, String value) throws IOException
Note: HTTP requires all request properties which can legally have multiple instances with the same key to use a comma-separated list syntax which enables multiple properties to be appended into a single property.
key
- the keyword by which the request is known
(e.g., "accept
").value
- the value associated with it.IOException
- is thrown if the connection is in the
connected state.getRequestProperty(java.lang.String)
public int getResponseCode() throws IOException
HTTP/1.0 200 OK HTTP/1.0 401 Unauthorizedand extracts the ints 200 and 401 respectively. from the response (i.e., the response is not valid HTTP).
IOException
- if an error occurred connecting to the server.public String getResponseMessage() throws IOException
HTTP/1.0 200 OK HTTP/1.0 404 Not FoundExtracts the Strings "OK" and "Not Found" respectively. Returns null if none could be discerned from the responses (the result was not valid HTTP).
null
IOException
- if an error occurred connecting to the server.public long getExpiration() throws IOException
expires
header field.IOException
- if an error occurred connecting to the server.public long getDate() throws IOException
date
header field.0
if not known. The value returned is the
number of milliseconds since January 1, 1970 GMT.IOException
- if an error occurred connecting to the server.public long getLastModified() throws IOException
last-modified
header field.
The result is the number of milliseconds since January 1, 1970 GMT.HttpConnection
was last modified, or
0 if not known.IOException
- if an error occurred connecting to the server.public String getHeaderField(String name) throws IOException
name
- of a header field.null
if there is no such field in the header.IOException
- if an error occurred connecting to the server.public int getHeaderFieldInt(String name, int def) throws IOException
This form of getHeaderField
exists because some
connection types (e.g., http-ng
) have pre-parsed
headers. Classes for that connection type can override this method
and short-circuit the parsing.
name
- the name of the header field.def
- the default value.def
value is returned if the field is
missing or malformed.IOException
- if an error occurred connecting to the server.public long getHeaderFieldDate(String name, long def) throws IOException
This form of getHeaderField
exists because some
connection types (e.g., http-ng
) have pre-parsed
headers. Classes for that connection type can override this method
and short-circuit the parsing.
name
- the name of the header field.def
- a default value.def
argument is returned if the field is
missing or malformed.IOException
- if an error occurred connecting to the server.public String getHeaderField(int n) throws IOException
n
- the index of the header fieldnull
if the array index is out of range.
An empty String is returned if the field does not have a value.IOException
- if an error occurred connecting to the server.public String getHeaderFieldKey(int n) throws IOException
n
- the index of the header fieldnull
if the array index is out of range.IOException
- if an error occurred connecting to the server.
|
MID Profile | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |