net.rim.device.api.io
Class DatagramTransportBase

java.lang.Object
  |
  +--net.rim.device.api.io.TransportBase
        |
        +--net.rim.device.api.io.DatagramTransportBase
All Implemented Interfaces:
GlobalEventListener

public abstract class DatagramTransportBase
extends TransportBase
implements GlobalEventListener

Provides a base implementation for a transport protocol.

This class contains all connection independent code/data required for a protocol. Upon instantiation, DatagramConnectionBase expects to find a DatagramTransportBase (or a sub-class of DatagramTransportBase).

Since:
JDE 4.0.0
See Also:
DatagramConnectionBase

Field Summary
protected  DatagramConnectionBase _subConnection
          The connection below.
 long GUID
          GUID for this object.
protected  String STR
           
 
Constructor Summary
DatagramTransportBase()
           
 
Method Summary
 void addConnection(DatagramConnection connection)
          Adds a super-connection to the protocol.
protected  void addDgramId(DatagramStatusListener listener, int datagramId, int subId)
          Adds an entry to the datagram status listener mapping table.
protected  void addSendRequest(Object sendObj, Datagram datagram)
          Adds a request to send a datagram to the send queue.
 void addSubConnection(DatagramConnectionBase connection)
          Adds a sub-connection to the protocol.
 int allocateDatagramId(Datagram datagram)
          Allocates an ID for provided datagram.
 void cancel(Datagram datagram)
          Attempts to cancel sending a datagram.
 void close(DatagramConnection connection)
          Closes the connection.
protected  void forwardDgslEvent(int index, int event, Object context)
          Forwards a datagram status event to a listener in the mapping table identified by index.
protected  int getDgramIdByIndex(int index)
          Retrieves ID of datagram from provided datagram index.
abstract  int getMaximumLength()
          Retrieves the maximum length for a datagram.
protected  int getNextDatagramId(DatagramBase dgram)
          Retrieves next valid datagram ID for provided datagram.
 int getNominalLength()
          Retrieves the nominal length of a datagram.
abstract  void init()
          Initializes this transport base.
 void init(DatagramConnection subConnection)
          Initializes this transport base with provided sub-connection.
protected  int lookupDgramIndexFromDgramId(int datagramId)
          Retrieves index of datagram from provided datagram ID.
protected  int lookupDgramIndexFromSubId(int subId)
          Retrieves index of datagram from provided sub-datagram ID.
 Datagram newDatagram(byte[] buffer, int offset, int length, String address)
          Makes a new datagram object.
 DatagramAddressBase newDatagramAddressBase(DatagramAddressBase addressBase, boolean swap)
          Creates a new datagram address base given an existing address base.
 DatagramAddressBase newDatagramAddressBase(String address, boolean swap)
          Creates a new datagram address base given an address string.
 void passDgslEvent(int subId, int event, Object context)
          Passes a datagram status event to a listener in the mapping table identified by sub-datagram ID.
protected  boolean passUpDatagram(Datagram datagram)
          Passes an event up to all the super-connections.
protected abstract  void processReceivedDatagram(Datagram datagram)
          Process a received datagram from the sub-connection.
abstract  void send(Datagram datagram)
          Sends a datagram.
protected  void send(Datagram datagram, DatagramAddressBase addressBase, IOProperties properties, DatagramStatusListener listener, int dgramId)
          Sends provided datagram with address base, properties, listener for events, and datagram ID.
 void superCancel(Datagram datagram)
          Attempts to cancel sending a datagram sent on super-connection.
 void superProcessReceivedDatagram(Datagram datagram)
          Logs the datagram and then hands it off to processReceivedDatagram(javax.microedition.io.Datagram).
protected  void superSend(Datagram datagram)
          Sends datagram along super-connection.
 void xmitDgslEvent(DatagramStatusListener listener, int datagramId, int event, Object context)
          Transmits a datagram status event to the specified listener.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail


_subConnection

protected DatagramConnectionBase _subConnection
The connection below.
Since:
JDE 4.0.0

GUID

public long GUID
GUID for this object.
Since:
JDE 4.0.0

STR

protected String STR
Since:
JDE 4.0.0
Constructor Detail

DatagramTransportBase

public DatagramTransportBase()
Since:
JDE 4.0.0
Method Detail

addConnection

public void addConnection(DatagramConnection connection)
Adds a super-connection to the protocol.

Note: This is public so that the Protocol sub-classes that override openPrim() can have access to addConnection().

Parameters:
connection - Super-connection to add.
Since:
JDE 4.0.0

addDgramId

protected void addDgramId(DatagramStatusListener listener,
                          int datagramId,
                          int subId)
Adds an entry to the datagram status listener mapping table.
Parameters:
listener - Status listener to add to mapping table.
datagramID - Datagram ID listener should listen for.
subId - ID for sub-datagram listener should listen for.
Since:
JDE 4.0.0

addSendRequest

protected void addSendRequest(Object sendObj,
                              Datagram datagram)
