javax.microedition.io.Connector
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public class Connector
Factory class for creating new Connection objects.
The creation of Connections is performed dynamically by looking up
a protocol implementation class whose name is formed from the platform
name (read from a system property) and the protocol name of the
requested connection (extracted from the parameter string supplied
by the application programmer.) The parameter string that describes
the target should conform to the URL format as described in RFC 2396.
This takes the general form:
{scheme}:[{target}][{parms}]
where {scheme} is the name of a protocol such as http.
The {target} is normally some kind of network address.
Any {parms} are formed as a series of equates of the form ";x=y". Example: ";type=a".
An optional second parameter may be specified to the open function. This is a mode 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 (READ), written (WRITE), or both (READ_WRITE). The validity of these flag settings is protocol dependent. For instance, a connection for a printer would not allow read access, and would throw an IllegalArgumentException. If the mode parameter is not specified, READ_WRITE is used by default.
An optional third parameter 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.
Because connections are frequently opened just to gain access to a specific input or output stream, four convenience functions are provided for this purpose.
DatagramConnectionRIM Implementation Notes
Platform specific behaviour with opening connections
On some RIM devices, if your application listens for incoming push
connections using a StreamConnectionNotifier, you must append the
"deviceside=false" parameter after the URL connection
string. Without this parameter, the StreamConnectionNotifier returns
null.
Blocking Operations
If you use Connector.open() to implement a javax.microedition.io interface,
make sure an application uses the implementation to open a connection from
within a non-main event thread. If an application runs the connection from within the
main event thread, the application will lock.
The following interfaces perform blocking operations:
CommConnectionConnectionContentConnectionDatagramDatagramConnectionHttpConnectionHttpsConnectionInputConnectionjavax.microedition.io.MulticastDatagramConnectionOutputConnectionSecureConnectionSecurityInfoServerSocketConnectionSocketConnectionStreamConnectionStreamConnectionNotifierUDPDatagramConnectionWi-Fi Support
Wi-Fi connection can be established by setting the interface parameter. This only works with direct TCP/UDP connections.
Protocol support
This implementation of the Connector class currently supports the following
protocols:
comm
open request should be formatted as follows:
(StreamConnection) Connector.open("comm:<portidentifier>[<optional parameters>]");
The first parameter must be a port identifier. Currently the only port
identifiers supported are COM1 and USB.
Any additional parameters must be separated by a semi-colon (;) and spaces are not allowed in the string. If a particular optional parameter is not applicable to a particular port, the parameter may be ignored.
| Parameter | Description | Default |
baudrate |
The speed of the port. | 19200 |
bitsperchar |
The number bits per character(7 or 8). |
8 |
stopbits |
the number of stop bits per char(1 or 2) |
1 |
parity |
The parity can be odd, even,
or none. |
none |
channel |
The USB channel name to register and open. | n/a |
When opening a StreamConnection to the USB port, the channel
must be specified.
See socketStreamConnection for more information.
This protocol opens a socket connection across the wireless network. The
open request should be formatted as follows:
(StreamConnection) Connector.open("socket://<host>:<port>/<path>[<optional parameters>]");
Any optional parameters must be separated by a semi-colon (;) and spaces are not allowed in the string.
|
Parameter |
Description |
Default |
deviceside
|
Specifies whether the connection is to be made via direct TCP or proxy TCP.
Can be true or false:
|
false
|
interface
|
If the interface=wifi parameter is appended to the end of the
URI string value, a Wi-Fi socket connection is opened.
|
n/a |
ConnectionUID
|
The UID of the service record for the WAP 2.0 gateway through which to connect. WPTCP is the CID of
this service record. You can use the ServiceBook class to search for it by its CID.
Useful only if a direct TCP connection is made by specifying deviceside=true.
|
n/a |
apn
|
The APN over which the connection will be made. Useful only if a direct TCP connection is made. | n/a |
TunnelAuthUsername
|
The user name to use to connect to the APN. Useful only if a direct TCP connection is made and an APN is specified. May be omitted if not required by the specified APN. | n/a |
TunnelAuthPassword
|
The password to use to connect to the APN. Useful only if a direct TCP connection is made and an APN is specified. May be omitted if not required by the specified APN. | n/a |
Note: The handheld's user can select the default TCP connection behaviour as
well as default APN settings; you can override this behaviour with the deviceside,
apn, tunnelauthusername, and tunnelauthpassword parameters.
The following code demonstrates how to open a direct TCP connection through a specific APN from the handheld:
conn=(StreamConnection)Connector.open("socket://testserver:600;deviceside=true;apn=<apn name>;tunnelauthusername=<apn username>;tunnelauthpassword=<apn password>");
Input and output stream can then be acquired using the
openInputStream() and openOutputStream() methods.
See StreamConnection for more information.
When closing the connection it has be closed from the same Application as it was opened with.
You can also set up a secure socket connection over TLS or SSL.
datagram
This protocol opens a UDP connection or a multicast datagram connection across the wireless network. The
open request should be formatted as follows:
(DatagramConnection) Connector.open("datagram://<host>:<dest_port>[;<src_port>]/<apn>[|<type>][;tunnelauthusername=<apn username>;tunnelauthpassword=<apn password>]");
(MulticastDatagramConnection) Connector.open("datagram://<host>:<dest_port>[;<src_port>]/<apn>[|<type>][;tunnelauthusername=<apn username>;tunnelauthpassword=<apn password>]");
where:
host is the host address in dotted ASCII-decimal format. Host address can be specified in FQDN format or as an IP address
dest_port is the port to send to at the host address (optional for receiving)
src_port is the local source port (optional)
apn is the network APN in string format
type specifies the connection type (UDP)
apn username is the APN authentication username in string format (optional if APN requires authentication)
apn password is the APN authentication password in string format (optional if APN requires authentication)
dest_port must be specified in order to send data
on this connection. If src_port is not specified then it is set
to the same value as dest_port by default.
If the connection is to be used to receive data then
src_port must be specified. dest_port can
be excluded on inbound connections allowing the connection to receive
datagrams from all destination ports.
Note: When testing your applications within the RIM Simulator, you must use the following command line switch to open a port for listening:
/data-port=<src_port>
If you attempt to send a datagram on a UDP connection and you are not
listening on src_port then an IOException will be thrown.
Note: The handheld's user can select the default UDP connection behaviour; you can override ths behaviour with the previous described parameters.
Input and output streams can be acquired using the
smsopenInputStream and openOutputStream methods.
See DatagramConnection for more information.
This protocol opens an SMS connection across the wireless network. The
open request should be formatted as follows:
(MessageConnection) Connector.open("sms://[<peer_address>]:[<port>]");
where:
<peer_address> is the MSISDN of the sender or
recipient.
<port> is the port number part of the application port
number address as specified in the GSM 3.40 SMS specification [1] (sections
9.2.3.24.3 and 9.2.3.24.4). The same mechanism is used, for example, for the
WAP WDP messages.
For example, to open a standard SMS connection use
Connector.open("sms://");
mms
open request should be formatted as follows:
(MessageConnection) Connector.open("mms://[<peer_address>]:[<application_Id>]");
where:
<peer_address> is the phone number or the email address of
recipient.
<application_Id> is used to identify a Java application.
For example, to send a mms message to specific application use
Connector.open("mms://+123456789:applicationID");
To open a server mode MessageConnection use
Connector.open("mms://:applicationID");
http
open request should be formatted as follows:
(HttpConnection) Connector.open("http://<host>:<port>/<path>[<optional parameters>]");
Any optional parameters must be separated by a semi-colon (;) and spaces are not allowed in the string.
|
Parameter |
Description |
Default |
TunnelAuthPassword
| Password for APN session. | n/a |
TunnelAuthUsername
| User name for APN session. | n/a |
WapEnableWTLS
|
This parameter overrides the default mechanism of using WTLS on the device. if this parameter is not added to the parameter list, then the WAP http stack will load the WTLS based on the WAP gateway port number. 9203 is used as the secure port number of the WAP gateways. If this parameter is added to the list, and is true, then WTLS gets loaded; if the parameter is added to the list, and is false, then WTLS is not loaded. |
n/a |
WapGatewayIP
|
IP address of gateway. |
n/a |
WapGatewayPort
| Gateway port value. | WAP_GATEWAY_PORT_DEFAULT (9201)
|
WapSourceIP
| IP address of source. | WAP_SOURCE_IP_DEFAULT ("127.0.0.1")
|
WapSourcePort
| Source port value. | WAP_SOURCE_PORT_DEFAULT (8205)
|
WapGatewayAPN
| WAP Gateway Access Point Name | WAP_GATEWAY_APN_DEFAULT ("rim.net.gprs")
|
ConnectionUID
|
The UID of the service record for the WAP 2.0 gateway through which to connect. WPTCP is the CID of
this service record. You can use the ServiceBook class to search for it by its CID.
Useful only if a direct TCP connection is made by specifying deviceside=true.
|
n/a |
deviceside
|
To specify that the underlying TCP connection should be opened directly from the handheld, set this parameter to "true". Specify "deviceside=false" when receiving or sending data through the BlackBerry MDS Connection Service. |
The default is |
interface
|
If the interface=wifi parameter is appended to the end of the
URI string value, a Wi-Fi HTTP connection is opened.
|
n/a |
no parameters
|
If you don't provide any parameters to the open request, the behaviour varies with the host network. |
GPRS/CDMA: use corporate MDS connection. If no corporate MDS service record is present, then the handheld will attempt to connect directly to the network. iDEN: Use direct TCP connection to specified host and
port. Default of |
Note: When testing your applications within the RIM Simulator, you must use the following command line switch with it (either on its own, or from your IDE):
/data-port=<wap source port>
Typically, you can use the default WAP_SOURCE_PORT_DEFAULT
(0x200D); however, if you're using a different source port, ensure
that you adjust the simulator's starting parameter accordingly.
See httpsHttpConnection for more information.
This protocol opens a secure HTTP connection over TLS. The open
request should be formatted as follows:
(HttpConnection) Connector.open("https://<host>:<port>/<path>[<optional parameters>]");
One of the following optional parameters can be specified:
| Parameter | Description | Default |
deviceside
|
To specify that the underlying TCP connection should be opened directly from the handheld, set this parameter to "true". Specify "deviceside=false" when receiving or sending data through the BlackBerry MDS Connection Service. |
The default is Note: If |
interface
|
If the interface=wifi parameter is appended to the end of the
URI string value, a Wi-Fi HTTPS connection is opened.
|
n/a |
WapGatewayAPN
| WAP Gateway Access Point Name | WAP_GATEWAY_APN_DEFAULT ("rim.net.gprs")
|
ConnectionUID
|
The UID of the service record for the WAP 2.0 gateway through which to connect. WPTCP is the CID of
this service record. You can use the ServiceBook class to search for it by its CID.
Useful only if a direct TCP connection is made by specifying deviceside=true.
|
n/a |
EndToEndRequired or EndToEndDesired
|
| n/a |
Refer to TLS Connections below more information.
tls or ssl
This protocol opens a socket-layer connection over TLS or SSL.
The open request should be formatted as follows:
Connector.open("tls://<host>:<port>/<path>[<optional parameters>]");
or
Connector.open("ssl://<host>:<port>/<path>[<optional parameters>]");
The following optional parameters can be specified:
| Parameter | Description | Default |
deviceside
|
To specify that the underlying TCP connection should be opened directly from the handheld, set this parameter to "true". Specify "deviceside=false" when receiving or sending data through the BlackBerry MDS Connection Service. |
The default is Note: If |
interface
|
If the interface=wifi parameter is appended to the end of the
URI string value, a Wi-Fi tls or ssl connection is opened.
|
n/a |
WapGatewayAPN
| WAP Gateway Access Point Name | WAP_GATEWAY_APN_DEFAULT ("rim.net.gprs")
|
ConnectionUID
|
The UID of the service record for the WAP 2.0 gateway through which to connect. WPTCP is the CID of
this service record. You can use the ServiceBook class to search for it by its CID.
Useful only if a direct TCP connection is made by specifying deviceside=true.
|
n/a |
EndToEndRequired or EndToEndDesired
|
|
n/a |
Refer to TLS Connections below for more
information.
TLS connections
Proxy mode
The Mobile Data Service (MDS) feature of the BlackBerry Enterprise Server
sets up TLS/SSL on behalf of the handheld. Communication over the Internet
between the BlackBerry Enterprise Server and the web server is encrypted
using TLS. Communication over the wireless network between the handheld and
BlackBerry Enterprise Server is not encrypted using TLS/SSL, but is still
TripleDES-encrypted. TLS data is decrypted at the MDS and re-encrypted using
TripleDES. There is a point at the MDS (behind the corporate firewall) when
data is not encrypted.
End-to-end mode
Data is TLS-encrypted for the entire connection between the handheld and the
web server. Data is not decrypted at the MDS. End-to-end mode is appropriate
when only the endpoints of the transaction are trusted (for example, with
banking services). Network access is slower than in proxy mode because the
handheld must set up the TLS connection.
Users can set an option to use proxy or end-to-end mode by default for
TLS connections. Applications can also specify end-to-end mode when opening a
connection, as explained in
https and tls or ssl above.
Bluetooth Serial Port Profile (BTSPP)
A Bluetooth Serial Port connection can be instantiated as either a client or a server. In the typical framework,
clients initiate connections whereas a server will accept client connections.
Client Connections
Before a SPP client can establish a connection to an SPP service, it must discover that service via
service discovery. This is done using the BluetoothSerialPortInfo class by retrieving the current serial port
connections available to the handheld. A client connection URL includes the Bluetooth device address of the
server and the server channel identifier for the service. Invoking the Connector.open() method with an SPP client
connection returns a SocketConnection object that represents a client-side SPP connection.
For example
SocketConnection conn = (SocketConnection)Connector.open( "btspp://0050C000321B:5" );
where 0050C000321B is the device address and 5 is the channel identifier.
Server Connections
To establish a SPP server connection on the handheld using the Connector.open() method
is straight forward. For example
ServerSocketConnection conn = (ServerSocketConnection)Connector.open( "btspp://localhost:00112233445566778899AABBCCDDEEFF;name=SSPEx" );
SocketConnection socket = (SocketConnection)conn.acceptAndOpen();
In the example, localhost indicates that this is a server connection. In addition, the host part can be left blank to provide the same effect. The UUID in this case is 00112233445566778899AABBCCDDEEFF which is the 128 bit UUID to be stored in the SDP record. Finally, the name indicates the name to be stored in the SDP record. Note that the name is optional.
| Field Summary | ||
|---|---|---|
static int |
READ
Access mode |
|
static int |
READ_WRITE
Access mode |
|
static int |
WRITE
Access mode |
|
| Method Summary | ||
|---|---|---|
static Connection |
open(String name)
Create and open a Connection |
|
static Connection |
open(String name,
int mode)
Create and open a Connection |
|
static Connection |
open(String name,
int mode,
boolean timeouts)
Create and open a Connection |
|
static DataInputStream |
openDataInputStream(String name)
Create and open a connection input stream |
|
static DataOutputStream |
openDataOutputStream(String name)
Create and open a connection output stream |
|
static InputStream |
openInputStream(String name)
Create and open a connection input stream |
|
static OutputStream |
openOutputStream(String name)
Create and open a connection output stream |
|
| Methods inherited from class java.lang.Object |
|---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static final int READ
public static final int WRITE
public static final int READ_WRITE
| Method Detail |
|---|
public static Connection open(String name)
throws IOException
string - The URL for the connection.
IllegalArgumentException - If a parameter is invalid.
ConnectionNotFoundException - If the connection cannot be found.
ControlledAccessException - if the firewall disallows a btspp or
comm connection (both btspp and comm connections are allowed by default).
IOException - if the firewall disallows a connection that is not btspp or comm.
public static Connection open(String name,
int mode)
throws IOException
string - The URL for the connection.mode - The access mode.
IllegalArgumentException - If a parameter is invalid.
ConnectionNotFoundException - If the connection cannot be found.
ControlledAccessException - if the firewall disallows a btspp or
comm connection (both btspp and comm connections are allowed by default).
IOException - if the firewall disallows a connection that is not btspp or comm.
public static Connection open(String name,
int mode,
boolean timeouts)
throws IOException
string - The URL for the connectionmode - The access modetimeouts - A flag to indicate that the caller wants timeout exceptions
IllegalArgumentException - If a parameter is invalid.
ConnectionNotFoundException - If the connection cannot be found.
ControlledAccessException - if the firewall disallows a btspp or
comm connection (both btspp and comm connections are allowed by default).
IOException - if the firewall disallows a connection that is not btspp or comm.
public static DataInputStream openDataInputStream(String name)
throws IOException
string - The URL for the connection.
IllegalArgumentException - If a parameter is invalid.
ConnectionNotFoundException - If the connection cannot be found.
IOException - If some other kind of I/O error occurs.
public static DataOutputStream openDataOutputStream(String name)
throws IOException
string - The URL for the connection.
IllegalArgumentException - If a parameter is invalid.
ConnectionNotFoundException - If the connection cannot be found.
IOException - If some other kind of I/O error occurs.
public static InputStream openInputStream(String name)
throws IOException
string - The URL for the connection.
IllegalArgumentException - If a parameter is invalid.
ConnectionNotFoundException - If the connection cannot be found.
IOException - If some other kind of I/O error occurs.
public static OutputStream openOutputStream(String name)
throws IOException
string - The URL for the connection.
IllegalArgumentException - If a parameter is invalid.
ConnectionNotFoundException - If the connection cannot be found.
IOException - If some other kind of I/O error occurs.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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