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
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	Default	Description
baudrate	19200	The speed of the port.
bitsperchar	8	The number bits per character(7 or 8).
stopbits	1	the number of stop bits per char(1 or 2)
parity	none	The parity can be odd, even, or none.
channel	none	The USB channel name to register and open.

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

Input and output stream can then be acquired using the openInputStream() and openOutputStream() methods. See StreamConnection for more information.

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 aource 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	Default	Description
TunnelAuthPassword	none	Password for APN session.
TunnelAuthUsername	none	User name for APN session.
WabEnableWTLS	none	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.
WapGatewayIP	none	IP address of gateway.
WapGatewayPort	WAP_GATEWAY_PORT_DEFAULT (9201)	Gateway port value.
WapSourceIP	WAP_SOURCE_IP_DEFAULT ("127.0.0.1")	IP address of source.
WapSourcePort	WAP_SOURCE_PORT_DEFAULT (8205)	Source port value.
WapGatewayAPN	WAP_GATEWAY_APN_DEFAULT ("rim.net.gprs")	Access Point Note

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.

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

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

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

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

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

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

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