net.rim.device.api.io
Class DatagramConnectionBase

java.lang.Object
  extended by 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





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal