DatagramConnection

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.microedition.io
Interface DatagramConnection

All Superinterfaces:
  Connection

All Known Subinterfaces:
  UDPDatagramConnection

    public interface DatagramConnection

extends Connection

This interface defines the capabilities that a datagram connection must have. The parameter string describing the target of a connection 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.

Also note that the allocation of datagram objects is done in a more abstract way than in Java 2 Standard Edition (J2SE). Instead of providing a concrete `DatagramPacket` class, an abstract `Datagram` interface is provided. This is to allow a single platform to support several different datagram interfaces simultaneously. Datagram objects must be allocated by calling the `newDatagram` methods of the `DatagramConnection` object. The resulting object is defined using another interface type called `javax.microedition.io.Datagram`.

Since:
  CLDC 1.0
Version:
  12/17/01 (CLDC 1.1)
Author:
  Brian Modra, Nik Shaylor

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)` Create a new datagram object.
`Datagram` | `newDatagram(byte[] buf, int size, String addr)` Make a new datagram object.
`Datagram` | `newDatagram(int size)` Create a new datagram object.
`Datagram` | `newDatagram(int size, String addr)` Create 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

    int getMaximumLength()
                         throws IOException

  Get the maximum length a datagram can be. Maximum length determines the maximum size of the datagram that can be created using the `newDatagram` method, and the maximum size of the datagram that can be sent or received.

  Returns:
    The maximum length of a datagram.
  Throws:
    `IOException` - If an I/O error occurs.

### getNominalLength

    int getNominalLength()
                         throws IOException

  Get the nominal length of a datagram. Nominal length refers to the size of the datagram that is stored into the data buffer. Nominal length may be equal or less than the maximum length of the datagram.

  Returns:
    The nominal length of a datagram.
  Throws:
    `IOException` - If an I/O error occurs.

### send

    void send(Datagram dgram)
              throws IOException

  Send a datagram. The `Datagram` object includes the information indicating the data to be sent, its length, and the address of the receiver. The method sends `length` bytes starting at the current `offset` of the `Datagram` object, where `length` and `offset` are internal state variables of the `Datagram` object.

  If a security manager exists, a datagram cannot be sent if the security manager's `checkConnect(host, port)` method does not permit at connection to the remote host and port.

  Parameters:
    `dgram` - A datagram.
  Throws:
    `IOException` - If an I/O error occurs.
    `InterruptedIOException` - Timeout or interrupt occurred.
    `SecurityException` - If a security manager exists, and its `checkConnect` method does not allow the operation.

### receive

    void receive(Datagram dgram)
                 throws IOException

  Receive a datagram. When this method returns, the internal buffer in the `Datagram` object is filled with the data received, starting at the location determined by the `offset` state variable, and the data is ready to be read using the methods of the `DataInput` interface.

  This method blocks until a datagram is received. The internal `length` state variable in the `Datagram` object contains the length of the received datagram. If the received data is longer than the length of the internal buffer minus offset, data is truncated.

  This method does not change the internal read/write state variable of the `Datagram` object. Use method `Datagram.reset` to change the pointer before reading if necessary.

  If a security manager exists, a datagram cannot be received if the security manager's `checkAccept(host, port)` method does not permit a connection from the remote host and port.

  Parameters:
    `dgram` - A datagram.
  Throws:
    `IOException` - If an I/O error occurs.
    `InterruptedIOException` - Timeout or interrupt occurred.

### newDatagram

    Datagram newDatagram(int size)
                         throws IOException

  Create a new datagram object.

  Parameters:
    `size` - The size of the buffer needed for the datagram
  Returns:
    A new datagram
  Throws:
    `IOException` - If an I/O error occurs.
    `IllegalArgumentException` - if the size is negative or larger than the maximum size

### newDatagram

    Datagram newDatagram(int size,
                         String addr)
                         throws IOException

  Create a new datagram object.

  Parameters:
    `size` - The size of the buffer needed for the datagram
    `addr` - The I/O address to which the datagram will be sent, in the form `"datagram://{host}:{port}"`.
  Returns:
    A new datagram
  Throws:
    `IOException` - If an I/O error occurs.
    `IllegalArgumentException` - if the size is negative or larger than the maximum size, or if the address parameter is invalid

### newDatagram

    Datagram newDatagram(byte[] buf,
                         int size)
                         throws IOException

  Create a new datagram object.

  Parameters:
    `buf` - The buffer to be used for the datagram
    `size` - The size of the buffer needed for the datagram
  Returns:
    A new datagram
  Throws:
    `IOException` - If an I/O error occurs.
    `IllegalArgumentException` - if the size is negative or larger than the maximum size or the given buffer's length, or if the buffer parameter is invalid

### newDatagram

    Datagram newDatagram(byte[] buf,
                         int size,
                         String addr)
                         throws IOException

  Make a new datagram object.

  Parameters:
    `buf` - The buffer to be used for the datagram
    `size` - The size of the buffer needed for the datagram
    `addr` - The I/O address to which the datagram will be sent, in the form `"datagram://{host}:{port}"`.
  Returns:
    A new datagram
  Throws:
    `IOException` - If an I/O error occurs.
    `IllegalArgumentException` - if the size is negative or larger than the maximum size or the given buffer's length, or if the address or buffer parameter is invalid

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD