httpconnection.java

用于移动设备上的java虚拟机源代码

/*
 * @(#)HttpConnection.java	1.51 02/09/06 @(#)
 *
 * Copyright (c) 1999-2002 Sun Microsystems, Inc.  All rights reserved.
 * PROPRIETARY/CONFIDENTIAL
 * Use is subject to license terms.
 */

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.
 * <P>
 * 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:
 * <UL>
 * <LI> Setup, in which the request parameters can be set
 * <LI> Connected, in which request parameters have been sent and the
 *      response is expected
 * <LI> Closed, the final state, in which the HTTP connection as been
 * terminated
 * </UL>
 * The following methods may be invoked only in the Setup state:
 * <UL>
 * <LI> <CODE> setRequestMethod</CODE>
 * <LI> <CODE> setRequestProperty</CODE>
 * </UL>
 *
 * The transition from Setup to Connected is caused by any method that
 * requires data to be sent to or received from the server. <p>
 *
 * The following methods cause the transition to the Connected state when
 * the connection is in Setup state.
 * <UL>
 * <LI> <CODE> openInputStream</CODE>
 * <LI> <CODE> openDataInputStream</CODE>
 * <LI> <CODE> getLength</CODE>
 * <LI> <CODE> getType</CODE>
 * <LI> <CODE> getEncoding</CODE>
 * <LI> <CODE> getHeaderField</CODE>
 * <LI> <CODE> getResponseCode</CODE>
 * <LI> <CODE> getResponseMessage</CODE>
 * <LI> <CODE> getHeaderFieldInt</CODE>
 * <LI> <CODE> getHeaderFieldDate</CODE>
 * <LI> <CODE> getExpiration</CODE>
 * <LI> <CODE> getDate</CODE>
 * <LI> <CODE> getLastModified</CODE>
 * <LI> <CODE> getHeaderField</CODE>
 * <LI> <CODE> getHeaderFieldKey</CODE>
 * </UL>
 * <P>
 * The following methods may be invoked while the connection is in Setup or
 * Connected state.
 * <UL>
 * <LI> <CODE> close</CODE>
 * <LI> <CODE> getRequestMethod</CODE>
 * <LI> <CODE> getRequestProperty</CODE>
 * <LI> <CODE> getURL</CODE>
 * <LI> <CODE> getProtocol</CODE>
 * <LI> <CODE> getHost</CODE>
 * <LI> <CODE> getFile</CODE>
 * <LI> <CODE> getRef</CODE>
 * <LI> <CODE> getPort</CODE>
 * <LI> <CODE> getQuery</CODE>
 * </UL>
 *
 * <P>
 * After an output stream has been opened by the
 * <code>openOutputStream</code> or <code>openDataOutputStream</code>
 * methods, attempts to change the request parameters via
 * <code>setRequestMethod</code> or the <code>setRequestProperty</code>
 * are ignored. Once the request parameters have been sent,
 * these methods will throw an <code>IOException</code>.
 *
 * When an output stream is closed via the
 * <code>OutputStream.close</code> or <code>DataOutputStream.close</code>
 * methods, the connection enters the Connected state.
 * When the output stream is flushed via the  
 * <code>OutputStream.flush</code> or <code>DataOutputStream.flush</code>
 * methods, the request parameters MUST be sent along with any data
 * written to the stream.
 * </P>
 *
 * The transition to Closed state from any other state is caused by the
 * <code>close</code> method and the closing all of the streams that were
 * opened from the connection. 
 * <P>
 * <STRONG>Example using StreamConnection</STRONG>
 * <p>
 * Simple read of a URL using <code>StreamConnection</code>.
 * No HTTP specific behavior is needed or used.
 * (<strong>Note:</strong> 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 <code>InputStream</code>.)
 *
 * <p>
 * <code>Connector.open</code> is used to open URL and a
 * <code>StreamConnection</code> is returned.
 * From the <code>StreamConnection</code> the
 * <code>InputStream</code> 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.
 * <p>
 * <pre>
 *     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();
 *         }
 *     }
 * </pre>
 * <p>
 * <STRONG>Example using ContentConnection</STRONG>
 * <p>
 * Simple read of a URL using <code>ContentConnection</code>.
 * No HTTP specific behavior is needed or used.
 * <p>
 * <code>Connector.open</code> is used to open url and
 * a <code>ContentConnection</code> is returned.
 * The <code>ContentConnection</code> may be able to provide the length.
 * If the length is available, it is used to read the data in bulk.
 * From the <code>ContentConnection</code> the
 * <code>InputStream</code> 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.
 * <p>
 * <pre>
 *     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 &gt; 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();
 *         }
 *     }
 * </pre>
 * <p>
 * <STRONG>Example using HttpConnection</STRONG>
 * <p>
 * Read the HTTP headers and the data using <code>HttpConnection</code>.
 * <p>
 * <code>Connector.open</code> is used to open url and a
 * <code>HttpConnection</code> 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 <code>HttpConnection</code> the
 * <code>InputStream</code> 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.
 * <p>
 * <pre>
 *     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 &gt; 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();
 *         }
 *     }
 * </pre>
 * <p>
 * <STRONG>Example using POST with HttpConnection</STRONG>
 * <p>
 *
 * Post a request with some headers and content to the server and
 * process the headers and content.
 * <p>
 * <code>Connector.open</code> is used to open url and a
 * <code>HttpConnection</code> 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 <code>HttpConnection</code> the
 * <code>InputStream</code> 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.
 * <p>
 * <pre>
 *    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 &gt; 0) {