net.rim.device.api.io.transport
Class ConnectionFactory

java.lang.Object
  extended by net.rim.device.api.io.transport.ConnectionFactory

public class ConnectionFactory
extends Object

This class enables you to create HTTP, HTTPS, socket, TLS, SSL and datagram (unicast) connections over supported transports.

This class is not thread-safe and the getConnection() method blocks. So you should not call these methods from the main event thread of an application.

You can configure preferred transport types by using ConnectionFactory.setPreferredTransportTypes(int[]). You can prohibit transport types by using ConnectionFactory.setDisallowedTransportTypes(int[]). You can customize the factory by setting specific options to use for the TCP Cellular, WAP, and BisB transports.

The characteristics of the returned connections can be specified by overwriting the following variables:

connectionMode is a flag that indicates to the protocol handler the intentions of the calling code. The options here specify if the connection is going to be read (ACCESS_READ), written (ACCESS_WRITE), or both (ACCESS_READ_WRITE).

timeoutSupported is a boolean flag that indicates if the calling code can handle timeout exceptions. If this flag is set, the protocol implementation may throw an InterruptedIOException when it detects a timeout condition. This flag is only a hint to the protocol handler, and it does not guarantee that such exceptions will actually be thrown. If this parameter is not set, no timeout exceptions will be thrown.

HTTPS and SSL/TLS connections can be customized by setting the following variables:

endToEndRequired specifies that end-to-end TLS/SSL must be used from the device to the host server. If the device does not support TLS/SSL, the connection is closed.

endToEndDesired specifies that end-to-end TLS/SSL should be used from the device to the host server, if the device supports this. If the device does not support end-to-end TLS/SSL, and the user permits proxy TLS, then a proxy TLS connection is set up using the Mobile Data Service.

You can customize retry attempts by setting the following properties:

timeLimit specifies the maximum duration in milliseconds during which the factory will attempt to create a connection. The default value is 15 minutes. Valid values range from 10 msec to 2 days.

attemptsLimit specifies the maximum number of times the factory will attempt to create a connection. The default value is 1. Valid values range from 1 to 500.

retryFactor controls the delay, in milliseconds, between retries according to the following formula: delay = ( 2 << attempt - 2) * retryFactor where attempt is the serial number of the attempt
Defaults to 1000 resulting in retries at: 2, 4, 8, 16, 32,..... seconds.
Can be set anywhere in the 500msec, 4hrs range.

Note: WAP 1.x doesn't support socket, TLS or SSL connections. If such a combination is specified, null will be returned and if a ConnectionAttemptListener is defined for the factory, it will be notified with a NoAvailableTransportException.

See Also:
Connection, Connector, ConnectionDescriptor, WapOptions, TcpCellularOptions, TransportInfo, TransportDescriptor, ConnectionAttemptListener
Since:
BlackBerry API 5.0.0

Field Summary
static int ACCESS_READ
          Access mode
static int ACCESS_READ_WRITE
          Access mode
static int ACCESS_WRITE
          Access mode
 
Constructor Summary
ConnectionFactory()
          Creates a ConnectionFactory object with default preferences
defaults: connectionMode: ACCESS_READ_WRITE timeoutSupported: false endToEndRequiered: false endToEndDesired: false timeLimit: 1 DAY attemptsLimit: 1 retryFactor: 1000
 
Method Summary
 int getAttemptsLimit()
          Retrieves the maximum number of attempts the factory will make to create a connection
 ConnectionDescriptor getConnection(String url)
          Creates a Connection to the specified url using the first available transport type from the array of preferred transport types if defined, or from the available transport types if no preferences were set.
 ConnectionDescriptor getConnection(String url, int transportType, String ConnectionUID)
          Creates a Connection to the specified url over a the specified transport type and using the specified ConnectionUID.
 ConnectionAttemptListener getConnectionAttemptListener()
          Retrieves the ConnectionAttemptListener is set
 int getConnectionMode()
          Retrieves the connectionMode
 long getConnectionTimeout()
          Retrieves the connectionTimeout
 int[] getDisallowedTransportTypes()
          Retrieves the set of disallowed transport types (if defined) used by the factory when attempting to get a connection.
 int[] getPreferredTransportTypes()
          Retrieves the set of preferred transport types used by the factory when attempting to get a connection.
 long getRetryFactor()
          Retrieves the retryFactor that controls the delay (in milliseconds) between retries according to the following formula:
