javax.microedition.io.HttpsConnection Maven / Gradle / Ivy
/*
This is not an official specification document, and usage is restricted.
NOTICE
(c) 2005-2007 Sun Microsystems, Inc. All Rights Reserved.
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.lang.String;
import java.io.IOException;
/**
* This interface defines the necessary methods
* and constants to establish a secure network connection.
* The URI format with scheme https when passed to
* Connector.open will return a
* HttpsConnection.
* RFC 2818
* defines the scheme.
*
* A secure connection MUST be implemented by one or more
* of the following specifications:
*
* - HTTP over TLS as documented in
* RFC 2818
* and TLS Protocol Version 1.0 as specified in
* RFC 2246.
*
*
- SSL V3 as specified in
*
* The SSL Protocol Version 3.0
*
*
* - WTLS as specified in
*
* WAP Forum Specifications June 2000 (WAP 1.2.1) conformance release
* - Wireless Transport Layer Security document WAP-199.
*
- WAP(TM) TLS Profile and Tunneling Specification as specified
* in
* WAP-219-TLS-20010411-a
*
*
* HTTPS is the secure version of HTTP (IETF RFC2616),
* a request-response protocol in which the parameters of the request must
* be set before the request is sent.
*
* In addition to the normal IOExceptions that may occur during
* invocation of the various methods that cause a transition to the Connected
* state, CertificateException
* (a subtype of IOException) may be thrown to indicate various
* failures related to establishing the secure link. The secure link
* is necessary in the Connected state so the headers
* can be sent securely. The secure link may be established as early as the
* invocation of Connector.open() and related
* methods for opening input and output streams and failure related to
* certificate exceptions may be reported.
*
*
* Example
*
* Open a HTTPS connection, set its parameters, then read the HTTP
* response.
*
* Connector.open is used to open the URL
* and an HttpsConnection 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
* HttpsConnection 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 getViaHttpsConnection(String url)
* throws CertificateException, IOException {
* HttpsConnection c = null;
* InputStream is = null;
* try {
* c = (HttpsConnection)Connector.open(url);
*
* // Getting the InputStream ensures that the connection
* // is opened (if it was not already handled by
* // Connector.open()) and the SSL handshake is exchanged,
* // and the HTTP response headers are read.
* // These are stored until requested.
* is = c.openDataInputStream();
*
* if c.getResponseCode() == HttpConnection.HTTP_OK) {
* // Get the length and process the data
* int len = (int)c.getLength();
* if (len > 0) {
* byte[] data = new byte[len];
* int actual = is.readFully(data);
* ...
* } else {
* int ch;
* while ((ch = is.read()) != -1) {
* ...
* }
* }
* } else {
* ...
* }
* } finally {
* if (is != null)
* is.close();
* if (c != null)
* c.close();
* }
* }
* Setup state then
* the connection is initiated to establish the secure connection
* to the server. The method returns when the connection is
* established and the Certificate supplied by the
* server has been validated.
* The SecurityInfo is only returned if the
* connection has been successfully made to the server.
*
* @return the security information associated with this open connection.
*
* @exception IOException if an arbitrary connection failure occurs
*/
public SecurityInfo getSecurityInfo() throws IOException;
/**
* Returns the network port number of the URL for this
* HttpsConnection.
*
* @return the network port number of the URL for this
* HttpsConnection.
* The default HTTPS port number (443) is returned if there was
* no port number in the string passed to Connector.open.
*/
public int getPort();
}