org.ka2ddo.ax25
Class AX25Stack

java.lang.Object
  extended by org.ka2ddo.ax25.AX25Stack
All Implemented Interfaces:
java.lang.Runnable, FrameListener

public class AX25Stack
extends java.lang.Object
implements FrameListener, java.lang.Runnable

This class implements the internal AX.25 protocol stack for a TNC (layer 2). It does not implement the level 7 applications or any layer 3 protocols.


Method Summary
 void addAprsMessageListener(AprsMessageListener listener)
          Register an AprsMessageListener to be notified of incoming parsed APRS messages.
 void addAX25FrameListener(AX25FrameListener l)
          Add a listener for incoming AX.25 frames.
 void addParsedAX25MessageListener(ParsedAX25MessageListener listener)
          Register an ParsedAX25MessageListener to be notified of incoming parsed level 3 protocol messages (other than APRS).
 void consumeFrame(AX25Frame frame)
          Queue one AX.25 frame (containing some sort of message) for parsing and processing.
 void consumeFrameNow(Connector connector, AX25Frame frame)
          Process an incoming AX,25 frame.
 void fireConsumeAX25Frame(AX25Frame frame, Connector connector)
          Send the specified incoming frame to all registered AX25FrameListeners.
 java.util.Map<AX25Callsign,java.util.Map<AX25Callsign,ConnState>> getConnectionMap()
          Get the map of all outstanding I-frame connected sessions observed by or end-pointed at this station.
 int getCurrentBacklog()
          Return the current number of backlogged frames to be processed by the AX25Stack thread.
static java.lang.String[] getDigipeaters()
          Get the default list of digipeaters for this stack.
static AX25Stack getInstance()
          Get a handle to the AX25Stack singleton.
 int getMaxBacklog()
          Return the maximum backlog ever incurred by the AX25Stack parser thread.
 int getMaxQueueCapacity()
          Return the maximum allowed size of the queue.
 int getNumConsumedMsgs()
          Return the number of AX.25 messages consumed by the AX25Stack.
 AX25Parser getParser(byte pid)
          Get the protocol parsing handler for the specified protocol.
static ConnState.ConnType getStateOf(AX25Callsign src, AX25Callsign dst)
          Get the connection state of an I-frame connection session between the specified two callsigns.
static java.lang.String getToCall()
          Get the destination callsign (tocall) that should be used for messages originated by this station.
 boolean isFrozen()
          Report if parser thread is frozen.
static boolean isLocalDest(AX25Callsign dest)
          Test if this callsign is addressed to the local station.
static boolean isLocalDest(java.lang.String destCallsign)
          Test if this callsign is addressed to the local station.
 void openConnection(AX25Callsign src, AX25Callsign dest, AX25Callsign[] via, ConnectionEstablishmentListener callback, java.lang.Object sessionIdentifier)
          Attempt to initiate an I-frame connected-mode session from the specified source (usually, the local station) to another station by sending a SABM frame.
 void processAPRSPacket(AX25Frame frame, AX25Message aprsMsg)
          Send this message (and its associated frame) to the APRS consumers.
 boolean processIBody(AX25Frame frame, boolean isUI, Connector connector, long rcvTimestamp)
          This method consumes one information frame.
 void processParsedAX25Message(AX25Frame frame, AX25Message parsedMsg)
          Dispatch an AX.25 frame that was parsed into a higher-level protocol to all registered listeners.
 void registerProtocolParser(byte pid, AX25Parser parser)
          Register another protocol parsing handler for a particular AX.25 UI/I message PID.
 void removeAprsMessageListener(AprsMessageListener listener)
          Unregister an AprsMessageListener to be notified of incoming parsed APRS messages.
 void removeAX25FrameListener(AX25FrameListener l)
          Remove a listener for incoming AX.25 frames.
 void removeParsedAX25MessageListener(ParsedAX25MessageListener listener)
          Unregister an ParsedAX25MessageListener to be notified of incoming parsed level 3 protocol messages (other than APRS).
static AX25Callsign[] reverseDigipeaters(AX25Callsign[] srcRelays)
          Reverse the order of a sequence of digipeaters (explicit and APRS aliases).
 void run()
          Private method to asynchronously consume AX25Frame objects for parsing.
