javax.microedition.io
Class Connector

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

public class Connector

extends Object

This class is a factory used to create all the connection objects.

This is done by dynamically looking up a class the name of which is formed from the platform name and the protocol of the requested connection. The parameter string describing the target conforms 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, but protocols may regard this as a fairly flexible field when the connection is not network oriented.

Any {parms} are formed as a series of equates on the form ";x=y" such as ;type=a.

An optional second parameter may be specified to the open function. The is a mode flag that indicated to the protocol handler the intentions of the calling code. The options here are to 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 this was attempted. Omitting this parameter results in READ_WRITE being used by default.

An optional third parameter is a boolean flag to indicate if the calling code has been written in such a way as to handle timeout exceptions. If this is selected the protocol may throw an InterruptedIOException when it detects a timeout condition. This flag is only a hint to the protocol handler and it is no guarantee that such exceptions will be throws. Omitting this parameter results in no exceptions being thrown. The timeout period is not specified in the open call because this is protocol specific. Protocol implementors can either hardwire an appropriate value or read them from an external source such as the system properties.

Because of the common occurrence of opening connections just to gain access to an input or output stream four functions are provided for this purpose.

RIM Implementation Notes
This implementation of the Connector class currently supports the following protocols:

• comm
• socket
• udp
• sms
• http
• https
• tls or ssl

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:<port identifier>[<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>");

You can add the optional deviceside parameter. The deviceside parameter can be set to true or false:

• If deviceside=true is specified in the connection URI, a direct TCP connection is opened from the handheld, without using the Mobile Data Service.
• If deviceside=false is specified in the connection URI, a proxy TCP connection is opened using the Mobile Data Service.
• If the deviceside parameter is not specified, on a BlackBerry 6500 handheld, direct TCP is used by default. On all other handhelds, the Mobile Data Service is used by default.

The following code demonstrates how to open a direct TCP connection from the handheld:

conn = (StreamConnection)Connector.open("socket://testserver:600;deviceside=true");

Note: Direct TCP connections are supported only on the BlackBerry 6500 Series of wireless handhelds. If an application specifies deviceside=true when it opens a connection, the connection fails if direct TCP is not supported.

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>]");

where:

• host is the host address in dotted ASCII-decimal format
• 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 is one of UDP (default), GPAK or GCMP (optional)

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:
/rport=<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.

Input and output stream 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:
(DatagramConnection) 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.

e.g. To open a standard SMS connection use Connector.open("sms://");

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	Specifies whether the underlying TCP connection should be opened directly from the handheld ("deviceside=true"), or opened using the Mobile Data Service as a proxy ("deviceside=false"). Note: Direct TCP is supported only on the BlackBerry 6500 Series of wireless handhelds. If an application specifies deviceside=true when it opens a connection, the connection fails if direct TCP is not supported.	On the BlackBerry 6500 Series of wireless handhelds, the default is true. On all other handhelds, default is false.

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):
/rport=<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
deviceside	Specifies whether the underlying TCP connection should be opened directly from the handheld ("deviceside=true"), or opened using the Mobile Data Service as a proxy ("deviceside=false"). On the BlackBerry 6500 Series of wireless handhelds, the default is true. On all other handhelds, the default is false. Note: Direct TCP is supported only on the BlackBerry 6500 Series of wireless handhelds. If an application specifies deviceside=true when it opens a connection, the connection fails if direct TCP is not supported. 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.
END_TO_END_REQUIRED or END_TO_END_DESIRED	END_TO_END_REQUIRED 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. END_TO_END_DESIRED 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.

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> [;<optional parameters>]");
OR
Connector.open("ssl://<host>:<port> [;<optional parameters>]");

The following optional parameters can be specified:

Parameter	Description
deviceside	Specifies whether the underlying TCP connection should be opened directly from the handheld ("deviceside=true"), or opened using the Mobile Data Service as a proxy ("deviceside=false"). On the BlackBerry 6500 Series of wireless handhelds, the default is true. On all other handhelds, the default is false. Note: Direct TCP is supported only on the BlackBerry 6500 Series of wireless handhelds. If an application specifies deviceside=true when it opens a connection, the connection fails if direct TCP is not supported. 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.
END_TO_END_REQUIRED or END_TO_END_DESIRED	END_TO_END_REQUIRED 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. END_TO_END_DESIRED 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.

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.

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

WRITE

public static final int WRITE

Access mode

READ_WRITE

public static final int READ_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.

IOException - If some other kind of I/O error occurs.

Since:

JDE 3.7.0

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.

IOException - If some other kind of I/O error occurs.

Since:

JDE 3.7.0

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.

IOException - If an I/O error occurs

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0