javax.microedition.io
Class Connector

java.lang.Object
  javax.microedition.io.Connector

public class Connector

extends Object

This class contains the static methods 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 option 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. See also: DatagramConnection for information relating to datagram addressing

Version:

00/06/19

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

See Also:

Constant Field Values

WRITE

public static final int WRITE

Access mode

See Also:

Constant Field Values

READ_WRITE

public static final int READ_WRITE

Access mode

See Also:

Constant Field Values

Method Detail

open

public static Connection open(String name)
                       throws IOException

Create and open a connection. Calls open(String name, int mode) with mode = READ_WRITE.

Parameters:

name - The URL for the connection, see open(String name, int mode, boolean timeouts)

Returns:

A new Connection object

Throws:

IllegalArgumentException - If a parameter is invalid.

ConnectionNotFoundException - if the requested connection cannot be make, or the protocol type does not exist.

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

open

public static Connection open(String name,
                              int mode)
                       throws IOException

Create and open a connection. Calls open(String name, int mode, boolean timeouts) with timeouts = false.

Parameters:

name - The URL for the connection, see open(String name, int mode, boolean timeouts)

mode - The access mode.

Returns:

A new Connection object.

Throws:

IllegalArgumentException - If a parameter is invalid.

ConnectionNotFoundException - if the requested connection cannot be make, or the protocol type does not exist.

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

open

public static Connection open(String name,
                              int mode,
                              boolean timeouts)
                       throws IOException

Create and open a Connection.
Main entry for "Generic Connection Framework". If successful, this method will return an object that implements one of the generic connection interfaces.

Parameters:

name - The URL for the connection.
Currently implemented are:

• HTTP records
  Example: Connector.open("http://www.foo.com");
  Realized as implementation of the interfaces HttpConnection
  
• Sockets
  Example: Connector.open("socket://129.144.111.222:9000");
  Realized as implementation of the interfaces StreamConnection
  
• Files
  Example: Connector.open("file://foo.dat");
  The letters after the slashes must form a valid file name, optionally with path. The path must not contain "..". Realized as implementation of the interfaces StreamConnection
  Notes: There will be created a subdirectory named "storage" in the directory of the caller if not already exist. You can access all files and subdirectories starting from here. Access to upper directories is not permitted.
• SMS
  For SL45i:
  Example:Connector.open("sms://+49123456");
  For the SL45i you must not set an Application-ID.
  For newer phones:
  Example:Connector.open("sms://+49123456:134");
  The numbers after the slashes must form a valid phone number, followed by the Application ID. The Application ID indicates the relation of the SMS to a specific application.
  Realized as implementation of the interfaces DatagramConnection
  Notes: Due to the special format of Java SMSes "normal" SMS will not be recognized within a Java MIDlet.

For phones with an IrDA Interface:

• Infrared Port
  Example: Connector.open("irda://");
  Realized as implementation of the interfaces DatagramConnection. There is no support for StreamConnection.
  Notes:
  • The IrDA port must be switched on in the phone settings.
  • The mandatory format of the transmitted file:
    file name: "java.jd". Content: The first 4 byte are the length of the following payload

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 requested connection cannot be make, or the protocol type does not exist.

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

openDataInputStream

public static DataInputStream openDataInputStream(String name)
                                           throws IOException

Create and open a connection input stream

Parameters:

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

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

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

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