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 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)
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