Adds a request to send a datagram to the send queue.
Parameters:
sendObject - Send object for request.
datagram - Datagram to send.
Since:
JDE 4.0.0

addSubConnection

public void addSubConnection(DatagramConnectionBase connection)
Adds a sub-connection to the protocol.
Parameters:
connection - Sub-connection to add.
Since:
JDE 4.0.0

allocateDatagramId

public int allocateDatagramId(Datagram datagram)
Allocates an ID for provided datagram.

You may need to invoke this method just before the datagram gets sent as the ID may depend on the contents of the datagram. Check the implementation of getNextDatagramId(net.rim.device.api.io.DatagramBase) in the appropriate inheriting class for more information.

Parameters:
datagram - Datagram for which to allocate an ID.
Returns:
ID allocated for your datagram; if this method returns DatagramBase.DG_NULL_ID, then the datagram has no ID and the underlying connection does not support listeners.
Since:
JDE 4.0.0
See Also:
getNextDatagramId(net.rim.device.api.io.DatagramBase)

cancel

public void cancel(Datagram datagram)
            throws IOException
Attempts to cancel sending a datagram.

Sub-classes should implement this class if they wish to provide any hope of cancelling a datagram that's in the process of sending.

Parameters:
datagram - Datagram to cancel.
Throws:
IOException - If an I/O error occurs.
Since:
JDE 4.0.0

close

public void close(DatagramConnection connection)
           throws IOException
Closes the connection.

When the connection has been closed, invoking any method but this one causes this transport base to throw an IOException. Closing an already closed connection has no effect. Streams derived from a connection may remain open after this method is invoked. This may cause the connection to remain open (but access to its methods are rejected) until any derived streams are closed themselves.

Parameters:
connection - Connection to close.
Throws:
IOException - If an I/O error occurs.
Since:
JDE 4.0.0

forwardDgslEvent

protected void forwardDgslEvent(int index,
                                int event,
                                Object context)
Forwards a datagram status event to a listener in the mapping table identified by index.
Parameters:
index - Index into the mapping table; if that entry in the table has no listener in it, your event gets sent to all open connections.
event - Status event to send.
context - Context associated with the status event, if any.
Since:
JDE 4.0.0

getDgramIdByIndex

protected int getDgramIdByIndex(int index)
Retrieves ID of datagram from provided datagram index.
Parameters:
index - Index of datagram.
Returns:
ID for datagram, or 0 if no such datagram.
Since:
JDE 4.0.0

getMaximumLength

public abstract int getMaximumLength()
                              throws IOException
Retrieves the maximum length for a datagram.
Returns:
Maximum length of a datagram.
Throws:
IOException - If transport has already been closed.
Since:
JDE 4.0.0

getNextDatagramId

protected int getNextDatagramId(DatagramBase dgram)
Retrieves next valid datagram ID for provided datagram.

This method should either return the next valid ID if this transport supports listeners, or DatagramBase.DG_NULL_ID if it does not support listeners.

You may need to invoke this method just before the datagram gets sent as the ID may depend on the contents of the datagram. Check the implementation of the appropriate sub-class for details; if the sub-class does not override this method, then it does not support listeners.

Parameters:
dgram - Datagram for which to retrieve the next valid ID.
Returns:
DatagramBase.DG_NULL_ID; inheriting classes that provide listener support must override this method and provide valid IDs.
Since:
JDE 4.0.0
See Also:
allocateDatagramId(javax.microedition.io.Datagram)

getNominalLength

public int getNominalLength()
                     throws IOException
Retrieves the nominal length of a datagram.
Returns:
Nominal length of a datagram.
Throws:
IOException - If transport has already been closed.
Since:
JDE 4.0.0

init

public abstract void init()
                   throws IOException
Initializes this transport base.

Sub-classes must implement this and have it invoke init(subConnection).

Since:
JDE 4.0.0

init

public void init(DatagramConnection subConnection)
Initializes this transport base with provided sub-connection.

Sub-classes must implement init() and have it invoke this method.

Parameters:
subConnection - Sub-connection this transport base talks to, or null if this transport base doesn't talk to a sub-connection. The provided sub-connection must inherit from DatagramConnectionBase.
Since:
JDE 4.0.0

lookupDgramIndexFromDgramId

protected int lookupDgramIndexFromDgramId(int datagramId)
Retrieves index of datagram from provided datagram ID.
Parameters:
datagramId - ID for datagram.
Returns:
Index for datagram or -1 if the index is not found.
Since:
JDE 4.0.0

lookupDgramIndexFromSubId

protected int lookupDgramIndexFromSubId(int subId)
Retrieves index of datagram from provided sub-datagram ID.
Parameters:
subId - ID for sub-datagram.
Returns:
Index for original datagram or -1 if no such datagram.
Since:
JDE 4.0.0

newDatagram

public Datagram newDatagram(byte[] buffer,
                            int offset,
                            int length,
                            String address)
                     throws IOException
