|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectnet.rim.device.api.io.TransportBase
net.rim.device.api.io.DatagramTransportBase
public abstract class DatagramTransportBase
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).
DatagramConnectionBase| Field Summary | ||
|---|---|---|
long |
GUID
GUID for this object. |
|
protected String |
STR
|
|
protected DatagramConnectionBase |
_subConnection
The connection below. |
|
| 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(String address,
boolean swap)
Creates a new datagram address base given an address string. |
|
DatagramAddressBase |
newDatagramAddressBase(DatagramAddressBase addressBase,
boolean swap)
Creates a new datagram address base given an existing address base. |
|
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 DatagramTransportBase.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 |
| Methods inherited from interface net.rim.device.api.system.GlobalEventListener |
|---|
eventOccurred |
| Field Detail |
|---|
public long GUID
protected String STR
protected DatagramConnectionBase _subConnection
| Constructor Detail |
|---|
public DatagramTransportBase()
| Method Detail |
|---|
public abstract void init()
throws IOException
Sub-classes must implement this and have it invoke
init(subConnection).
init in class TransportBaseIOExceptionpublic void init(DatagramConnection subConnection)
Sub-classes must implement DatagramTransportBase.init() and have it invoke this method.
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.public void addConnection(DatagramConnection connection)
Note: This is public so that the
Protocol
sub-classes that override
openPrim()
can have access to addConnection().
connection - Super-connection to add.public void addSubConnection(DatagramConnectionBase connection)
connection - Sub-connection to add.
public void close(DatagramConnection connection)
throws IOException
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.
connection - Connection to close.
IOException - If an I/O error occurs.
public abstract int getMaximumLength()
throws IOException
IOException - If transport has already been closed.
public int getNominalLength()
throws IOException
IOException - If transport has already been closed.
protected void superSend(Datagram datagram)
throws IOException
datagram - Datagram to send.
IOException - If transport has already been closed.
IOCancelledException - If datagram has already been cancelled.
protected void send(Datagram datagram,
DatagramAddressBase addressBase,
IOProperties properties,
DatagramStatusListener listener,
int dgramId)
throws IOException
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.
IOException - If an I/O error occurs (for example, transport has
already been closed).
public abstract void send(Datagram datagram)
throws IOException
datagram - Datagram to send.
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.
public void superCancel(Datagram datagram)
throws IOException
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.
datagram - Datagram to cancel.
IOException - If an I/O error occurs (for example, transport has
already been closed).
public void cancel(Datagram datagram)
throws IOException
Sub-classes should implement this class if they wish to provide any hope of cancelling a datagram that's in the process of sending.
datagram - Datagram to cancel.
IOException - If an I/O error occurs.
protected void addDgramId(DatagramStatusListener listener,
int datagramId,
int subId)
listener - Status listener to add to mapping table.datagramID - Datagram ID listener should listen for.subId - ID for sub-datagram listener should listen for.
public Datagram newDatagram(byte[] buffer,
int offset,
int length,
String address)
throws IOException
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.
IOException - If an I/O error occurs.
IllegalArgumentException - If the length is negative or larger than
the buffer.
public DatagramAddressBase newDatagramAddressBase(String address,
boolean swap)
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.
public DatagramAddressBase newDatagramAddressBase(DatagramAddressBase addressBase,
boolean swap)
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.
protected boolean passUpDatagram(Datagram datagram)
datagram - Datagram involved in the event.
protected abstract void processReceivedDatagram(Datagram datagram)
throws IOException
datagram - Datagram received (note this method expects to receive a
Java ME datagram).
IOException - If an I/O error occurs.
public void superProcessReceivedDatagram(Datagram datagram)
throws IOException
DatagramTransportBase.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.
datagram - Datagram to process (note this method expects to receive
a Java ME datagram).
IOException - If an I/O error occurs.protected int getNextDatagramId(DatagramBase dgram)
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.
dgram - Datagram for which to retrieve the next valid ID.
DatagramBase.DG_NULL_ID; inheriting classes that provide
listener support must override this method and provide valid IDs.DatagramTransportBase.allocateDatagramId(javax.microedition.io.Datagram)public int allocateDatagramId(Datagram 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 DatagramTransportBase.getNextDatagramId(net.rim.device.api.io.DatagramBase) in the appropriate
inheriting class for more information.
datagram - Datagram for which to allocate an ID.
DatagramBase.DG_NULL_ID, then the datagram has no ID and the
underlying connection does not support listeners.DatagramTransportBase.getNextDatagramId(net.rim.device.api.io.DatagramBase)
protected void forwardDgslEvent(int index,
int event,
Object context)
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.
public void passDgslEvent(int subId,
int event,
Object context)
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.
public void xmitDgslEvent(DatagramStatusListener listener,
int datagramId,
int event,
Object context)
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.protected int lookupDgramIndexFromSubId(int subId)
subId - ID for sub-datagram.
protected int lookupDgramIndexFromDgramId(int datagramId)
datagramId - ID for datagram.
protected int getDgramIdByIndex(int index)
index - Index of datagram.
protected void addSendRequest(Object sendObj,
Datagram datagram)
sendObject - Send object for request.datagram - Datagram to send.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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.