net.rim.device.api.crypto.tls.ssl30
Class SSL30Connection

java.lang.Object
  extended by net.rim.device.api.crypto.tls.ssl30.SSL30Connection
All Implemented Interfaces:
ConnectionCloseListener, ConnectionCloseProvider, ParentStreamProvider, SocketConnectionEnhanced

public class SSL30Connection
extends Object
implements ParentStreamProvider, ConnectionCloseProvider, ConnectionCloseListener, SocketConnectionEnhanced

This class can be used to instantiate a SSL3.0 connection directly given an underlying connection (such as TCP) or it can be instantiated using Connector.open and specifying ssl as the protocol to use.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

Field Summary
 
Fields inherited from interface net.rim.device.api.io.SocketConnectionEnhanced
READ_TIMEOUT
 
Constructor Summary
Category: Signed SSL30Connection(StreamConnection subConnection, String name)
          Creates an instance of the SSL protocol passing in an underlying stream connection and the address you are connecting to.
Category: Signed SSL30Connection(StreamConnection subConnection, String name, boolean startHandshake)
          Creates an instance of the SSL protocol passing in an underlying stream connection and the address you are connecting to.
 
Method Summary
Category: Signed  void close()
          Close the connection.
Category: Signed  void connectionClosed(ConnectionCloseProvider connection)
          Called when a connection is closed.
Category: Signed  boolean connectionStatusAvailable()
          Returns if the connections status is available.
Category: Signed  String getAddress()
          Gets the remote address to which the socket is bound.
Category: Signed  String getLocalAddress()
          Gets the local address to which the socket is bound.
Category: Signed  int getLocalPort()
          Returns the local port to which this socket is bound.
Category: Signed  StreamConnection getParentStream()
          Returns the parent stream if it is available.
Category: Signed  int getPort()
          Returns the remote port to which this socket is bound.
Category: Signed  SecurityInfo getSecurityInfo()
          Return the security information associated with this connection.
Category: Signed  int getSocketOption(byte option)
          Get a socket option for the connection.
Category: Signed  long getSocketOptionEx(short option)
          Get a socket option for this connection.
Category: Signed  boolean isConnectionEstablished()
          Returns if the connection is established or not.
Category: Signed  DataInputStream openDataInputStream()
          Returns a data input stream to use for retrieving data from the TLS stream.
Category: Signed  DataOutputStream openDataOutputStream()
          Returns a data output stream for writing data to the stream securely using TLS.
Category: Signed  InputStream openInputStream()
          Returns the input stream where one would read information from when it is being sent through the protocol.
Category: Signed  OutputStream openOutputStream()
          Returns the output stream to use when sending data using this protocol.
Category: Signed  void setConnectionCloseListener(ConnectionCloseListener listener)
          Sets the current close listener.
Category: Signed  void setSocketOption(byte option, int value)
          Set a socket option for the connection.
Category: Signed  void setSocketOptionEx(short option, long value)
          Set a socket option for this connection.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

SSL30Connection

public SSL30Connection(StreamConnection subConnection,
                       String name)
                throws IOException,
                       TLSException
Creates an instance of the SSL protocol passing in an underlying stream connection and the address you are connecting to. By default, this is MIDP 2.0 compliant in that the handshake is completed immediately.

This creates the protocol and calls connect which will establish the connection with the server using SSL. To use the connection call the getInputStream and getOutputStream methods.

Parameters:
subConnection - An ordered stream connection such as a TCP connection which will provide the underlying transport for this protocol.
name - The URL of the server that was passed into the subConnection constructor or the domain name.
Throws:
IOException - Thrown if an I/O error occurs.
TLSException - Thrown if a TLS error occurs.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

SSL30Connection

public SSL30Connection(StreamConnection subConnection,
                       String name,
                       boolean startHandshake)
                throws IOException,
                       TLSException
Creates an instance of the SSL protocol passing in an underlying stream connection and the address you are connecting to.

This creates the protocol and calls connect which will establish the connection with the server using SSL. To use the connection call the getInputStream and getOutputStream methods.

Parameters:
subConnection - An ordered stream connection such as a TCP connection which will provide the underlying transport for this protocol.
name - The URL of the server that was passed into the subConnection constructor or the domain name.
startHandshake - If this boolean is true, then the handshake will be completed before this function is finished. If it is false, then the handshake is completed when required.
Throws:
IOException - Thrown if an I/O error occurs.
TLSException - Thrown if a TLS error occurs.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0


Method Detail

openInputStream

public InputStream openInputStream()
                            throws IOException
Returns the input stream where one would read information from when it is being sent through the protocol.

Returns:
The InputStream.
Throws:
IOException - Thrown if an I/O error occurs or if the connection is already closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

openDataInputStream

public DataInputStream openDataInputStream()
                                    throws IOException
Returns a data input stream to use for retrieving data from the TLS stream.

Returns:
The DataInputStream.
Throws:
IOException - Thrown if an I/O error occurs or if the connection is already closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

openOutputStream

public OutputStream openOutputStream()
                              throws IOException
Returns the output stream to use when sending data using this protocol.

Returns:
The OutputStream.
Throws:
IOException - Thrown if an I/O error occurs or if the connection is already closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

openDataOutputStream

public DataOutputStream openDataOutputStream()
                                      throws IOException
Returns a data output stream for writing data to the stream securely using TLS.

