javax.microedition.io
Class Connector

java.lang.Object
  |
  +--javax.microedition.io.Connector

public class Connector
extends Object

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.

Since:
CLDC 1.0

RIM 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:

Wi-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
This protocol opens a StreamConnection to a communication port on the device. The 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 StreamConnection for more information.

socket
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:

  • If deviceside=true is specified in the connection URI, a direct TCP connection is opened from the handheld, without using the BlackBerry MDS Connection Service.
  • If deviceside=false is specified in the connection URI, a proxy TCP connection is opened using the BlackBerry MDS Connection Service.
  • If the deviceside parameter is not specified the behaviour varies by platform: For any BlackBerry on the iDEN network (BlackBerry 6510 Wireless Handheld, BlackBerry 7510, BlackBerry 7520, BlackBerry 7100i), direct TCP is used by default; on all other handhelds, the BlackBerry MDS Connection Service is used by default. If the BlackBerry MDS Connection Service is not available the handheld falls back on direct TCP.
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
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.

You can also set up a secure socket connection over TLS or SSL.

udp
This protocol opens a UDP connection across the wireless network. The open request should be formatted as follows:

  (DatagramConnection) Connector.open("udp://<host>:<dest_port>[;<src_port>]/<apn>[|<type>][;tunnelauthusername=<apn username>;tunnelauthpassword=<apn password>]");
 

where:

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 openInputStream and openOutputStream methods. See DatagramConnection for more information.

sms
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:

For example, to open a standard SMS connection use

 
   Connector.open("sms://");
 

mms
This protocol opens an MMS connection across the wireless network. The open request should be formatted as follows:

  (MessageConnection) Connector.open("mms://[<peer_address>]:[<application_Id>]");
 

where:

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
This protocol opens an HTTP connection across the wireless network. The 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")
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 false.

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 localhost:80 if not specified.

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 HttpConnection for more information.

https
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 false.

Note: If "deviceside=true" is set, end-to-end TLS must be used. If the handheld does not support end-to-end TLS, the connection is closed.

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
EndToEndRequired or EndToEndDesired

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

"EndToEndDesired" specifies that end-to-end TLS/SSL should be used from the handheld to the host server, if the handheld supports this. If the handheld 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.

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 false.

Note: If "deviceside=true" is set, end-to-end TLS must be used. If the handheld does not support end-to-end TLS, the connection is closed.

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
EndToEndRequired or EndToEndDesired

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

"EndToEndDesired" specifies that end-to-end TLS/SSL should be used from the handheld to the host server, if the handheld supports this. If the handheld 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.

n/a

Refer to TLS Connections below for more information.

TLS connections SSL or TLS can be set up in one of two modes:

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.

See Also:
DatagramConnection

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

READ

public static final int READ
Access mode

READ_WRITE

public static final int READ_WRITE
Access mode

WRITE

public static final int WRITE
Access mode
Method Detail

open

public static Connection open(String name)
                       throws IOException
Create and open a Connection
Parameters:
string - The URL for the connection.
Returns:
A new Connection object.
Throws:
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.

open

public static Connection open(String name,
                              int mode)
                       throws IOException
Create and open a Connection
Parameters:
string - The URL for the connection.
mode - The access mode.
Returns:
A new Connection object.
Throws:
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.

open

public static Connection open(String name,
                              int mode,
                              boolean timeouts)
                       throws IOException
Create and open a Connection
Parameters:
string - The URL for the connection
mode - The access mode
timeouts - A flag to indicate that the called wants timeout exceptions
Returns:
A new Connection object
Throws:
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.

openDataInputStream

public static DataInputStream openDataInputStream(String name)
                                           throws IOException
Create and open a connection input stream
Parameters:
string - The URL for the connection.
Returns:
A DataInputStream.
Throws:
IllegalArgumentException - If a parameter is invalid.
ConnectionNotFoundException - If the connection cannot be found.
IOException - If some other kind of I/O error occurs.

openDataOutputStream

public static DataOutputStream openDataOutputStream(String name)
                                             throws IOException
Create and open a connection output stream
Parameters:
string - The URL for the connection.
Returns:
A DataOutputStream.
Throws:
IllegalArgumentException - If a parameter is invalid.
ConnectionNotFoundException - If the connection cannot be found.
IOException - If some other kind of I/O error occurs.

openInputStream

public static InputStream openInputStream(String name)
                                   throws IOException
Create and open a connection input stream
Parameters:
string - The URL for the connection.
Returns:
An InputStream.
Throws:
IllegalArgumentException - If a parameter is invalid.
ConnectionNotFoundException - If the connection cannot be found.
IOException - If some other kind of I/O error occurs.

openOutputStream

public static OutputStream openOutputStream(String name)
                                     throws IOException
Create and open a connection output stream
Parameters:
string - The URL for the connection.
Returns:
An OutputStream.
Throws:
IllegalArgumentException - If a parameter is invalid.
ConnectionNotFoundException - If the connection cannot be found.
IOException - If some other kind of I/O error occurs.



Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.