| 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:
- Setup, in which the request parameters can be set
- Connected, in which request parameters have been sent and the
response is expected
- Closed, the final state, in which the HTTP connection as been
terminated
The following methods may be invoked only in the Setup state:
-
setRequestMethod
-
setRequestProperty
The transition from Setup to Connected is caused by any method that
requires data to be sent to or received from the server.
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.
The transition to Closed state from any other state is caused by the
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 distinguish which data is retrieved 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)
Please be aware that using these methods implies certain restrictions.
You will not get a reference to the actual connection, but rather just
references to the input or output stream of the connection. Not having
a reference to the connection means that you will not be able to manipulate
or query the connection directly. This in turn means that you will not
be able to call any of the following methods:
-
getRequestMethod()
-
setRequestMethod()
-
getRequestProperty()
-
setRequestProperty()
-
getLength()
-
getType()
-
getEncoding()
-
getHeaderField()
-
getResponseCode()
-
getResponseMessage()
-
getHeaderFieldInt
-
getHeaderFieldDate
-
getExpiration
-
getDate
-
getLastModified
-
getHeaderField
-
getHeaderFieldKey
since:
MIDP 1.0 |