javax.microedition.io
Interface SocketConnection

All Superinterfaces:
Connection, InputConnection, OutputConnection, StreamConnection
All Known Subinterfaces:
SecureConnection

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.

Blocking Operations

This interface performs blocking Input and Output operations. An application will lock if an implementation of this interface opens a connection from within the main event thread. Prevent an application from locking by opening a connection from within a thread that is separate from the main event thread. SeeConnector for more information.

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:
BlackBerry API 4.0.0, MIDP 2.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.Connection
close
 
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
Since:
BlackBerry API 4.0.0

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
Since:
BlackBerry API 4.0.0

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
Since:
BlackBerry API 4.0.0

RCVBUF

static final byte RCVBUF
Socket option for the size of the receiving buffer (3).

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

SNDBUF

static final byte SNDBUF
Socket option for the size of the sending buffer (4).

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0


Method Detail

setSocketOption

void setSocketOption(byte option,
                     int value)
                     throws IllegalArgumentException,
                            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:
SocketConnection.getSocketOption(byte)
Since:
BlackBerry API 4.0.0

getSocketOption

int getSocketOption(byte option)
                    throws IllegalArgumentException,
                           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:
SocketConnection.setSocketOption(byte, int)
Since:
BlackBerry API 4.0.0

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
Since:
BlackBerry API 4.0.0

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
Since:
BlackBerry API 4.0.0

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.
Since:
BlackBerry API 4.0.0

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.
Since:
BlackBerry API 4.0.0





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.