javax.microedition.io
Interface DatagramConnection

All Superinterfaces:
Connection
All Known Subinterfaces:
UDPDatagramConnection
All Known Implementing Classes:
DatagramConnectionBase, WTLS20Connection

public interface DatagramConnection
extends Connection

This interface defines the capabilities that a datagram connection must have.

Reminder: In common with all the other addressing schemes used for I/O in CLDC, the syntax for datagram addressing is not defined in the CLDC Specification. Syntax definition can only be take place at the profile level. The reason for this is that the datagram interface classes of CLDC can be used for implementing various kinds of datagram protocols. Examples include IP and WDP networks as well as infrared beaming protocols used by various PDAs and other devices. All these protocols use very different addressing mechanisms.

In the sample implementation provided as part of the CLDC reference implementation, the following addressing scheme is used for UDP datagrams.

The parameter string describing the target of a connection in the CLDC reference implementation takes the following form:

 {protocol}://[{host}]:[{port}]
 
A datagram connection can be opened in a "client" mode or "server" mode. If the "//{host}" part is missing then the connection is opened as a "server" (by "server", we mean that a client application initiates communication). When the "//{host}" part is specified, the connection is opened as a "client".

Examples:

A datagram connection for accepting datagrams
datagram://:1234

A datagram connection for sending to a server:
datagram://123.456.789.12:1234

Note that the port number in "server mode" (unspecified host name) is that of the receiving port. The port number in "client mode" (host name specified) is that of the target port. The reply-to port in both cases is never unspecified. In "server mode", the same port number is used for both receiving and sending. In "client mode", the reply-to port is always dynamically allocated.

The allocation of datagram objects is done in a more abstract way than in J2SE. This is to allow a single platform to support several different datagram interfaces simultaneously. Datagram objects must be allocated by calling the "newDatagram" method of the DatagramConnection object. The resulting object is defined using another interface type called "javax.microedition.io.Datagram".


Method Summary
 int getMaximumLength()
          Get the maximum length a datagram can be.
 int getNominalLength()
          Get the nominal length of a datagram.
 Datagram newDatagram(byte[] buf, int size)
          Make a new datagram object
 Datagram newDatagram(byte[] buf, int size, String addr)
          Make a new datagram object
 Datagram newDatagram(int size)
          Make a new datagram object automatically allocating a buffer
 Datagram newDatagram(int size, String addr)
          Make a new datagram object
 void receive(Datagram dgram)
          Receive a datagram
 void send(Datagram dgram)
          Send a datagram
 
Methods inherited from interface javax.microedition.io.Connection
close
 

Method Detail

getMaximumLength

public int getMaximumLength()
                     throws IOException
Get the maximum length a datagram can be.
Returns:
The maximum length a datagram can be.
Throws:
IOException - If an I/O error occurs.

getNominalLength

public int getNominalLength()
                     throws IOException
Get the nominal length of a datagram.
Returns:
The nominal length a datagram can be.
Throws:
IOException - If an I/O error occurs.

send

public void send(Datagram dgram)
          throws IOException
Send a datagram
Parameters:
dgram - A datagram.
Throws:
IOException - If an I/O error occurs.
InterruptedIOException - Timeout or upon closing the connection with outstanding I/O.
Since:
JDE 4.0.2

receive

public void receive(Datagram dgram)
             throws IOException
Receive a datagram
Parameters:
dgram - A datagram.
Throws:
IOException - If an I/O error occurs.
InterruptedIOException - Timeout or upon closing the connection with outstanding I/O.
Since:
JDE 4.0.2

newDatagram

public Datagram newDatagram(int size)
                     throws IOException
Make a new datagram object automatically allocating a buffer
Parameters:
size - The length of the buffer to be allocated for the datagram
Returns:
A new datagram
Throws:
IOException - If an I/O error occurs.
IllegalArgumentException - if the length is negative or larger than the buffer
Since:
JDE 4.0.2

newDatagram

public Datagram newDatagram(int size,
                            String addr)
                     throws IOException
Make a new datagram object
Parameters:
size - The length of the buffer to be used
addr - The I/O address to which the datagram will be sent
Returns:
A new datagram
Throws:
IOException - If an I/O error occurs.
IllegalArgumentException - if the length is negative or larger than the buffer, or if the address parameter is invalid
Since:
JDE 4.0.2

newDatagram

public Datagram newDatagram(byte[] buf,
                            int size)
                     throws IOException
Make a new datagram object
Parameters:
buf - The buffer to be used in the datagram
size - The length of the buffer to be allocated for the datagram
Returns:
A new datagram
Throws:
IOException - If an I/O error occurs.
IllegalArgumentException - if the length is negative or larger than the buffer, or if the buffer parameter is invalid
Since:
JDE 4.0.2

newDatagram

public Datagram newDatagram(byte[] buf,
                            int size,
                            String addr)
                     throws IOException
Make a new datagram object
Parameters:
buf - The buffer to be used in the datagram
size - The length of the buffer to be used
addr - The I/O address to which the datagram will be sent
Returns:
A new datagram
Throws:
IOException - If an I/O error occurs.
IllegalArgumentException - if the length is negative or larger than the buffer, or if the address or buffer parameters is invalid
Since:
JDE 4.0.2


Copyright 1999-2004 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.