net.rim.device.api.io
Class DatagramBase

java.lang.Object
  |
  +--net.rim.device.api.util.DataBuffer
        |
        +--net.rim.device.api.io.DatagramBase
All Implemented Interfaces:
Datagram, DataInput, DataOutput, IOProperties, Persistable, Persistable

public class DatagramBase
extends DataBuffer
implements Datagram, IOProperties

Generic datagram object defines holder of data sent or received from a datagram connection.

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. A special method, reset(), may be called to reset the read/write point to the beginning of the buffer.

Since:
JDE 4.0.0

Field Summary
protected  DatagramAddressBase _addressBase
           
protected  int _datagramId
           
protected  int _flags
           
protected  DatagramStatusListener _listener
           
protected  Hashtable _properties
           
protected  int _validFlags
           
static int DG_NULL_ID
          Datagram has null ID.
 
Fields inherited from interface net.rim.device.api.io.IOProperties
CDMA_SET_FAST_DORMANCY_FLAG, FLAG_INVALID, FLAG_SET, FLAG_UNSET, GME_ADD_SRC_FIELD_FLAG, GME_DELAYED_ACK_FLAG, GME_FAIL_ON_MISSING_ROUTING_INFO_FLAG, GME_REQUEST_CONFIRMATION_FLAG, MDP_DATAGRAM_ACK_FLAG, MDP_DONT_SET_FAST_DORMANCY_FLAG, MDP_PACKET_ACK_FLAG, MOBITEX_MAILBOX_FLAG, MOBITEX_REQUEST_ACK_FLAG, UDP_RETRY_ON_NO_CONTEXT
 
Constructor Summary
DatagramBase()
          Constructs a new DatagramBase instance.
DatagramBase(byte[] buffer, int offset, int length)
          Constructs a new DatagramBase instance from provided data.
DatagramBase(byte[] buffer, int offset, int length, DatagramAddressBase addressBase)
          Constructs a new DatagramBase instance from provided data and address base.
DatagramBase(byte[] buffer, int offset, int length, String address)
          Constructs a new DatagramBase instance from provided data and target address.
 
Method Summary
 void copy(DatagramBase dgram)
          Copies state and data from provided datagram.
 void copyFlagsInto(DatagramBase dst)
          Copies flags from this datagram into provided datagram.
 String getAddress()
          Retrieves the target address for this datagram.
 DatagramAddressBase getAddressBase()
          Retrieves the address base for this datagram.
 byte[] getData()
          Retrieves this datagram's data.
 int getDatagramId()
          Retrieves this datagram's datagram ID.
 DatagramStatusListener getDatagramStatusListener()
          Retrieves current status listener object.
 int getFlag(int flag)
          Retrieves state of named flag.
 int getLength()
          Retrieves this datagram's data length.
 int getOffset()
          Retrieves the offset into this datagram's data.
 Object getProperty(String name)
          Retrieves property by name.
 boolean isFlagSet(int flag)
          Determines if named flag is set.
protected  DatagramAddressBase newAddressBase()
          Retrieve new address base.
 void reset()
          Resets state and data of this datagram.
 void resetDataBuffer()
          Resets only the data of this datagram.
 void setAddress(Datagram datagram)
          Sets this datagram's address, copying from provided datagram.
 void setAddress(String address)
          Sets this datagram's address.
 void setAddressBase(DatagramAddressBase addressBase)
          Sets this datagram's address base, copying from provided address base object.
 void setData(byte[] buffer, int offset, int length)
          Sets this datagram's data.
 void setDatagramId(int datagramId)
          Sets datagram ID for this datagram.
 void setDatagramStatusListener(DatagramStatusListener listener)
          Registers status listener to receive events.
 void setFlag(int flag, boolean value)
          Sets state of named flag.
 void setLength(int length)
          Sets this datagram's data length.
 Object setProperty(String name, Object data)
          Sets a property for this datagram.
 void simpleReset()
          Resets only the state of this datagram Use this method to remove this datagram's properties and flags.
 
Methods inherited from class net.rim.device.api.util.DataBuffer
available, ensureBuffer, ensureCapacity, ensureLength, eof, getArray, getArrayLength, getArrayPosition, getArrayStart, getCompressedIntSize, getPosition, isBigEndian, read, read, read, read, readBoolean, readByte, readByteArray, readChar, readCompressedInt, readCompressedLong, readDouble, readFloat, readFully, readFully, readInt, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF, rewind, setBigEndian, setData, setPosition, skipBytes, toArray, trim, trim, write, write, write, write, write, write, write, writeBoolean, writeByte, writeByteArray, writeByteArray, writeByteArray, writeChar, writeChars, writeCompressedInt, writeCompressedLong, writeDouble, writeFloat, writeInt, writeLong, writeShort, writeUTF, zero
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.io.DataInput
readBoolean, readByte, readChar, readDouble, readFloat, readFully, readFully, readInt, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF, skipBytes
 
Methods inherited from interface java.io.DataOutput
write, write, write, writeBoolean, writeByte, writeChar, writeChars, writeDouble, writeFloat, writeInt, writeLong, writeShort, writeUTF
 

Field Detail

_addressBase

protected DatagramAddressBase _addressBase
Since:
JDE 4.0.0

_datagramId

protected int _datagramId
Since:
JDE 4.0.0

_flags

protected int _flags
Since:
JDE 4.0.0

_listener

protected DatagramStatusListener _listener
Since:
JDE 4.0.0

_properties

protected Hashtable _properties
Since:
JDE 4.0.0

_validFlags

protected int _validFlags
Since:
JDE 4.0.0

DG_NULL_ID

public static final int DG_NULL_ID
Datagram has null ID.
Since:
JDE 4.0.0
Constructor Detail

DatagramBase

public DatagramBase()
Constructs a new DatagramBase instance.
Since:
JDE 4.0.0

DatagramBase

public DatagramBase(byte[] buffer,
                    int offset,
                    int length)
Constructs a new DatagramBase instance from provided data.
Parameters:
buffer - Data buffer containing data for datagram.
offset - First byte in buffer to read.
length - Number of bytes to read from buffer.
Since:
JDE 4.0.0

DatagramBase

public DatagramBase(byte[] buffer,
                    int offset,
                    int length,
                    DatagramAddressBase addressBase)
Constructs a new DatagramBase instance from provided data and address base.
Parameters:
buffer - Data buffer containing data for datagram.
offset - First byte in buffer to read.
length - Number of bytes to read from buffer.
addressBase - Address base for datagram.
Since:
JDE 4.0.0

DatagramBase

public DatagramBase(byte[] buffer,
                    int offset,
                    int length,
                    String address)
             throws IOException
Constructs a new DatagramBase instance from provided data and target address.
Parameters:
buffer - Data buffer containing data for datagram.
offset - First byte in buffer to read.
length - Number of bytes to read from buffer.
address - Address for datagram.
Since:
JDE 4.0.0
Method Detail

copy

public void copy(DatagramBase dgram)
          throws IOException
Copies state and data from provided datagram.

Use this method to copy the data and internal state (poperties, flags, address) from provied datagram into this datagram.

Sub-classes are expected to override this method for specific functionality, but should first call super.copy( datagram ) and then copy the subclass-specific material (including any subclass-specific properties).

Parameters:
dgram - Source datagram that things should copy from
Since:
JDE 4.0.0

copyFlagsInto

public void copyFlagsInto(DatagramBase dst)
Copies flags from this datagram into provided datagram.
Parameters:
dst - Datagram to receive flags.
Since:
JDE 4.0.0

getAddress

public String getAddress()
Retrieves the target address for this datagram.
Returns:
Target address in string form, or null if no address was set.
Since:
JDE 4.0.0

getAddressBase

public DatagramAddressBase getAddressBase()
Retrieves the address base for this datagram.
Returns:
Address base, or null if no address was set.
Since:
JDE 4.0.0

getData

public byte[] getData()
Retrieves this datagram's data.
Returns:
Data buffer containing this datagram's data.
Since:
JDE 4.0.0

getDatagramId

public int getDatagramId()
Retrieves this datagram's datagram ID.
Returns:
This datagram's datagram ID.
Since:
JDE 4.0.0

getDatagramStatusListener

public DatagramStatusListener getDatagramStatusListener()
Retrieves current status listener object.
Returns:
Status listener object currently registered to receive events, or null if no listener registered.
Since:
JDE 4.0.0

getFlag

public int getFlag(int flag)
Retrieves state of named flag.
Parameters:
flag - Flag for which to retrieve state.
Returns:
IOProperties.FLAG_SET if set; IOProperties.FLAG_UNSET if unset; IOProperties.FLAG_INVALID if not a valid flag.
Since:
JDE 4.0.0

getLength

public int getLength()
Retrieves this datagram's data length.
Specified by:
getLength in interface Datagram
Overrides:
getLength in class DataBuffer
Returns:
Length of this datagram's data.
Since:
JDE 4.0.0

