Connector (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.microedition.io
Class Connector

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

    @TransactionType(value=NOT_SUPPORTED)
    public class Connector

extends Object

This class is factory 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 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 URI format as described in RFC 3986. This takes the general form:

`{scheme}:[{hier-part}][?{query}][#{fragment}]`

where

- `{scheme}` is the name of a protocol such as http.
- `{hier-part}` contains the target of the requested connection and any necessary parameters in the form `";x=y"`.

Example URIs used with GCF include:

- `http://www.example.com:80/over/there?name=ferret#nose`
- `socket://www.sun.com:8080`
- `datagram://:50000`

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.

The creation of a new Connection object is subject to a security check to verify that the caller has the security Permission associated with the requested protocol scheme and target. If the caller lacks the necessary permission, the invoked Connector method throws a SecurityException. Some protocols may defer the security checks to a later stage when the designated target is being accessed, see the Generic Connection Framework (GCF) Security Checks section. See `HttpConnection` for an example of such a protocol.

URIs passed as parameter to Connector methods are normalized as per the Scheme-based and Protocol-based Normalization procedure before proceeding to any security checks on these URIs. These Connector methods throws a ConnectionNotFoundException if the actual target designated by the passed name/URI cannot be found. Some protocols may defer the throwing of that exception to a later stage when the designated target is being accessed. See `HttpConnection` for an example of such a protocol.

Because connections are frequently opened just to gain access to a specific input or output stream, four convenience functions are provided for this purpose.

See also: `DatagramConnection` for information relating to datagram addressing.

Since:
  CLDC 1.0, Java Card 3.0

Field Summary
`static int` | `READ` Access mode READ.
`static int` | `READ_WRITE` Access mode READ_WRITE.
`static int` | `WRITE` Access mode WRITE.

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.
`static void` | `storeConnection(Object object)`

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.

  See Also:
    Constant Field Values

### WRITE

    public static final int WRITE

  Access mode WRITE.

  See Also:
    Constant Field Values

### READ_WRITE

    public static final int READ_WRITE

  Access mode READ_WRITE.

  See Also:
    Constant Field Values

Method Detail

### open

    public static Connection open(String name)
                           throws IOException

  Create and open a Connection.

  Parameters:
    `name` - The URL for the connection.
  Returns:
    A new Connection object.
  Throws:
    `IllegalArgumentException` - If a parameter is invalid.
    `ConnectionNotFoundException` -
    - If the requested protocol type is not supported,
    - or, if it can be immediately determined that the target of the name cannot be found.
    `IOException` - If some other kind of I/O error occurs.
    `SecurityException` - If access to the requested target using the requested protocol is denied.

### open

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

  Create and open a Connection.

  Parameters:
    `name` - The URL for the connection.
    `mode` - The access mode.
  Returns:
    A new Connection object.
  Throws:
    `IllegalArgumentException` - If a parameter is invalid.
    `ConnectionNotFoundException` -
    - If the requested protocol type is not supported,
    - or, if it can be immediately determined that the target of the name cannot be found.
    `IOException` - If some other kind of I/O error occurs.
    `SecurityException` - If access to the requested target using the requested protocol is denied.

### open

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

  Create and open a Connection.

  Parameters:
    `name` - The URL for the connection
    `mode` - The access mode
    `timeouts` - A flag to indicate that the caller wants timeout exceptions
  Returns:
    A new Connection object
  Throws:
    `IllegalArgumentException` - If a parameter is invalid.
    `ConnectionNotFoundException` -
    - If the requested protocol type is not supported,
    - or, if it can be immediately determined that the target of the name cannot be found.
    `IOException` - If some other kind of I/O error occurs.
    `SecurityException` - If access to the requested target using the requested protocol is denied.

### 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 requested protocol type is not supported,
    - or, if the target of the name cannot be found.
    `IOException` - If some other kind of I/O error occurs.
    `SecurityException` - If access to the requested target using the requested protocol is denied.

### 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 requested protocol type is not supported,
    - or, if the target of the name cannot be found.
    `IOException` - If some other kind of I/O error occurs.
    `SecurityException` - If access to the requested target using the requested protocol is denied.

### 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 requested protocol type is not supported,
    - or, if the target of the name cannot be found.
    `IOException` - If some other kind of I/O error occurs.
    `SecurityException` - If access to the requested target using the requested protocol is denied.

### 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 requested protocol type is not supported,
    - or, if the target of the name cannot be found.
    `IOException` - If some other kind of I/O error occurs.
    `SecurityException` - If access to the requested target using the requested protocol is denied.

### storeConnection

    public static void storeConnection(Object object)

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.