Returns:
The DataOutputStream.
Throws:
IOException - Thrown if an I/O error occurs or if the connection is already closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

close

public void close()
           throws IOException
Close the connection.

When the connection has been closed access to all methods except this one will cause an an IOException to be thrown.

Closing an already closed connection has no effect. Streams derived from the connection may be open when method is called. Any open streams will cause the connection to be held open until they themselves are closed.

Throws:
IOException - Thrown if an I/O error occurs.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

getSecurityInfo

public SecurityInfo getSecurityInfo()
                             throws IOException
Return the security information associated with this 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 - Thrown if an I/O error occurs or if the connection is already closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

setSocketOption

public void setSocketOption(byte option,
                            int value)
                     throws IllegalArgumentException,
                            IOException
Set a socket option for the connection.

Options inform the low level networking code about intended usage patterns that the application will use in dealing with the socket connection.

Calling setSocketOption to assign buffer sizes is a hint to the platform of the sizes to set the underlying network I/O buffers. Calling getSocketOption can be used to see what sizes the system is using. The system MAY adjust the buffer sizes to account for better throughput available from Maximum Transmission Unit (MTU) and Maximum Segment Size (MSS) data available from current network information.

Parameters:
option - socket option identifier (KEEPALIVE, LINGER, SNDBUF, RCVBUF, or DELAY)
value - numeric value for specified option
Throws:
IllegalArgumentException - if the value is not valid (e.g. negative value) or if the option identifier is not valid
IOException - if the connection was closed
See Also:
SSL30Connection.getSocketOption(byte)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

getSocketOption

public int getSocketOption(byte option)
                    throws IllegalArgumentException,
                           IOException
Get a socket option for the connection.

Parameters:
option - socket option identifier (KEEPALIVE, LINGER, SNDBUF, RCVBUF, or DELAY)
Returns:
numeric value for specified option or -1 if the value is not available.
Throws:
IllegalArgumentException - if the option identifier is not valid
IOException - if the connection was closed
See Also:
SSL30Connection.setSocketOption(byte, int)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

getLocalAddress

public String getLocalAddress()
                       throws IOException
Gets the local address to which the socket is bound.

The host address(IP number) that can be used to connect to this end of the socket connection from an external system. Since IP addresses may be dynamically assigned, a remote application will need to be robust in the face of IP number reasssignment.

The local hostname (if available) can be accessed from System.getProperty("microedition.hostname")

Returns:
the local address to which the socket is bound.
Throws:
IOException - if the connection was closed.
See Also:
ServerSocketConnection
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

getLocalPort

public int getLocalPort()
                 throws IOException
Returns the local port to which this socket is bound.

Returns:
the local port number to which this socket is connected.
Throws:
IOException - if the connection was closed.
See Also:
ServerSocketConnection
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

getAddress

public String getAddress()
                  throws IOException
Gets the remote address to which the socket is bound. The address can be either the remote host name or the IP address(if available).

Returns:
the remote address to which the socket is bound.
Throws:
IOException - if the connection was closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

getPort

public int getPort()
            throws IOException
Returns the remote port to which this socket is bound.

Returns:
the remote port number to which this socket is connected.
Throws:
IOException - if the connection was closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

getParentStream

public StreamConnection getParentStream()
Returns the parent stream if it is available.

Specified by:
getParentStream in interface ParentStreamProvider
Returns:
the parent stream this connection was created with.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.2

connectionStatusAvailable

public boolean connectionStatusAvailable()
Returns if the connections status is available.

Specified by:
connectionStatusAvailable in interface ConnectionCloseProvider
Returns:
True if and only if connection established method returns a valid state.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

isConnectionEstablished

public boolean isConnectionEstablished()
Returns if the connection is established or not.

Specified by:
isConnectionEstablished in interface ConnectionCloseProvider
Returns:
True if and only if the connection is established and not closing.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

setConnectionCloseListener

public void setConnectionCloseListener(ConnectionCloseListener listener)
Sets the current close listener.

Specified by:
setConnectionCloseListener in interface ConnectionCloseProvider
Parameters:
listener - The listener to be notified if this connection closes.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

connectionClosed

public void connectionClosed(ConnectionCloseProvider connection)
Called when a connection is closed.

Specified by:
connectionClosed in interface ConnectionCloseListener
Parameters:
connection - The connection that was closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

setSocketOptionEx

public void setSocketOptionEx(short option,
                              long value)
                       throws IllegalArgumentException,
                              IOException
Set a socket option for this connection. This is a extended API allowing more options to be set than the ones available in javax.microedition.io.

Specified by:
setSocketOptionEx in interface SocketConnectionEnhanced
Parameters:
option - socket option identifier
value - value for specified option
Throws:
IllegalArgumentException - if the value is not valid (e.g. negative value) or if the option identifier is not valid
IOException - if the connection was closed
See Also:
SSL30Connection.getSocketOptionEx(short)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getSocketOptionEx

public long getSocketOptionEx(short option)
                       throws IllegalArgumentException,
                              IOException
Get a socket option for this connection. This is a extended API allowing more options to be queried than the ones available in javax.microedition.io.

Specified by:
getSocketOptionEx in interface SocketConnectionEnhanced
Parameters:
option - socket option identifier
Returns:
numeric value for specified option or -1 if the value is not available.
Throws:
IllegalArgumentException - if the option identifier is not valid
IOException - if the connection was closed
See Also:
SSL30Connection.setSocketOptionEx(short, long)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal