net.rim.device.api.io
Class DatagramBase

java.lang.Object
  extended by net.rim.device.api.util.DataBuffer
      extended by net.rim.device.api.io.DatagramBase
All Implemented Interfaces:
DataInput, DataOutput, Datagram, IOProperties, 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, DatagramBase.reset(), may be called to reset the read/write point to the beginning of the buffer.

Since:
BlackBerry API 4.0.0

Field Summary
static int DG_NULL_ID
          Datagram has null ID.
protected  DatagramAddressBase _addressBase
           
protected  int _datagramId
           
protected  int _flags
           
protected  DatagramStatusListener _listener
           
protected  Hashtable _properties
           
protected  int _validFlags
           
 
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, String address)
          Constructs a new DatagramBase instance from provided data and target address.
DatagramBase(byte[] buffer, int offset, int length, DatagramAddressBase addressBase)
          Constructs a new DatagramBase instance from provided data and address base.
 
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(String address)
          Sets this datagram's address.
 void setAddress(Datagram datagram)
          Sets this datagram's address, copying from provided datagram.
 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, readLine, readLong, readShort, readUTF, readUnsignedByte, readUnsignedShort, rewind, setBigEndian, setData, setPosition, skipBytes, toArray, trim, trim, write, write, write, write, write, write, write, writeBoolean, writeByte, writeByteArray, writeByteArray, writeByteArray, writeBytes, 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, readUTF, readUnsignedByte, readUnsignedShort, skipBytes
 
Methods inherited from interface java.io.DataOutput
write, write, write, writeBoolean, writeByte, writeChar, writeChars, writeDouble, writeFloat, writeInt, writeLong, writeShort, writeUTF
 



Field Detail

DG_NULL_ID

public static final int DG_NULL_ID
Datagram has null ID.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

_addressBase

protected DatagramAddressBase _addressBase
Since:
BlackBerry API 4.0.0

_properties

protected Hashtable _properties
Since:
BlackBerry API 4.0.0

_flags

protected int _flags
Since:
BlackBerry API 4.0.0

_validFlags

protected int _validFlags
Since:
BlackBerry API 4.0.0

_datagramId

protected int _datagramId
Since:
BlackBerry API 4.0.0

_listener

protected DatagramStatusListener _listener
Since:
BlackBerry API 4.0.0


Constructor Detail

DatagramBase

public DatagramBase()
Constructs a new DatagramBase instance.

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


Method Detail

getAddress

public String getAddress()
Retrieves the target address for this datagram.

Specified by:
getAddress in interface Datagram
Returns:
Target address in string form, or null if no address was set.
Since:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 4.0.0

getData

public byte[] getData()
Retrieves this datagram's data.

Specified by:
getData in interface Datagram
Returns:
Data buffer containing this datagram's data.
Since:
BlackBerry API 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:
BlackBerry API 4.0.0

getOffset

public int getOffset()
Retrieves the offset into this datagram's data.

Specified by:
getOffset in interface Datagram
Returns:
Offset into this datagram's data.
Since:
BlackBerry API 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.

Specified by:
setAddress in interface Datagram
Parameters:
address - New target address.
Throws:
IllegalArgumentException - If you provide an invalid address.
Since:
BlackBerry API 4.0.0

setAddress

public void setAddress(Datagram datagram)
Sets this datagram's address, copying from provided datagram.

Specified by:
setAddress in interface 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:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 4.0.0

setProperty

public Object setProperty(String name,
                          Object data)
Sets a property for this datagram.

Specified by:
setProperty in interface IOProperties
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:
BlackBerry API 4.0.0

getProperty

public Object getProperty(String name)
Retrieves property by name.

Specified by:
getProperty in interface IOProperties
Parameters:
name - Name for property to find.
Returns:
Property object, or null if no property with provided name.
Since:
BlackBerry API 4.0.0

setFlag

public void setFlag(int flag,
                    boolean value)
Sets state of named flag.

Specified by:
setFlag in interface IOProperties
Parameters:
flag - Flag to set or unset.
value - True to set flag; false to unset it.
Since:
BlackBerry API 4.0.0

getFlag

public int getFlag(int flag)
Retrieves state of named flag.

Specified by:
getFlag in interface IOProperties
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:
BlackBerry API 4.0.0

isFlagSet

public boolean isFlagSet(int flag)
Determines if named flag is set.

Specified by:
isFlagSet in interface IOProperties
Parameters:
flag - Flag to test.
Returns:
True if named flag is set; otherwise, false.
Since:
BlackBerry API 4.0.0

copyFlagsInto

public void copyFlagsInto(DatagramBase dst)
Copies flags from this datagram into provided datagram.

Parameters:
dst - Datagram to receive flags.
Since:
BlackBerry API 4.0.0

setDatagramStatusListener

public void setDatagramStatusListener(DatagramStatusListener listener)
Registers status listener to receive events.

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

setDatagramId

public void setDatagramId(int datagramId)
Sets datagram ID for this datagram.

Parameters:
datagramID - Dstagram ID to set.
Since:
BlackBerry API 4.0.0

getDatagramId

public int getDatagramId()
Retrieves this datagram's datagram ID.

Returns:
This datagram's datagram ID.
Since:
BlackBerry API 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
See Also:
DatagramBase.simpleReset()
Since:
BlackBerry API 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.

See Also:
DatagramBase.reset()
Since:
BlackBerry API 4.0.0

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

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
Throws:
IOException
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.