SocketConnection (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
Interface SocketConnection

All Superinterfaces:
  Connection, InputConnection, OutputConnection, StreamConnection

All Known Subinterfaces:
  SecureConnection

    @TransactionType(value=NOT_SUPPORTED)
    public interface SocketConnection

extends StreamConnection

This interface defines the socket stream connection.

A socket is accessed using a generic connection string with an explicit host and port number. The host may be specified as a fully qualified host name or IPv4 number. E.g., `socket://host.com:79` defines a target socket on the `host.com` system at port `79`.

Note that RFC1900 recommends the use of names rather than IP numbers for best results in the event of IP number reassignment.

### Closing Streams

Every `StreamConnection` provides a `Connection` object as well as an `InputStream` and `OutputStream` to handle the I/O associated with the connection. Each of these interfaces has its own `close()` method. For systems that support duplex communication over the socket connection, closing of the input or output stream SHOULD shutdown just that side of the connection. E.g., closing the `InputStream` will permit the `OutputStream` to continue sending data.

Once the input or output stream has been closed, it can only be reopened with a call to `Connector.open()`. The application will receive an `IOException` if an attempt is made to reopen the stream.

## BNF Format for Connector.open() string

The URI must conform to the BNF syntax specified below. If the URI does not conform to this syntax, an `IllegalArgumentException` is thrown.

<socket_connection_string> | ::= "socket://"<hostport>
<hostport> | ::= host ":" port
<host> | ::= host name or IP address (omitted for inbound connections, See ServerSocketConnection)
<port> | ::= numeric port number

### Examples

The following examples show how a `SocketConnection` would be used to access a sample loopback program.

     SocketConnection sc = (SocketConnection)
     Connector.open("socket://host.com:79");
     sc.setSocketOption(SocketConnection.LINGER, 5);

     InputStream is = sc.openInputStream(); OutputStream os =
     sc.openOutputStream();

     os.write("\r\n".getBytes()); int ch = 0; while(ch != -1) { ch = is.read(); }

     is.close(); os.close(); sc.close();

Since:
  MIDP 2.0, CDC 1.1, Java Card 3.0

Field Summary
`static byte` | `DELAY` Socket option for the small buffer writing delay (0).
`static byte` | `KEEPALIVE` Socket option for the keep alive feature (2).
`static byte` | `LINGER` Socket option for the linger time to wait in seconds before closing a connection with pending data output (1).
`static byte` | `RCVBUF` Socket option for the size of the receiving buffer (3).
`static byte` | `SNDBUF` Socket option for the size of the sending buffer (4).

Method Summary
`String` | `getAddress()` Gets the remote address to which the socket is bound.
`String` | `getLocalAddress()` Gets the local address to which the socket is bound.
`int` | `getLocalPort()` Returns the local port to which this socket is bound.
`int` | `getPort()` Returns the remote port to which this socket is bound.
`int` | `getSocketOption(byte option)` Get a socket option for the connection.
`void` | `setSocketOption(byte option, int value)` Set a socket option for the connection.

Methods inherited from interface javax.microedition.io.InputConnection
`openDataInputStream, openInputStream`

Methods inherited from interface javax.microedition.io.OutputConnection
`openDataOutputStream, openOutputStream`

Methods inherited from interface javax.microedition.io.Connection
`close`

Field Detail

### DELAY

    static final byte DELAY

  Socket option for the small buffer writing delay (0). Set to zero to disable Nagle algorithm for small buffer operations. Set to a non-zero value to enable.

  See Also:
    Constant Field Values

### LINGER

    static final byte LINGER

  Socket option for the linger time to wait in seconds before closing a connection with pending data output (1). Setting the linger time to zero disables the linger wait interval.

  See Also:
    Constant Field Values

### KEEPALIVE

    static final byte KEEPALIVE

  Socket option for the keep alive feature (2). Setting KEEPALIVE to zero will disable the feature. Setting KEEPALIVE to a non-zero value will enable the feature.

  See Also:
    Constant Field Values

### RCVBUF

    static final byte RCVBUF

  Socket option for the size of the receiving buffer (3).

  See Also:
    Constant Field Values

### SNDBUF

    static final byte SNDBUF

  Socket option for the size of the sending buffer (4).

  See Also:
    Constant Field Values

Method Detail

### setSocketOption

    void setSocketOption(byte option,
                         int value)
                         throws IOException

  Set a socket option for the connection.

  Options inform the low level networking code about intended usage patterns that the application will use in dealing with the socket connection.

  Calling `setSocketOption` to assign buffer sizes is a hint to the platform of the sizes to set the underlying network I/O buffers. Calling `getSocketOption` can be used to see what sizes the system is using. The system MAY adjust the buffer sizes to account for better throughput available from Maximum Transmission Unit (MTU) and Maximum Segment Size (MSS) data available from current network information.

  Parameters:
    `option` - socket option identifier (KEEPALIVE, LINGER, SNDBUF, RCVBUF, or DELAY)
    `value` - numeric value for specified option
  Throws:
    `IllegalArgumentException` - if the value is not valid (e.g., negative value) or if the option identifier is not valid
    `IOException` - if the connection was closed
  See Also:
    `getSocketOption(byte)`

### getSocketOption

    int getSocketOption(byte option)
                        throws IOException

  Get a socket option for the connection.

  Parameters:
    `option` - socket option identifier (KEEPALIVE, LINGER, SNDBUF, RCVBUF, or DELAY)
  Returns:
    numeric value for specified option or -1 if the value is not available.
  Throws:
    `IllegalArgumentException` - if the option identifier is not valid
    `IOException` - if the connection was closed
  See Also:
    `setSocketOption(byte, int)`

### getLocalAddress

    String getLocalAddress()
                           throws IOException

  Gets the local address to which the socket is bound.

  The host address(IP number) that can be used to connect to this end of the socket connection from an external system. Since IP addresses may be dynamically assigned, a remote application will need to be robust in the face of IP number reasssignment.

  The local hostname (if available) can be accessed from `System.getProperty("microedition.hostname")`

  Returns:
    the local address to which the socket is bound.
  Throws:
    `IOException` - if the connection was closed.
  See Also:
    `ServerSocketConnection`

### getLocalPort

    int getLocalPort()
                     throws IOException

  Returns the local port to which this socket is bound.

  Returns:
    the local port number to which this socket is connected.
  Throws:
    `IOException` - if the connection was closed.
  See Also:
    `ServerSocketConnection`

### getAddress

    String getAddress()
                      throws IOException

  Gets the remote address to which the socket is bound. The address can be either the remote host name or the IP address(if available).

  Returns:
    the remote address to which the socket is bound.
  Throws:
    `IOException` - if the connection was closed.

### getPort

    int getPort()
                throws IOException

  Returns the remote port to which this socket is bound.

  Returns:
    the remote port number to which this socket is connected.
  Throws:
    `IOException` - if the connection was closed.

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.