javax.microedition.io.HttpConnection Maven / Gradle / Ivy

Neither this file nor any files generated from it describe a complete specification, and they may only be used as described below. For example, no permission is given for you to incorporate this file, in whole or in part, in an implementation of a Java specification.

Sun Microsystems Inc. owns the copyright in this file and it is provided to you for informative, as opposed to normative, use. The file and any files generated from it may be used to generate other informative documentation, such as a unified set of documents of API signatures for a platform that includes technologies expressed as Java APIs. The file may also be used to produce "compilation stubs," which allow applications to be compiled and validated for such platforms.

Any work generated from this file, such as unified javadocs or compiled stub files, must be accompanied by this notice in its entirety.

This work corresponds to the API signatures of JSR 219: Foundation Profile 1.1. In the event of a discrepency between this work and the JSR 219 specification, which is available at http://www.jcp.org/en/jsr/detail?id=219, the latter takes precedence. */ package javax.microedition.io; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; import java.lang.String; import javax.microedition.io.ContentConnection; /** * 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 *

*
• 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. *

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

*
• GET *
• POST *
• HEAD *

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. * * @param key the keyword by which the request is known * (e.g., "accept"). * @param value the value associated with it. * @exception IOException is thrown if the connection is in the * connected state. * @see #getRequestProperty */ public void setRequestProperty(java.lang.String key, java.lang.String value) throws IOException; /** * Returns the HTTP response status code. * It parses responses like: *

     * HTTP/1.0 200 OK
     * HTTP/1.0 401 Unauthorized
     * 

     * HTTP/1.0 200 OK
     * HTTP/1.0 404 Not Found
     * 

* 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. * * @param name the name of the header field. * @param def the default value. * @return the value of the named field, parsed as an integer. The * def value is returned if the field is * missing or malformed. * @exception IOException if an error occurred connecting to the server. */ public int getHeaderFieldInt(java.lang.String name, int def) throws IOException; /** * Returns the value of the named field parsed as date. * The result is the number of milliseconds since January 1, 1970 GMT * represented by the named field. *