HttpsConnection (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.microedition.io
Interface HttpsConnection

All Superinterfaces:
  Connection, ContentConnection, HttpConnection, InputConnection, OutputConnection, StreamConnection

    @TransactionType(value=NOT_SUPPORTED)
    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` or `PSKException` (subtypes 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 or pre-shared secret keys 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();
             }
         }

`

Since:
  MIDP 2.0, Foundation Profile 1.1, Java Card 3.0
See Also:
  `CertificateException`, `PSKException`

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_NO_CONTENT, HTTP_NOT_ACCEPTABLE, HTTP_NOT_AUTHORITATIVE, HTTP_NOT_FOUND, HTTP_NOT_IMPLEMENTED, HTTP_NOT_MODIFIED, 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.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` or `Pre-shared Secret Key` 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

### 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`.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.