getOffset

public int getOffset()
Retrieves the offset into this datagram's data.
Returns:
Offset into this datagram's data.
Since:
JDE 4.0.0

getProperty

public Object getProperty(String name)
Retrieves property by name.
Parameters:
name - Name for property to find.
Returns:
Property object, or null if no property with provided name.
Since:
JDE 4.0.0

isFlagSet

public boolean isFlagSet(int flag)
Determines if named flag is set.
Parameters:
flag - Flag to test.
Returns:
True if named flag is set; otherwise, false.
Since:
JDE 4.0.0

newAddressBase

protected DatagramAddressBase newAddressBase()
Retrieve new address base.

By default, this method constructs and returns a new datagram address base object. Sub-classes should override this method for more specific functionality.

Returns:
New datagram address base object.
Since:
JDE 4.0.0

reset

public void reset()
Resets state and data of this datagram.

Use this method to flush this datagram, making it an empty datagram with a length of 0 bytes, with no properties or flags. The address is set to null and the registered listener (if present) is removed.

Specified by:
reset in interface Datagram
Overrides:
reset in class DataBuffer
Since:
JDE 4.0.0
See Also:
simpleReset()

resetDataBuffer

public void resetDataBuffer()
Resets only the data of this datagram.

Use this method to flush this datagram, making it an empty datagram with a length of 0 bytes. This method does not affect any of the datagram's internal state variables (properties, flags, address).

Since:
JDE 4.0.0

setAddress

public void setAddress(Datagram datagram)
Sets this datagram's address, copying from provided datagram.
Parameters:
datagram - The datagram who's address will be copied as the new target address for this datagram.
Throws:
IllegalArgumentException - If the address is not valid.
Since:
JDE 4.0.0

setAddress

public void setAddress(String address)
Sets this datagram's address.

The parameter string describing the target of the datagram takes this form:

     {protocol}:{target}
 

For example, the "target" can be "//{host}:{port}" (but is not necessarily limited to this).

So in this example a datagram connection for sending to a server could be addressed as so:

     datagram://123.456.789.12:1234
 

Note: If the address of a datagram is not specified, then it defaults to that of the connection.

Parameters:
address - New target address.
Throws:
IllegalArgumentException - If you provide an invalid address.
Since:
JDE 4.0.0

setAddressBase

public void setAddressBase(DatagramAddressBase addressBase)
Sets this datagram's address base, copying from provided address base object.
Parameters:
addressBase - Address base to serve as source.
Since:
JDE 4.0.0

setData

public void setData(byte[] buffer,
                    int offset,
                    int length)
Sets this datagram's data.

Note: This method resets the stream to big endian mode.

Specified by:
setData in interface Datagram
Overrides:
setData in class DataBuffer
Parameters:
buffer - Data buffer.
offset - Offset into the data buffer.
length - Length of the data in the buffer.
Throws:
IllegalArgumentException - If the length or offset fall outside the buffer.
Since:
JDE 4.0.0

setDatagramId

public void setDatagramId(int datagramId)
Sets datagram ID for this datagram.
Parameters:
datagramID - Dstagram ID to set.
Since:
JDE 4.0.0

setDatagramStatusListener

public void setDatagramStatusListener(DatagramStatusListener listener)
Registers status listener to receive events.
Returns:
listener Status listener object to receive events, or null to remove registered listener.
Since:
JDE 4.0.0

setFlag

public void setFlag(int flag,
                    boolean value)
Sets state of named flag.
Parameters:
flag - Flag to set or unset.
value - True to set flag; false to unset it.
Since:
JDE 4.0.0

setLength

public void setLength(int length)
Sets this datagram's data length.
Specified by:
setLength in interface Datagram
Overrides:
setLength in class DataBuffer
Parameters:
length - New length for this datagram's data; must not be less than zero.
Throws:
IllegalArgumentException - If provided length is negative.
Since:
JDE 4.0.0

setProperty

public Object setProperty(String name,
                          Object data)
Sets a property for this datagram.
Parameters:
name - Name of the property to set.
data - Data for property; pass null to remove the named property from this datagram.
Returns:
Previous data contained in your named property, or null if no previous data.
Since:
JDE 4.0.0

simpleReset

public void simpleReset()
Resets only the state of this datagram

Use this method to remove this datagram's properties and flags. The address is set to null and the registered listener (if present) is removed. This method does not flush this datagram's data or alter its length.

Since:
JDE 4.0.0
See Also:
reset()



Copyright 1999-2009 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.