delay = ( 2 << attempt - 2) * retryFactor where attempt is the serial number of the attempt
 long getTimeLimit()
          Retrieves the maximum time the factory will try to create a connection
 TransportTypeOptions getTransportTypeOptions(int transportType)
          Retrieves the options that the factory is using (if any) for the specified transport type.
 boolean isEndToEndDesired()
          Retrieves the endToEndDesired
 boolean isEndToEndRequired()
          Retrieves the endToEndRequired
 boolean isTimeoutSupported()
          Retrieves the timeoutSupported
 void setAttemptsLimit(int attemptsLimit)
          Sets the maximum number of attempts the factory will make to create a connection.
 void setConnectionAttemptListener(ConnectionAttemptListener connectionAttemptListener)
          Sets the ConnectionAttemptListener for the factory.
 void setConnectionMode(int connectionMode)
          Sets the connectionMode to the desired value
 void setConnectionTimeout(long connectionTimeout)
          Sets connectionTimeout to the desired value
 void setDisallowedTransportTypes(int[] disallowedTransportTypes)
          Sets the disallowed transport types used by the factory when attempting to get a connection.
 void setEndToEndDesired(boolean endToEndDesired)
          Sets the endToEndDesired to the desired value
 void setEndToEndRequired(boolean endToEndRequired)
          Sets the endToEndRequired to the desired value
 void setPreferredTransportTypes(int[] preferredTransportTypes)
          Sets the preferred transport types used by the factory when attempting to get a connection.
 void setRetryFactor(long retryFactor)
          Retrieves the retryFactor that controls the delay (in milliseconds) between retries according to the following formula:
delay = ( 2 << attempt - 2) * retryFactor where attempt is the serial number of the attempt
Valid range: [500ms, 4hrs]
 void setTimeLimit(long timeLimit)
          Sets the maximum time the factory will try to create a connection
 void setTimeoutSupported(boolean timeoutSupported)
          Sets timeoutSupported to the desired value
 void setTransportTypeOptions(int transportType, TransportTypeOptions options)
          Sets the options that the factory will use when creating connections over the specified transport type.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

ACCESS_READ

public static int ACCESS_READ
Access mode

Since:
BlackBerry API 5.0.0

ACCESS_WRITE

public static int ACCESS_WRITE
Access mode

Since:
BlackBerry API 5.0.0

ACCESS_READ_WRITE

public static int ACCESS_READ_WRITE
Access mode

Since:
BlackBerry API 5.0.0


Constructor Detail

ConnectionFactory

public ConnectionFactory()
Creates a ConnectionFactory object with default preferences