static void setDigipeaters(java.lang.String[] digipeaters)
          Set the default list of digipeaters for this stack.
 void setFrozen(boolean frozen)
          Specify whether the AX.25 parser thread should be paused (frozen) to allow the user to view the output without it moving constantly
static void setToCall(java.lang.String toCall)
          Set the destination callsign (tocall) that should be used for messages originated by this station.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getInstance

public static AX25Stack getInstance()
Get a handle to the AX25Stack singleton.

Returns:
AX25Stack instance

getDigipeaters

public static java.lang.String[] getDigipeaters()
Get the default list of digipeaters for this stack.

Returns:
array of String digipeater aliases supported by this stack

setDigipeaters

public static void setDigipeaters(java.lang.String[] digipeaters)
Set the default list of digipeaters for this stack.

Parameters:
digipeaters - array of String digipeater aliases

getToCall

public static java.lang.String getToCall()
Get the destination callsign (tocall) that should be used for messages originated by this station.

Returns:
destination callsign (tocall)

setToCall

public static void setToCall(java.lang.String toCall)
Set the destination callsign (tocall) that should be used for messages originated by this station.

Parameters:
toCall - destination callsign (tocall)

addAX25FrameListener

public void addAX25FrameListener(AX25FrameListener l)
Add a listener for incoming AX.25 frames.

Parameters:
l - AX25FrameListener to register

removeAX25FrameListener

public void removeAX25FrameListener(AX25FrameListener l)
Remove a listener for incoming AX.25 frames.

Parameters:
l - AX25FrameListener to unregister

registerProtocolParser

public void registerProtocolParser(byte pid,
                                   AX25Parser parser)
Register another protocol parsing handler for a particular AX.25 UI/I message PID.

Parameters:
pid - pid byte code for this protocol
parser - AX25Parser to handle receiving this protocol

getParser

public AX25Parser getParser(byte pid)
Get the protocol parsing handler for the specified protocol.

Parameters:
pid - level 3 protocol ID byte (as defined by the AX.25 protocol specification)
Returns:
AX25Parser object, or null if no parser registered for the specified protocol

fireConsumeAX25Frame

public void fireConsumeAX25Frame(AX25Frame frame,
                                 Connector connector)
Send the specified incoming frame to all registered AX25FrameListeners.

Parameters:
frame - AX25Frame to dispatch
connector - Connector that received the frame

consumeFrame

public void consumeFrame(AX25Frame frame)
Queue one AX.25 frame (containing some sort of message) for parsing and processing.

Specified by:
consumeFrame in interface FrameListener
Parameters:
frame - the AX25Frame to be processed

getCurrentBacklog

public int getCurrentBacklog()
Return the current number of backlogged frames to be processed by the AX25Stack thread.

Returns:
current queue size

getMaxBacklog

public int getMaxBacklog()
Return the maximum backlog ever incurred by the AX25Stack parser thread.

Returns:
maximum queue backlog

getMaxQueueCapacity

public int getMaxQueueCapacity()
Return the maximum allowed size of the queue.

Returns:
total capacity of the backlog queue

getNumConsumedMsgs

public int getNumConsumedMsgs()
Return the number of AX.25 messages consumed by the AX25Stack.

Returns:
count of messages consumed

run

public void run()
Private method to asynchronously consume AX25Frame objects for parsing. This tries to prevent back-pressuring any sources (particularly fast-moving TCP connections to APRS-IS servers). Can only be executed from the singleton thread created by this class.

Specified by:
run in interface java.lang.Runnable

isFrozen

public boolean isFrozen()
Report if parser thread is frozen.

Returns:
boolean true if parser thread is stopped

setFrozen

public void setFrozen(boolean frozen)
Specify whether the AX.25 parser thread should be paused (frozen) to allow the user to view the output without it moving constantly

Parameters:
frozen - boolean true to freeze the parser thread, or false to resume execution

consumeFrameNow

public void consumeFrameNow(Connector connector,
                            AX25Frame frame)
Process an incoming AX,25 frame.

Parameters:
connector - Connector that received the frame
frame - AX25Frame to process

getConnectionMap

public java.util.Map<AX25Callsign,java.util.Map<AX25Callsign,ConnState>> getConnectionMap()
Get the map of all outstanding I-frame connected sessions observed by or end-pointed at this station.

