net.rim.device.api.io
Class DatagramConnectionBase

java.lang.Object
  net.rim.device.api.io.DatagramConnectionBase

All Implemented Interfaces:

Connection, DatagramConnection, UDPDatagramConnection, IOProperties

public abstract class DatagramConnectionBase
extends Object
implements DatagramConnection, IOProperties, UDPDatagramConnection

Contains methods that handle BlackBerry Datagram connection and transmission operations.

The parameter string 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".

The following examples describe how to create UDP connections on a BlackBerry.

A datagram connection for accepting datagrams udp://:1234

A datagram connection for sending to a server: udp://123.456.789.12:1234

Since:

BlackBerry API 4.0.0

Field Summary
protected static long	DEFAULT_TIMEOUT
protected DatagramAddressBase	_addressBase
protected int	_flags
protected boolean	_isActive
protected boolean	_isTimeOutSet
protected DatagramStatusListener	_listener
protected Hashtable	_properties
protected DatagramAddressBase	_receiveFilter
protected Datagram[]	_sendingDatagrams
protected long	_timeout
protected DatagramTransportBase	_transport
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

DatagramConnectionBase()
Creates a new DatagramConnectionBase instance.

Method Summary
int	allocateDatagramId(Datagram datagram) Allocates an ID for the provided datagram.
void	cancel(Datagram datagram) Attempts to cancel a sent datagram.
protected void	checkForClosed() Determines if the connection has been closed.
void	close() Closes the connection.
void	copyFlagsInto(DatagramBase dg) Copies flags from the connection to the datagram.
DatagramStatusListener	getDatagramStatusListener() Retrieves the status listener for this connection.
int	getFlag(int flag) Retrieves state of specified flags for this connection.
String	getLocalAddress() Retrieves local address.
int	getLocalPort() Retrieves local port.
int	getMaximumLength() Retrieves a datagram's maximum length.
int	getNominalLength() Retrieves a datagram's nominal length.
Object	getProperty(String name) Retrieves a property associated with the connection.
void	handleDatagramStatus(int datagramId, int event, Object context) Handles a status change event for a datagram.
protected boolean	isAddressed(String address) Determines if a received datagram is destined for the connection.
protected boolean	isAddressed(DatagramAddressBase address) Determines if a received datagram is destined for the connection.
boolean	isFlagSet(int flag) Determines if any of specified flags are set.
Datagram	newDatagram() Builds a new datagram object with an empty 0 byte buffer.
Datagram	newDatagram(byte[] buffer) Builds a new datagram object.
Datagram	newDatagram(byte[] buffer, int length) Builds a new datagram object.
Datagram	newDatagram(byte[] buffer, int offset, int length) Builds a new datagram object.
Datagram	newDatagram(byte[] buffer, int offset, int length, String address) Builds a new datagram object.
Datagram	newDatagram(byte[] buffer, int length, String address) Builds a new datagram object.
Datagram	newDatagram(int length) Builds a new datagram object automatically allocating a buffer.
Datagram	newDatagram(int length, String address) Builds a new datagram object.
DatagramAddressBase	newDatagramAddressBase(String address, boolean swap) Builds a new datagram address base from provided string.
DatagramAddressBase	newDatagramAddressBase(DatagramAddressBase addressBase, boolean swap) Builds a new datagram address base cloned from provided one.
Connection	openPrim(String name, int mode, boolean timeouts) Opens primary connection.
void	processReceivedDatagram(Datagram datagram) Processes received datagram.
void	receive(Datagram datagram) Receives a datagram.
void	send(Datagram datagram) Sends a datagram.
void	setDatagramStatusListener(DatagramStatusListener listener) Registers a status listener for this connection.
void	setFlag(int flag, boolean value) Sets state of specified flags for this connection.
Object	setProperty(String name, Object data) Associates a property with the connection.
void	setTimeout(long timeout) Sets the timeout value for this connection.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_TIMEOUT

protected static long DEFAULT_TIMEOUT

Since:

BlackBerry API 4.0.0

_addressBase

protected DatagramAddressBase _addressBase

Since:

BlackBerry API 4.0.0

_receiveFilter

protected DatagramAddressBase _receiveFilter

Since:

BlackBerry API 4.0.0

_transport

protected DatagramTransportBase _transport

Since:

BlackBerry API 4.0.0

_sendingDatagrams

protected Datagram[] _sendingDatagrams

Since:

BlackBerry API 4.0.2

_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

_timeout

protected long _timeout

Since:

