/*
 *   
 *
 * Copyright  1990-2006 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version
 * 2 only, as published by the Free Software Foundation. 
 * 
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License version 2 for more details (a copy is
 * included at /legal/license.txt). 
 * 
 * You should have received a copy of the GNU General Public License
 * version 2 along with this work; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA 
 * 
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 or visit www.sun.com if you need additional
 * information or have any questions. 
 */

package javax.microedition.io;

import java.io.*;

/**
 * This is the generic datagram interface. It represents an object that
 * will act as the holder of data to be sent or received from a datagram
 * connection.
 * <p>
 * The DataInput and DataOutput interfaces are extended by this interface
 * to provide a simple way to read and write binary data in and out of
 * the datagram buffer. An additional function reset() may be called to
 * reset the read/write point to the beginning of the buffer.
 * <p>
 * It should be noted that in the interests of reducing space and speed
 * concerns, these mechanisms are very simple. In order to use them
 * correctly the following restrictions should be observed:
 * <p>
 * 1) The use of the standard DataInput and DataOutput interfaces is
 * done in order to provide a familiar API for reading and writing
 * data into and out of a Datagram buffer.
 * It should be understood however that this is not an API to a Java
 * stream and does not exhibit all of the features normally associated
 * with one. The most important difference here is that a Java stream
 * is either an InputStream or an OutputStream. The interface presented
 * here is, essentially, both at the same time. As the datagram object
 * does not have a mode for reading and writing, it is necessary for the
 * application programmer to realize that no automatic detection of the
 * wrong mode usage can be done.
 * <p>
 * 2) The DataInput and DataOutput interfaces will not work with any
 * arbitrary settings of the Datagram state variables. The main
 * restriction here is that the <I>offset</I> state variable must
 * at all times be zero. Datagrams may be used in the normal way
 * where the offset is non-zero but when this is done the DataInput
 * and DataOutput interfaces cannot be used.
 * <p>
 * 3) The DataInput and DataOutput read() and write() functions work
 * by using an invisible state variable of the Datagram object. Before
 * any data is read from or written to the datagram buffer, this state
 * variable must be zeroed using the reset() function. This variable
 * is not the <I>offset</I> state variable but an additional state
 * variable used only for the read() and write() functions.
 * <p>
 * 4) Before data is to be received into the datagram's buffer, the
 * <I>offset</I> state variable and the <I>length</I> state variable
 * must first be set up to the part of the buffer the data should be
 * written to. If the intention is to use the read() functions, the
 * offset must be zero. After receive() is called, the data can be
 * read from the buffer using the read() functions until an EOF
 * condition is found. This will occur when the number of characters
 * represented by the length parameter have been read.
 * <p>
 * 5) To write data into the buffer prior to a send() operation,
 * the reset() function should first be called.  This will zero the
 * read/write pointer along with the offset and length parameters
 * of the Datagram object. Then the data can be written using the
 * write() functions. When this process is complete, the <I>length</I>
 * state variable will be set to the correct value for the send()
 * function of the datagram's connection, and so the send operation
 * can take place. An IndexOutOfBoundsException will be thrown if
 * the number of characters written exceeds the size of the buffer.
 *
 * @version 1.2 1/17/2000
 */
public interface Datagram extends DataInput, DataOutput {

    /**
     * Get the address in the datagram.
     *
     * @return the address in string form, or null if no address was set
     *
     * @see #setAddress
     */
    public String getAddress();

    /**
     * Get the buffer.
     *
     * @return the data buffer
     *
     * @see #setData
     */
    public byte[] getData();

    /**
     * Get the length.
     *
     * @return the length of the data
     *
     * @see #setLength
     */
    public int getLength();

    /**
     * Get the offset.
     *
     * @return the offset into the data buffer
     */
    public int getOffset();

    /**
     * Set datagram address.
     * <p>
     * The actual addressing scheme is implementation-dependent.
     * Please read the general comments on datagram addressing
     * in <I>DatagramConnection.java</I>.
     * <p>
     * Note that if the address of a datagram is not specified, then it
     * defaults to that of the connection.
     *
     * @param addr the new target address as a URL
     * @exception IllegalArgumentException if the address is not valid
     * @exception IOException if a some kind of I/O error occurs
     *
     * @see #getAddress
     */
    public void setAddress(String addr) throws IOException;

    /**
     * Set datagram address, copying the address from another datagram.
     *
     * @param reference the datagram who's address will be copied as
     * the new target address for this datagram.
     * @exception IllegalArgumentException if the address is not valid
     *
     * @see #getAddress
     */
    public void setAddress(Datagram reference);

    /**
     * Set the length.
     *
     * @param len the new length of the data
     * @exception IllegalArgumentException if the length is negative
     * or larger than the buffer
     *
     * @see #getLength
     */
    public void setLength(int len);

    /**
     * Set the buffer, offset and length.
     *
     * @param buffer the data buffer
     * @param offset the offset into the data buffer
     * @param len the length of the data in the buffer
     * @exception IllegalArgumentException if the length or offset
     *                                     fall outside the buffer
     *
     * @see #getData
     */
    public void setData(byte[] buffer, int offset, int len);

    /**
     * Zero the read/write pointer as well as the offset and
     * length parameters.
     */
    public void reset();

}
