javax.microedition.io
Interface HttpsConnection

All Superinterfaces:

Connection, ContentConnection, HttpConnection, InputConnection, OutputConnection, StreamConnection

public interface HttpsConnection
extends HttpConnection

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.

Blocking Operations

This interface performs blocking Input and Output operations. An application will lock if an implementation of this interface opens a connection from within the main event thread. Prevent an application from locking by opening a connection from within a thread that is separate from the main event thread. SeeConnector for more information.

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();
         }
     }
 

See Also:

CertificateException

Since:

BlackBerry API 4.0.0, MIDP 2.0

Field Summary

Fields inherited from interface javax.microedition.io.HttpConnection

GET, HEAD, HTTP_ACCEPTED, HTTP_BAD_GATEWAY, HTTP_BAD_METHOD, HTTP_BAD_REQUEST, HTTP_CLIENT_TIMEOUT, HTTP_CONFLICT, HTTP_CREATED, HTTP_ENTITY_TOO_LARGE, HTTP_EXPECT_FAILED, HTTP_FORBIDDEN, HTTP_GATEWAY_TIMEOUT, HTTP_GONE, HTTP_INTERNAL_ERROR, HTTP_LENGTH_REQUIRED, HTTP_MOVED_PERM, HTTP_MOVED_TEMP, HTTP_MULT_CHOICE, HTTP_NOT_ACCEPTABLE, HTTP_NOT_AUTHORITATIVE, HTTP_NOT_FOUND, HTTP_NOT_IMPLEMENTED, HTTP_NOT_MODIFIED, HTTP_NO_CONTENT, HTTP_OK, HTTP_PARTIAL, HTTP_PAYMENT_REQUIRED, HTTP_PRECON_FAILED, HTTP_PROXY_AUTH, HTTP_REQ_TOO_LONG, HTTP_RESET, HTTP_SEE_OTHER, HTTP_TEMP_REDIRECT, HTTP_UNAUTHORIZED, HTTP_UNAVAILABLE, HTTP_UNSUPPORTED_RANGE, HTTP_UNSUPPORTED_TYPE, HTTP_USE_PROXY, HTTP_VERSION, POST

Method Summary
int	getPort() Returns the network port number of the URL for this HttpsConnection.
SecurityInfo	getSecurityInfo() Return the security information associated with this successfully opened connection.

Methods inherited from interface javax.microedition.io.HttpConnection

getDate, getExpiration, getFile, getHeaderField, getHeaderField, getHeaderFieldDate, getHeaderFieldInt, getHeaderFieldKey, getHost, getLastModified, getProtocol, getQuery, getRef, getRequestMethod, getRequestProperty, getResponseCode, getResponseMessage, getURL, setRequestMethod, setRequestProperty

Methods inherited from interface javax.microedition.io.ContentConnection

getEncoding, getLength, getType

Methods inherited from interface javax.microedition.io.InputConnection

openDataInputStream, openInputStream

Methods inherited from interface javax.microedition.io.Connection

close

Methods inherited from interface javax.microedition.io.OutputConnection

openDataOutputStream, openOutputStream

Methods inherited from interface javax.microedition.io.Connection

close

Method Detail

getSecurityInfo

SecurityInfo getSecurityInfo()
                             throws IOException

Return the security information associated with this successfully opened connection. If the connection is still in 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.

Returns:

the security information associated with this open connection.

Throws:

IOException - if an arbitrary connection failure occurs

Since:

BlackBerry API 4.0.0

getPort

int getPort()

Returns the network port number of the URL for this HttpsConnection.

Specified by:

getPort in interface HttpConnection

Returns:

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.

Since:

BlackBerry API 4.0.0