BlackBerry API 4.0.0

_isActive

protected boolean _isActive

Since:

BlackBerry API 4.0.0

_listener

protected DatagramStatusListener _listener

Since:

BlackBerry API 4.0.0

_isTimeOutSet

protected boolean _isTimeOutSet

Since:

BlackBerry API 4.0.0

Constructor Detail

DatagramConnectionBase

public DatagramConnectionBase()

Creates a new DatagramConnectionBase instance.

Since:

BlackBerry API 4.0.0

Method Detail

openPrim

public Connection openPrim(String name,
                           int mode,
                           boolean timeouts)
                    throws IOException

Opens primary connection.

Note: This method is overriden in some subclasses to create protocol-specific Connection classes.

Parameters:

name - Address base name.

mode - Mode

timeouts - Use timeouts for this connection.

Returns:

New connection.

Throws:

IOException - If unable to find underlying transport class.

Since:

BlackBerry API 4.0.0

close

public void close()
           throws IOException

Closes the connection.

When the connection has been closed the behaviour of all methods except this one is undefined. Closing an already closed connection has no effect. Streams derived from a connection may remain open after this method is called. This may cause the connection to remain open (but access to its methods are rejected) until any derived streams are closed themselves.

Specified by:

close in interface Connection

Throws:

IOException - If an I/O error occurs.

Since:

BlackBerry API 4.0.0

getMaximumLength

public int getMaximumLength()
                     throws IOException

Retrieves a datagram's maximum length.

Specified by:

getMaximumLength in interface DatagramConnection

Returns:

Maximum datagram length.

Throws:

IOException - If an I/O error occurs.

Since:

BlackBerry API 4.0.0

getNominalLength

public int getNominalLength()
                     throws IOException

Retrieves a datagram's nominal length.

Specified by:

getNominalLength in interface DatagramConnection

Returns:

Nominal datagram length.

Throws:

IOException - If an I/O error occurs.

Since:

BlackBerry API 4.0.0

send

public void send(Datagram datagram)
          throws IOException

Sends a datagram.

Specified by:

send in interface DatagramConnection

Parameters:

datagram - Datagram to send.

Throws:

IOException - If an I/O error occurs.

IOCancelledException - If the datagram was cancelled.

IOFormatException - Bad length or address.

InterruptedIOException - Timeout or upon closing the connection with outstanding I/O.

Since:

BlackBerry API 4.0.0

cancel

public void cancel(Datagram datagram)
            throws IOException

Attempts to cancel a sent datagram.

Note: This method cannot guarantee to cancel your provided datagram; at some point in the sending process, the datagram becomes uncancellable.

Parameters:

datagram - Datagram to cancel.

Throws:

IOException - If an I/O error occurs.

Since:

BlackBerry API 4.0.0

isAddressed

protected boolean isAddressed(String address)

Determines if a received datagram is destined for the connection. This function is called by the underlying protocol when a datagram event is received.

Parameters:

address - the address for the datagram.

Returns:

true if the datagram is intended for the connection and invoking receive() will retrieve the datagram, or false if the connection will not receive the datagram.

Since:

BlackBerry API 4.0.0

isAddressed

protected boolean isAddressed(DatagramAddressBase address)

Determines if a received datagram is destined for the connection.

Parameters:

address - the address for the datagram.

Returns:

true if the datagram is intended for the connection and invoking receive() will retrieve the datagram, or false if the connection will not receive the datagram.

Since:

BlackBerry API 4.0.0

receive

public void receive(Datagram datagram)
             throws IOException

Receives a datagram.

Specified by:

receive in interface DatagramConnection

Parameters:

datagram - Datagram object to contain the contents of a received datagram.

Throws:

IOException - If an I/O error occurs.

InterruptedIOException - Timeout or upon closing the connection with outstanding I/O.

Since:

BlackBerry API 4.0.0

newDatagram

public Datagram newDatagram()
                     throws IOException

Builds a new datagram object with an empty 0 byte buffer.

Returns:

New, empty datagram.

Throws:

IOException - If an I/O error occurs.

Since:

BlackBerry API 4.0.0

newDatagram

public Datagram newDatagram(int length)
                     throws IOException

Builds a new datagram object automatically allocating a buffer.

Note: Although the underlying buffer in the returned datagram will have enough space to contain elements equal to your provided length, its starting length will be zero becuase it's emtpy when created.

Specified by:

newDatagram in interface DatagramConnection

Parameters:

length - Length of the buffer to allocate for the datagram.

