httpconnection.java

有关j2me的很好的例子可以研究一下

/*
 * @(#)HttpConnection.java	1.38 01/08/21
 * Copyright (c) 1999-2001 Sun Microsystems, Inc. All Rights Reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 *
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
 * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
 * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
 * THIS SOFTWARE OR ITS DERIVATIVES.
 */

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 connection has not been made to the server.
 * <LI> Connected, in which the connection has been made, request parameters
 * have been sent and the response is expected.
 * <LI> Closed, in which the connection has been closed and the methods will
 *	throw an IOException if called.
 * </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
 * <UL>
 * <LI> <CODE> openInputStream</CODE>
 * <LI> <CODE> openOutputStream</CODE>
 * <LI> <CODE> openDataInputStream</CODE>
 * <LI> <CODE> openDataOutputStream</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 open.
 * <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>
 * <STRONG>Example using StreamConnection</STRONG>
 * <p>
 * Simple read of a url using StreamConnection.
 * No HTTP specific behavior is needed or used.
 * <p>
 * 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.
 * <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 ContentConnection.
 * No HTTP specific behavior is needed or used.
 * <p>
 * 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.
 * <p>
 * <pre>
 *     void getViaContentConnection(String url) throws IOException {
 *         ContentConnection c = null;
 *         InputStream is = null;
 *         try {
 *             c = (ContentConnection)Connector.open(url);
 *             int len = (int)c.getLength();
 *             if (len > 0) {
 *                 is = c.openInputStream();
 *                 byte[] data = new byte[len];
 *                 int actual = is.read(data);
 *                 ...
 *             } else {
 *                 int ch;
 *                 while ((ch = is.read()) != -1) {
 *                     ...
 *                 }
 *             }
 *         } finally {
 *             if (is != null)
 *                 is.close();
 *             if (c != null)
 *                 c.close();
 *         }
 *     }
 * </pre>
 * <p>
 * <STRONG>Example using HttpConnection</STRONG>
 * <p>
 * Read the HTTP headers and the data using HttpConnection.
 * <p>
 * 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.
 * <p>
 * <pre>
 *     void getViaHttpConnection(String url) throws IOException {
 *         HttpConnection c = null;
 *         InputStream is = null;
 *         try {
 *             c = (HttpConnection)Connector.open(url);
 * 
 *             // Getting the InputStream will open the connection
 *             // and read the HTTP headers. They are stored until
 *             // requested.
 *             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) {
 *                 byte[] data = new byte[len];
 *                 int actual = is.read(data);
 *                 ...
 *             } else {
 *                 int ch;
 *                 while ((ch = is.read()) != -1) {
 *                     ...
 *                 }
 *             }
 *         } 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>
 * 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.
 * <p>
 * <pre>
 *    void postViaHttpConnection(String url) throws IOException {
 *        HttpConnection c = null;
 *        InputStream is = null;
 *        OutputStream os = null;
 *
 *        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-1.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, openInputStream will flush
 *
 *            // Opening the InputStream will open the connection
 *            // and read the HTTP headers. They are stored until
 *            // requested.
 *            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) {
 *                byte[] data = new byte[len];
 *                int actual = is.read(data);
 *                process(data);
 *            } else {
 *                int ch;
 *                while ((ch = is.read()) != -1) {
 *                    process((byte)ch);
 *                }
 *            }
 *        } finally {
 *            if (is != null)
 *                is.close();
 *            if (os != null)
 *                os.close();
 *            if (c != null)
 *                c.close();
 *        }
 *    }
 * </pre>
 * <hr>
 * <p>
 * <STRONG>Simplified Stream Methods on Connector</STRONG>
 * <p>
 * Please note the following: The Connector class defines the following 
 * convenience methods for retrieving an input or output stream directly 
 * for a specified URL:
 *
 * <UL>
 * <LI> <CODE> InputStream openDataInputStream(String url) </CODE>
 * <LI> <CODE> DataInputStream openDataInputStream(String url) </CODE>
 * <LI> <CODE> OutputStream openOutputStream(String url) </CODE>
 * <LI> <CODE> DataOutputStream openDataOutputStream(String url) </CODE>
 * </UL>
 * 
 * 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:
 *
 * <UL>
 * <LI> <CODE> getRequestMethod() </CODE> 
 * <LI> <CODE> setRequestMethod() </CODE>
 * <LI> <CODE> getRequestProperty() </CODE>
 * <LI> <CODE> setRequestProperty() </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>
 */
public interface HttpConnection extends ContentConnection {
    /** HTTP Head method. */
    public final static String HEAD = "HEAD";
    /** HTTP Get method. */
    public final static String GET = "GET";
    /** HTTP Post method. */
    public final static String POST = "POST";

    /** 2XX: generally "OK" */
    /** 200: The request has succeeded. */
    public static final int HTTP_OK = 200;

    /**
     * 201: The request has been fulfilled and resulted in a new
     * resource being created.
     */
    public static final int HTTP_CREATED = 201;

    /**
     * 202: The request has been accepted for processing, but the processing 
     * has not been completed.
     */
    public static final int HTTP_ACCEPTED = 202;

    /**
     * 203: The returned meta-information in the entity-header is not the
     *  definitive set as available from the origin server.
     */
    public static final int HTTP_NOT_AUTHORITATIVE = 203; 

    /**
     * 204:  The server has fulfilled the request but does not need to
     * return an entity-body, and might want to return updated 
     * meta-information.
     */
    public static final int HTTP_NO_CONTENT = 204;

    /**
     * 205: The server has fulfilled the request and the user agent SHOULD reset
     *	the document view which caused the request to be sent.
     */
    public static final int HTTP_RESET = 205;

    /**
     * 206: The server has fulfilled the partial GET request for the resource.
     */
    public static final int HTTP_PARTIAL = 206;

    /** 3XX: relocation/redirect */
    /**
     * 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. */
    public static final int HTTP_MULT_CHOICE = 300;

    /**
     * 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.
     */
    public static final int HTTP_MOVED_PERM = 301;

    /**
     * 302: The requested resource resides temporarily under a
     * different URI.
     */
    public static final int HTTP_MOVED_TEMP = 302;

    /**
     * 303: The response to the request can be found under a different URI and
     *   SHOULD be retrieved using a GET method on that resource.
     */
    public static final int HTTP_SEE_OTHER = 303;

    /**
     *  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.
     */
    public static final int HTTP_NOT_MODIFIED = 304;

    /**
     * 305: The requested resource MUST be accessed through the proxy given by
     *	the Location field.
     */
    public static final int HTTP_USE_PROXY = 305;

    /** 
     * 307: The requested resource resides temporarily under a different URI.
     */
    public static final int HTTP_TEMP_REDIRECT = 307;

    /** 4XX: client error */
    /**