defaults:

  • connectionMode: ACCESS_READ_WRITE
  • timeoutSupported: false
  • endToEndRequiered: false
  • endToEndDesired: false
  • timeLimit: 1 DAY
  • attemptsLimit: 1
  • retryFactor: 1000
  • Since:
    BlackBerry API 5.0.0


    Method Detail

    getConnectionMode

    public int getConnectionMode()
    Retrieves the connectionMode

    Returns:
    the connectionMode
    Since:
    BlackBerry API 5.0.0

    setConnectionMode

    public void setConnectionMode(int connectionMode)
    Sets the connectionMode to the desired value

    Parameters:
    connectionMode - the connectionMode to set
    Since:
    BlackBerry API 5.0.0

    isTimeoutSupported

    public boolean isTimeoutSupported()
    Retrieves the timeoutSupported

    Returns:
    the timeoutSupported
    Since:
    BlackBerry API 5.0.0

    setTimeoutSupported

    public void setTimeoutSupported(boolean timeoutSupported)
    Sets timeoutSupported to the desired value

    Parameters:
    timeoutSupported - the timeoutSupported to set (true or false)
    Since:
    BlackBerry API 5.0.0

    getConnectionTimeout

    public long getConnectionTimeout()
    Retrieves the connectionTimeout

    Returns:
    the connectionTimeout
    Since:
    BlackBerry API 5.0.0

    setConnectionTimeout

    public void setConnectionTimeout(long connectionTimeout)
    Sets connectionTimeout to the desired value

    Parameters:
    connectionTimeout - the connectionTimeout to set (in milliseconds)
    Since:
    BlackBerry API 5.0.0

    isEndToEndRequired

    public boolean isEndToEndRequired()
    Retrieves the endToEndRequired

    Returns:
    the endToEndRequired
    Since:
    BlackBerry API 5.0.0

    setEndToEndRequired

    public void setEndToEndRequired(boolean endToEndRequired)
    Sets the endToEndRequired to the desired value

    Since:
    BlackBerry API 5.0.0

    isEndToEndDesired

    public boolean isEndToEndDesired()
    Retrieves the endToEndDesired

    Returns:
    the endToEndDesired
    Since:
    BlackBerry API 5.0.0

    setEndToEndDesired

    public void setEndToEndDesired(boolean endToEndDesired)
    Sets the endToEndDesired to the desired value

    Since:
    BlackBerry API 5.0.0

    getTimeLimit

    public long getTimeLimit()
    Retrieves the maximum time the factory will try to create a connection

    Returns:
    the maximum time the factory will try to create a connection.
    Since:
    BlackBerry API 5.0.0

    setTimeLimit

    public void setTimeLimit(long timeLimit)
    Sets the maximum time the factory will try to create a connection

    Parameters:
    timeLimit - a long (milliseconds) in the [10ms, 2 Days] range
    Since:
    BlackBerry API 5.0.0

    getAttemptsLimit

    public int getAttemptsLimit()
    Retrieves the maximum number of attempts the factory will make to create a connection

    Since:
    BlackBerry API 5.0.0

    setAttemptsLimit

    public void setAttemptsLimit(int attemptsLimit)
    Sets the maximum number of attempts the factory will make to create a connection. The valid range is [1, 500]

    Parameters:
    attemptsLimit -
    Since:
    BlackBerry API 5.0.0

    getRetryFactor

    public long getRetryFactor()
    Retrieves the retryFactor that controls the delay (in milliseconds) between retries according to the following formula:
    delay = ( 2 << attempt - 2) * retryFactor where attempt is the serial number of the attempt

    Returns:
    a number in the range: [500ms, 4hrs] expressed in milliseconds.
    Since:
    BlackBerry API 5.0.0

    setRetryFactor

    public void setRetryFactor(long retryFactor)
    Retrieves the retryFactor that controls the delay (in milliseconds) between retries according to the following formula:
    delay = ( 2 << attempt - 2) * retryFactor where attempt is the serial number of the attempt
    Valid range: [500ms, 4hrs]

    Parameters:
    retryFactor - a number in the range: [500ms, 4hrs] expressed in milliseconds.
    Since:
    BlackBerry API 5.0.0

    getConnectionAttemptListener

    public ConnectionAttemptListener getConnectionAttemptListener()
    Retrieves the ConnectionAttemptListener is set

    Returns:
    the connectionAttemptListener a ConnectionAttemptListener if set; null otherwise.
    Since:
    BlackBerry API 5.0.0

    setConnectionAttemptListener

    public void setConnectionAttemptListener(ConnectionAttemptListener connectionAttemptListener)
    Sets the ConnectionAttemptListener for the factory.

    Parameters:
    connectionAttemptListener - the connectionAttemptListener to set
    Since:
    BlackBerry API 5.0.0

    getTransportTypeOptions

    public TransportTypeOptions getTransportTypeOptions(int transportType)
    Retrieves the options that the factory is using (if any) for the specified transport type.

    Parameters:
    transportType - One of the TRANSPORT_* defined on @link TransporType
    Returns:
    a subclass of TransportTypeOptions if options have been set for the specified transport type, or null otherwise.
    Since:
    BlackBerry API 5.0.0

    setTransportTypeOptions

    public void setTransportTypeOptions(int transportType,
                                        TransportTypeOptions options)
    Sets the options that the factory will use when creating connections over the specified transport type.

    Parameters:
    transportType - One of the TRANSPORT_* defined on @link TransporType
    options - an object of the proper subclass of TransportTypeOptions.
    Since:
    BlackBerry API 5.0.0

    getPreferredTransportTypes

    public int[] getPreferredTransportTypes()
    Retrieves the set of preferred transport types used by the factory when attempting to get a connection. Note that the transport types are tried in the natural order of the array.

    Returns:
    an array of TRANSPORT_* constants defined on TransportInfo that represents the preferred transport types to be used by the factory for creating connections. If no preference has been set, null is returned.
    Since:
    BlackBerry API 5.0.0

    setPreferredTransportTypes

    public void setPreferredTransportTypes(int[] preferredTransportTypes)
    Sets the preferred transport types used by the factory when attempting to get a connection. Note that the transport types are tried in the natural order of the array.

    Parameters:
    preferredTransportTypes - an array of TRANSPORT_* constants as defined on TransportInfo that represents the preferred transport types to be used by the factory for creating connections. null can be used to indicate no preference so all available transport types are used.
    Since:
    BlackBerry API 5.0.0

    getDisallowedTransportTypes

    public int[] getDisallowedTransportTypes()
    Retrieves the set of disallowed transport types (if defined) used by the factory when attempting to get a connection.

    Returns:
    an array of TRANSPORT_* constants defined on TransportInfo that represents the transport types that should not be considered by the factory for creating connections. If no transport type has been disallowed, null is returned.
    Since:
    BlackBerry API 5.0.0

    setDisallowedTransportTypes

    public void setDisallowedTransportTypes(int[] disallowedTransportTypes)
    Sets the disallowed transport types used by the factory when attempting to get a connection. The transport types in the set will not be considered as candidates when creating connections.

    Parameters:
    disallowedTransportTypes - an array of TRANSPORT_* constants as defined on TransportInfo that represents the transport types to be ignored by the factory for creating connections. null can be used to indicate no transport type is disallowed.
    Since:
    BlackBerry API 5.0.0

    getConnection

    public ConnectionDescriptor getConnection(String url)
    Creates a Connection to the specified url using the first available transport type from the array of preferred transport types if defined, or from the available transport types if no preferences were set. The url must start with http://, https://, socket://, tls://, ssl:// or udp:// or datagram://. The connection object returned is wrapped in a ConnectionDescriptor that can be queried to find out which transport the connection was opened on. If no connection can be obtained, null is returned.

    Note: WAP 1.x doesn't support socket://, tls://, or ssl:// connections. If the URL contains one of these protocol specifiers, WAP 1.x will never be attempted.

    Note: WAP 1.x, WAP2, MDS and BIS_B do not support udp:// or datagram:// connections. If any such combination is specified, null will be returned and if a ConnectionAttemptListener is defined for the factory, it will be notified with a NoAvailableTransportException.

    Parameters:
    url - A URL with one of the following formats:
  • http://<host>:<port>/<path>[<optional parameters>]
  • https://<host>:<port>/<path>[<optional parameters>]
  • socket://<host>:<port>/<path>
  • tls://<host>:<port>/<path>
  • ssl://<host>:<port>/<path>
  • udp://<host>:<dest_port>[;<src_port>]
  • datagram://<host>:<dest_port>[;<src_port>]
  • Returns:
    a ConnectionDescriptor if a connection can be established; null otherwise
    Since:
    BlackBerry API 5.0.0

    getConnection

    public ConnectionDescriptor getConnection(String url,
                                              int transportType,
                                              String ConnectionUID)
    Creates a Connection to the specified url over a the specified transport type and using the specified ConnectionUID. If ConnectionUID is null the available transports of the specified type will be tried in all cases except TCP Cellular. In the TCP Cellular case, if the ConnectionUID is null, then a check is made to see if TcpCellularOptions have been set on the ConnectionFactory. If the TcpCellularOptions have been set, then a connection is attempted using only the transport associated with these options. If the TcpCellularOptions have not been set, then a connection is attempted using all the TCP Cellular transports The url must start with http://, https://, socket://, tls://, ssl:// or udp:// or datagram://. The connection object returned is wrapped in a ConnectionDescriptor that can be queried to find out which transport the connection was opened on. If no connection can be obtained, null is returned.

    Note: WAP 1.x doesn't support socket://, tls://, or ssl:// connections. If such a combination is specified, null will be returned and if a ConnectionAttemptListener is defined for the factory, it will be notified with a NoAvailableTransportException.

    Note: WAP 1.x, WAP2, MDS and BIS_B do not support udp:// or datagram:// connections. If any such combination is specified, null will be returned and if a ConnectionAttemptListener is defined for the factory, it will be notified with a NoAvailableTransportException.

    Parameters:
    url - A URL with one of the following formats:
  • http://<host>:<port>/<path>[<optional parameters>]
  • https://<host>:<port>/<path>[<optional parameters>]
  • socket://<host>:<port>/<path>
  • tls://<host>:<port>/<path>
  • ssl://<host>:<port>/<path>
  • udp://<host>:<dest_port>[;<src_port>]
  • datagram://<host>:<dest_port>[;<src_port>]
  • transportType - One of the TRANSPORT_* defined on @link TransporType
    ConnectionUID - The UID of the ServiceRecord for a specific transport instance
    Returns:
    a ConnectionDescriptor if a connection can be established; null otherwise
    Since:
    BlackBerry API 5.0.0





    Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
    Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
    Copyright 2002-2003 Nokia Corporation All Rights Reserved.
    Java is a trademark of Sun Microsystems, Inc.