Returns:

New datagram.

Throws:

IOException - If an I/O error occurs.

IllegalArgumentException - If the length is negative.

Since:

BlackBerry API 4.0.0

newDatagram

public Datagram newDatagram(int length,
                            String address)
                     throws IOException

Builds a new datagram object.

Note: Although the underlying buffer in the returned datagram will have enough space to contain elements equal to your provided length, its starting length will be zero becuase it's emtpy when created.

Specified by:

newDatagram in interface DatagramConnection

Parameters:

length - Length of the buffer to be allocated for the datagram.

address - Address to which the datagram must go.

Returns:

New datagram.

Throws:

IOException - If an I/O error occurs.

IllegalArgumentException - If the length is negative.

Since:

BlackBerry API 4.0.0

newDatagram

public Datagram newDatagram(byte[] buffer)
                     throws IOException

Builds a new datagram object.

Parameters:

buffer - Buffer to use for the datagram.

Returns:

New datagram with length equal to the length of your provided data buffer.

Throws:

IOException - If an I/O error occurs.

Since:

BlackBerry API 4.0.0

newDatagram

public Datagram newDatagram(byte[] buffer,
                            int length)
                     throws IOException

Builds a new datagram object.

Specified by:

newDatagram in interface DatagramConnection

Parameters:

buffer - Buffer to use for the datagram.

length - Length of the buffer to allocate for the datagram (should not be larger than the actual length of the buffer passed in).

Returns:

New datagram with length equal to the smaller of your length or the buffer provided.

Throws:

IOException - If an I/O error occurs.

IllegalArgumentException - If the length is negative.

Since:

BlackBerry API 4.0.0

newDatagram

public Datagram newDatagram(byte[] buffer,
                            int length,
                            String address)
                     throws IOException

Builds a new datagram object.

Specified by:

newDatagram in interface DatagramConnection

Parameters:

buffer - Buffer to use for the datagram.

length - Length of the buffer to allocate for the datagram (should not be larger than the actual length of the buffer passed in).

address - Address to which the datagram must go.

Returns:

New datagram with length equal to the smaller of your length or the buffer provided.

Throws:

IOException - If an I/O error occurs.

IllegalArgumentException - If the length or offset is negative.

Since:

BlackBerry API 4.0.0

newDatagram

public Datagram newDatagram(byte[] buffer,
                            int offset,
                            int length)
                     throws IOException

Builds a new datagram object.

Parameters:

buffer - Buffer to use for the datagram.

offset - Offset into the buffer the datagram should start at.

length - Length of the buffer to allocate for the datagram (should not be larger than the actual length of the buffer passed in).

Returns:

New datagram with length equal to the smaller of your length or the buffer provided.

Throws:

IOException - If an I/O error occurs.

IllegalArgumentException - If the length or offset is negative.

Since:

BlackBerry API 4.0.0

newDatagram

public Datagram newDatagram(byte[] buffer,
                            int offset,
                            int length,
                            String address)
                     throws IOException

Builds a new datagram object.

Parameters:

buffer - Buffer to use for the datagram.

offset - Offset into the buffer the datagram should start at.

length - Length of the buffer to allocate for the datagram (should not be larger than the actual length of the buffer passed in).

address - Address to which the datagram must go.

Returns:

A new datagram with length equal to the smaller of your length or the buffer provided.

Throws:

IOException - If an I/O error occurs.

IllegalArgumentException - If the length or offset is negative.

Since:

BlackBerry API 4.0.0

newDatagramAddressBase

public DatagramAddressBase newDatagramAddressBase(String address,
                                                  boolean swap)

Builds a new datagram address base from provided string.

Parameters:

address - String to form new address base..

swap - If true, swap source information for destination information in returned addres base; otherwise, produce exact clone.

Returns:

New address base.

Since:

BlackBerry API 4.0.0

newDatagramAddressBase

public DatagramAddressBase newDatagramAddressBase(DatagramAddressBase addressBase,
                                                  boolean swap)

Builds a new datagram address base cloned from provided one.

Parameters:

addressBase - Address base to clone.

swap - If true, swap source information for destination information in returned address base; otherwise, produce exact clone.

Returns:

New address base.

Since:

BlackBerry API 4.0.0

processReceivedDatagram

public void processReceivedDatagram(Datagram datagram)

Processes received datagram.

Parameters:

datagram - Datagram to process.

Since:

BlackBerry API 4.0.0

setProperty

public Object setProperty(String name,
                          Object data)