Makes a new datagram object.
Parameters:
buffer - Buffer to use for the new datagram.
offset - First byte in the buffer to use for the new datagram.
length - Number of bytes in the buffer to use for the new datagram.
address - Recipient address for the new datagram.
Returns:
Newly created datagram.
Throws:
IOException - If an I/O error occurs.
IllegalArgumentException - If the length is negative or larger than the buffer.
Since:
JDE 4.0.0

newDatagramAddressBase

public DatagramAddressBase newDatagramAddressBase(DatagramAddressBase addressBase,
                                                  boolean swap)
Creates a new datagram address base given an existing address base.
Parameters:
address - Address base from which to form new one.
swap - If true, invokes DatagramAddressBase#swap on newly created address base before retrieval; otherwise, does not.
Returns:
Newly created address base.
Since:
JDE 4.0.0

newDatagramAddressBase

public DatagramAddressBase newDatagramAddressBase(String address,
                                                  boolean swap)
Creates a new datagram address base given an address string.
Parameters:
address - Address name from which to form a new address base.
swap - If true, invokes DatagramAddressBase#swap on newly created address base before retrieval; otherwise, does not.
Returns:
Newly created address base.
Since:
JDE 4.0.0

passDgslEvent

public void passDgslEvent(int subId,
                          int event,
                          Object context)
Passes a datagram status event to a listener in the mapping table identified by sub-datagram ID.
Parameters:
subId - Sub-datagram ID associated with listener to receive the event: if no table entry exists for this sub-datagram's ID, then this method returns without sending the event; if a table entry exists for the sub-datagam's ID, but has no assocated listener, then your event gets sent to all open connections.
event - Status event to send.
context - Context associated with the status event, if any.
Since:
JDE 4.0.0

passUpDatagram

protected boolean passUpDatagram(Datagram datagram)
Passes an event up to all the super-connections.
Parameters:
datagram - Datagram involved in the event.
Returns:
True if a connection accepted the datagram; otherwise, false
Since:
JDE 4.0.0

processReceivedDatagram

protected abstract void processReceivedDatagram(Datagram datagram)
                                         throws IOException
Process a received datagram from the sub-connection.
Parameters:
datagram - Datagram received (note this method expects to receive a Java ME datagram).
Throws:
IOException - If an I/O error occurs.
Since:
JDE 4.0.0

send

public abstract void send(Datagram datagram)
                   throws IOException
Sends a datagram.
Parameters:
datagram - Datagram to send.
Throws:
IOException - If an I/O error occurs (for example, transport has already been closed).
IOCancelledException - If the datagram was cancelled.
IOFormatException - If datagram has bad length or address.
InterruptedIOException - Timeout or upon closing the connection with outstanding I/O.
Since:
JDE 4.0.0

send

protected void send(Datagram datagram,
                    DatagramAddressBase addressBase,
                    IOProperties properties,
                    DatagramStatusListener listener,
                    int dgramId)
             throws IOException
Sends provided datagram with address base, properties, listener for events, and datagram ID.
Parameters:
datagram - Datagram to send.
addressBase - Address base to use.
properties - Properties for transmission.
listener - Listener to receive status events for this transmission.
dgramId - ID identifying datagram to be passed back to listener in status events.
Throws:
IOException - If an I/O error occurs (for example, transport has already been closed).
Since:
JDE 4.0.0

superCancel

public void superCancel(Datagram datagram)
                 throws IOException
Attempts to cancel sending a datagram sent on super-connection.

This method looks throught the send list for the super connection for your provided datagram; if it's found, then this method removes it from the list.

Note: this method is not guaranteed to cancel a sent datagram; if the datagram has already been transmitted, it no longer exists in the send queue, and therefore cannot be cancelled. Also, datagrams in the process of transmission are not guaranteed to be cancellable.

Parameters:
datagram - Datagram to cancel.
Throws:
IOException - If an I/O error occurs (for example, transport has already been closed).
Since:
JDE 4.0.0

superProcessReceivedDatagram

public void superProcessReceivedDatagram(Datagram datagram)
                                  throws IOException
Logs the datagram and then hands it off to processReceivedDatagram(javax.microedition.io.Datagram).

If a traffic logger has been registered with this transport, this method logs the provided datagram and then hands it off to be processed.

Parameters:
datagram - Datagram to process (note this method expects to receive a Java ME datagram).
Throws:
IOException - If an I/O error occurs.
Since:
JDE 4.0.0

superSend

protected void superSend(Datagram datagram)
                  throws IOException
Sends datagram along super-connection.
Parameters:
datagram - Datagram to send.
Throws:
IOException - If transport has already been closed.
IOCancelledException - If datagram has already been cancelled.
Since:
JDE 4.0.0

xmitDgslEvent

public void xmitDgslEvent(DatagramStatusListener listener,
                          int datagramId,
                          int event,
                          Object context)
Transmits a datagram status event to the specified listener.
Parameters:
listener - Status listener to receive the event; if null, this method sends your event to all open connections.
datagramId - ID for datagram invovled in the event.
event - Status event to send.
context - Context associated with the status event, if any.
Since:
JDE 4.0.0



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.