001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.microedition.io;
028:
029: import java.lang.String;
030: import java.io.IOException;
031: import javax.microedition.pki.Certificate;
032: import javax.microedition.pki.CertificateException;
033:
034: /**
035: * This interface defines the necessary methods
036: * and constants to establish a secure network connection.
037: * The URI format with scheme <CODE>https</CODE> when passed to
038: * <CODE>Connector.open</CODE> will return a
039: * <code>HttpsConnection</code>.
040: * <A HREF="http://www.ietf.org/rfc/rfc2818.txt">RFC 2818</A>
041: * defines the scheme.
042: * <p>
043: * A secure connection MUST be implemented by one or more
044: * of the following specifications:
045: * <UL>
046: * <LI>HTTP over TLS as documented in
047: * <A HREF="http://www.ietf.org/rfc/rfc2818.txt">RFC 2818</A>
048: * and TLS Protocol Version 1.0 as specified in
049: * <A HREF="http://www.ietf.org/rfc/rfc2246.txt">RFC 2246</A>.
050: *
051: * <LI>SSL V3 as specified in
052: * <A HREF="http://home.netscape.com/eng/ssl3/draft302.txt">
053: * The SSL Protocol Version 3.0</A>
054: * </LI>
055: *
056: * <LI>WTLS as specified in
057: * <A HREF="http://www.wapforum.org/what/technical_1_2_1.htm">
058: * WAP Forum Specifications June 2000 (WAP 1.2.1) conformance release</A>
059: * - Wireless Transport Layer Security document WAP-199.
060: * <LI>WAP(TM) TLS Profile and Tunneling Specification as specified
061: * in <A HREF="http://www.wapforum.com/what/technical.htm">
062: * WAP-219-TLS-20010411-a</A>
063: * </UL>
064: * <p>
065: * HTTPS is the secure version of HTTP (IETF RFC2616),
066: * a request-response protocol in which the parameters of the request must
067: * be set before the request is sent.
068: * <p>
069: * In addition to the normal <code>IOExceptions</code> that may occur during
070: * invocation of the various methods that cause a transition to the Connected
071: * state, <code>CertificateException</code>
072: * (a subtype of <code>IOException</code>) may be thrown to indicate various
073: * failures related to establishing the secure link. The secure link
074: * is necessary in the <code>Connected</code> state so the headers
075: * can be sent securely. The secure link may be established as early as the
076: * invocation of <code>Connector.open()</code> and related
077: * methods for opening input and output streams and failure related to
078: * certificate exceptions may be reported.
079: *
080: * </p><br>
081: * <b>Example</b><br>
082: *
083: * <p>Open a HTTPS connection, set its parameters, then read the HTTP
084: * response.</p>
085: *
086: * <code>Connector.open</code> is used to open the URL
087: * and an <code>HttpsConnection</code> is returned.
088: * The HTTP
089: * headers are read and processed. If the length is available, it is used
090: * to read the data in bulk. From the
091: * <code>HttpsConnection</code> the <code>InputStream</code> is
092: * opened. It is used to read every character until end of file (-1). If
093: * an exception is thrown the connection and stream are closed.
094: *
095: * <code><PRE>
096: * void getViaHttpsConnection(String url)
097: * throws CertificateException, IOException {
098: * HttpsConnection c = null;
099: * InputStream is = null;
100: * try {
101: * c = (HttpsConnection)Connector.open(url);
102: *
103: * // Getting the InputStream ensures that the connection
104: * // is opened (if it was not already handled by
105: * // Connector.open()) and the SSL handshake is exchanged,
106: * // and the HTTP response headers are read.
107: * // These are stored until requested.
108: * is = c.openDataInputStream();
109: *
110: * if c.getResponseCode() == HttpConnection.HTTP_OK) {
111: * // Get the length and process the data
112: * int len = (int)c.getLength();
113: * if (len > 0) {
114: * byte[] data = new byte[len];
115: * int actual = is.readFully(data);
116: * ...
117: * } else {
118: * int ch;
119: * while ((ch = is.read()) != -1) {
120: * ...
121: * }
122: * }
123: * } else {
124: * ...
125: * }
126: * } finally {
127: * if (is != null)
128: * is.close();
129: * if (c != null)
130: * c.close();
131: * }
132: * }
133: * </PRE> </code>
134: * @see CertificateException
135: */
136:
137: public interface HttpsConnection extends HttpConnection {
138: /**
139: * Return the security information associated with this
140: * successfully opened connection.
141: * If the connection is still in <CODE>Setup</CODE> state then
142: * the connection is initiated to establish the secure connection
143: * to the server. The method returns when the connection is
144: * established and the <CODE>Certificate</CODE> supplied by the
145: * server has been validated.
146: * The <CODE>SecurityInfo</CODE> is only returned if the
147: * connection has been successfully made to the server.
148: *
149: * @return the security information associated with this open connection.
150: *
151: * @exception IOException if an arbitrary connection failure occurs
152: */
153: public SecurityInfo getSecurityInfo() throws IOException;
154:
155: /**
156: * Returns the network port number of the URL for this
157: * <code>HttpsConnection</code>.
158: *
159: * @return the network port number of the URL for this
160: * <code>HttpsConnection</code>.
161: * The default HTTPS port number (443) is returned if there was
162: * no port number in the string passed to <code>Connector.open</code>.
163: */
164: public int getPort();
165:
166: }
|