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:

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