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

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.

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

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

Note: The handheld's user can select the default TCP connection behaviour; you can override ths behaviour with the deviceside parameter.

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

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

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:

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.

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:

  (DatagramConnection) Connector.open("sms://[<peer_address>][<port>]");
 

where:

For example, 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.

no parameters

If you don't provide any parameters to the open request, the behaviour varies with the host network.

GPRS/CDMA: use corproate MDS connection. If no corporate MDS service record, then use public MDS. Note, service records are considered corporate unless specifically marked as public.

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

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

mobitex
The syntax for opening a mobitex connection is as follows:

mobitex:<type>:<MAN>
where <type> is one of: and MAN is in ascii-decimal format.

To open a server connection (that is a listener) leave the MAN field blank.

Connector.open() will return a DatagramConnection in this case

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

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 4.0.2

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 4.0.2

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 4.0.2

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 4.0.2

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 4.0.2

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 4.0.2

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 4.0.2


Copyright 1999-2004 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.