|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectnet.rim.device.api.io.transport.ConnectionFactory
public class ConnectionFactory
This class enables you to create HTTP, HTTPS, socket, TLS, and SSL 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:
connectionModeis 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).
timeoutSupportedis a boolean flag that indicates if the calling code can handle timeout exceptions. If this flag is set, the protocol implementation may throw anInterruptedIOExceptionwhen 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:
endToEndRequiredspecifies 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.
endToEndDesiredspecifies 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:
timeLimitspecifies 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.
attemptsLimitspecifies 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.
retryFactorcontrols 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.
Connection,
Connector,
ConnectionDescriptor,
WapOptions,
TcpCellularOptions,
TransportInfo,
TransportDescriptor,
ConnectionAttemptListener| 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 |
|---|
public static int ACCESS_READ
public static int ACCESS_WRITE
public static int ACCESS_READ_WRITE
| Constructor Detail |
|---|
public ConnectionFactory()
ConnectionFactory object with default preferences
defaults:
| Method Detail |
|---|
public int getConnectionMode()
public void setConnectionMode(int connectionMode)
connectionMode - the connectionMode to setpublic boolean isTimeoutSupported()
public void setTimeoutSupported(boolean timeoutSupported)
timeoutSupported - the timeoutSupported to set (true or false)public long getConnectionTimeout()
public void setConnectionTimeout(long connectionTimeout)
connectionTimeout - the connectionTimeout to set (in milliseconds)public boolean isEndToEndRequired()
public void setEndToEndRequired(boolean endToEndRequired)
public boolean isEndToEndDesired()
public void setEndToEndDesired(boolean endToEndDesired)
public long getTimeLimit()
public void setTimeLimit(long timeLimit)
timeLimit - a long (milliseconds) in the [10ms, 2 Days] rangepublic int getAttemptsLimit()
public void setAttemptsLimit(int attemptsLimit)
attemptsLimit - public long getRetryFactor()
public void setRetryFactor(long retryFactor)
retryFactor - a number in the range: [500ms, 4hrs] expressed in milliseconds.public ConnectionAttemptListener getConnectionAttemptListener()
ConnectionAttemptListener is set
ConnectionAttemptListener if set; null otherwise.public void setConnectionAttemptListener(ConnectionAttemptListener connectionAttemptListener)
ConnectionAttemptListener for the factory.
connectionAttemptListener - the connectionAttemptListener to setpublic TransportTypeOptions getTransportTypeOptions(int transportType)
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
public void setTransportTypeOptions(int transportType,
TransportTypeOptions options)
transportType - One of the TRANSPORT_* defined on @link TransporTypeoptions - an object of the proper subclass of TransportTypeOptions.- Since:
- BlackBerry API 5.0.0
public int[] getPreferredTransportTypes()
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.public void setPreferredTransportTypes(int[] preferredTransportTypes)
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.public int[] getDisallowedTransportTypes()
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.public void setDisallowedTransportTypes(int[] disallowedTransportTypes)
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.public ConnectionDescriptor getConnection(String url)
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://, or ssl://.
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.
url - A URL with one of the following formats:
ConnectionDescriptor if a connection can be established; null otherwise
public ConnectionDescriptor getConnection(String url,
int transportType,
String ConnectionUID)
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.
The url must start with http://, https://, socket://, tls://, or ssl://.
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.
url - A URL with one of the following formats:
transportType - One of the TRANSPORT_* defined on @link TransporTypeConnectionUID - 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
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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.