Associates a property with the connection.

Specified by:

setProperty in interface IOProperties

Parameters:

name - Name for the property.

data - Data for the named property; if the named property already exists, and you provide null for this parameter, the property gets removed.

Returns:

Property's previously associated data, or null if the property did not exist before calling this method.

Since:

BlackBerry API 4.0.0

getProperty

public Object getProperty(String name)

Retrieves a property associated with the connection.

Specified by:

getProperty in interface IOProperties

Parameters:

name - Property's name.

Returns:

Named property's data, or null if property doesn't exist.

Since:

BlackBerry API 4.0.0

setFlag

public void setFlag(int flag,
                    boolean value)

Sets state of specified flags for this connection.

Specified by:

setFlag in interface IOProperties

Parameters:

flag - Bit mask specifying which flags to modify.

value - New value for each flag specified in the mask.

Since:

BlackBerry API 4.0.0

getFlag

public int getFlag(int flag)

Retrieves state of specified flags for this connection.

Specified by:

getFlag in interface IOProperties

Parameters:

flag - Bit mask of flags to query.

Returns:

IOProperties.FLAG_INVALID if none of the flags specified in the mask exist, or IOProperties.FLAG_SET if any of the flags are set, or IOProperties.FLAG_UNSET if none of the flags are set.

Since:

BlackBerry API 4.0.0

isFlagSet

public boolean isFlagSet(int flag)

Determines if any of specified flags are set.

Specified by:

isFlagSet in interface IOProperties

Parameters:

flag - Bit mask of flags to check.

Returns:

True if any flag in the mask is set; otherwise, false.

Since:

BlackBerry API 4.0.0

setTimeout

public void setTimeout(long timeout)

Sets the timeout value for this connection.

Note: This only has an effect if the connection was created with timeouts turned on.

Parameters:

timeout - New timeout value in milliseconds (specifying a value of 0 effectively turns off timeouts).

Since:

BlackBerry API 4.0.0

setDatagramStatusListener

public void setDatagramStatusListener(DatagramStatusListener listener)

Registers a status listener for this connection.

Parameters:

listener - Status listener to register.

Since:

BlackBerry API 4.0.0

getDatagramStatusListener

public DatagramStatusListener getDatagramStatusListener()

Retrieves the status listener for this connection.

Returns:

Status listener registered for this connection, or null if no listener registered.

Since:

BlackBerry API 4.0.0

allocateDatagramId

public int allocateDatagramId(Datagram datagram)

Allocates an ID for the provided datagram.

You may need to invoke this method just before the sending the datagram as the ID may depend on the contents of the datagram. Check the implementation of the getNextDatagramId method in the underlying Transport object for more information.

If this method returns DatagramBase.DG_NULL_ID then the datagram has no ID and the underlying connection does not support listeners.

Parameters:

datagram - Datagram to receive ID.

Returns:

ID given to the specified datagram.

Since:

BlackBerry API 4.0.0

handleDatagramStatus

public void handleDatagramStatus(int datagramId,
                                 int event,
                                 Object context)

Handles a status change event for a datagram.

Parameters:

datagramId - Datagram ID.

event - Event code for the status change event.

context - Any context associated with the status event.

Since:

BlackBerry API 4.0.0

copyFlagsInto

public void copyFlagsInto(DatagramBase dg)

Copies flags from the connection to the datagram.

Any valid flags in the connection are copied into the given datagram, as long as the flag is not already set in the datagram. This allows setting a default value for a flag in a connection that can be overriden by the datagram.

Parameters:

dg - Datagram base to receive the copied flags.

Since:

BlackBerry API 4.0.0

getLocalAddress

public String getLocalAddress()
                       throws IOException

Retrieves local address.

Specified by:

getLocalAddress in interface UDPDatagramConnection

Returns:

Local address for this connection.

Throws:

IOException - if the connection was closed.

See Also:

ServerSocketConnection

Since:

BlackBerry API 4.0.0

getLocalPort

public int getLocalPort()
                 throws IOException

Retrieves local port.

Specified by:

getLocalPort in interface UDPDatagramConnection

Returns:

Local port for this connection.

Throws:

IOException - if the connection was closed.

See Also:

ServerSocketConnection

Since:

BlackBerry API 4.0.0

checkForClosed

protected void checkForClosed()
                       throws IOException

Determines if the connection has been closed. If the connection has been closed, this method throws an IOException; otherwise, the method does nothing.

Throws:

IOException

Since:

BlackBerry API 4.0.0