Returns:
Map by initiating callsign of Maps by destination callsign of connection states

getStateOf

public static ConnState.ConnType getStateOf(AX25Callsign src,
                                            AX25Callsign dst)
Get the connection state of an I-frame connection session between the specified two callsigns.

Parameters:
src - AX25Callsign of originating end of session
dst - AX25Callsign of receiving end of session
Returns:
ConnType of the session, or ConnType.NONE if there is no such connection session known to this protocol stack

reverseDigipeaters

public static AX25Callsign[] reverseDigipeaters(AX25Callsign[] srcRelays)
Reverse the order of a sequence of digipeaters (explicit and APRS aliases).

Parameters:
srcRelays - array of AX25Callsign indicating the path used to get from sender to recipient
Returns:
array of AX25Callsigns needed to go from recipient back to sender

processIBody

public boolean processIBody(AX25Frame frame,
                            boolean isUI,
                            Connector connector,
                            long rcvTimestamp)
This method consumes one information frame. The caller handles any flow control issues for I (versus UI) frames.

Parameters:
frame - AX25Frame to be decoded
isUI - where frame was received in a UI AX.25 frame instead of an I frame
connector - PortConnector over which message arrived, or null for file playback
rcvTimestamp - time (in Java-standard milliseconds since Jan 1 1970 UTC) that message was received
Returns:
boolean true if message has already been reported to listeners

processParsedAX25Message

public void processParsedAX25Message(AX25Frame frame,
                                     AX25Message parsedMsg)
Dispatch an AX.25 frame that was parsed into a higher-level protocol to all registered listeners.

Parameters:
frame - AX25Frame of incoming message
parsedMsg - AX25Message subclass containing protocol decoding of message

processAPRSPacket

public void processAPRSPacket(AX25Frame frame,
                              AX25Message aprsMsg)
Send this message (and its associated frame) to the APRS consumers.

Parameters:
frame - AX25Frame containing the APRS message
aprsMsg - Message that was sent

addAprsMessageListener

public void addAprsMessageListener(AprsMessageListener listener)
Register an AprsMessageListener to be notified of incoming parsed APRS messages.

Parameters:
listener - AprsMessageListener to register

removeAprsMessageListener

public void removeAprsMessageListener(AprsMessageListener listener)
Unregister an AprsMessageListener to be notified of incoming parsed APRS messages.

Parameters:
listener - AprsMessageListener to unregister

addParsedAX25MessageListener

public void addParsedAX25MessageListener(ParsedAX25MessageListener listener)
Register an ParsedAX25MessageListener to be notified of incoming parsed level 3 protocol messages (other than APRS).

Parameters:
listener - ParsedAX25MessageListener to register

removeParsedAX25MessageListener

public void removeParsedAX25MessageListener(ParsedAX25MessageListener listener)
Unregister an ParsedAX25MessageListener to be notified of incoming parsed level 3 protocol messages (other than APRS).

Parameters:
listener - ParsedAX25MessageListener to unregister

isLocalDest

public static boolean isLocalDest(AX25Callsign dest)
Test if this callsign is addressed to the local station.

Parameters:
dest - AX25Callsign to test as a destination
Returns:
boolean true if this callsign is for the local station

isLocalDest

public static boolean isLocalDest(java.lang.String destCallsign)
Test if this callsign is addressed to the local station.

Parameters:
destCallsign - String of AX.25 callsign-SSID to test as a destination
Returns:
boolean true if this callsign is for the local station

openConnection

public void openConnection(AX25Callsign src,
                           AX25Callsign dest,
                           AX25Callsign[] via,
                           ConnectionEstablishmentListener callback,
                           java.lang.Object sessionIdentifier)
                    throws java.io.IOException
Attempt to initiate an I-frame connected-mode session from the specified source (usually, the local station) to another station by sending a SABM frame.

Parameters:
src - AX25Callsign of originating station
dest - AX25Callsign of destination for connection
via - digipeater path (may be null)
callback - ConnectionEstablishmentListener to be notified of changes in state of the connection
sessionIdentifier - arbitrary unique identifier for the connection, so that the ConnectionEstablishmentListener can tell which connection is being reported about
Throws:
java.io.IOException - if connection initiation (SABM frame) could not be sent