org.ka2ddo.yaac.ax25
Class StationTracker

java.lang.Object
  extended by org.ka2ddo.yaac.ax25.StationTracker
All Implemented Interfaces:
java.lang.Iterable<StationState>, AprsMessageListener, ParsedAX25MessageListener

public class StationTracker
extends java.lang.Object
implements java.lang.Iterable<StationState>, AprsMessageListener, ParsedAX25MessageListener

This class manages tracking all heard APRS stations and objects/items. It keeps a time-ordered and callsign-searchable index of all stations, with the messages associated with each station in reverse chronological order, along with an assembled current state of the station.


Nested Class Summary
static class StationTracker.AddressStatistics<K,C extends StationTracker.AddressStatistics>
          This abstract class collects the occurrence counts for a particular type of station.
static class StationTracker.DestinationStatistics
          Usage statistics for a particular tocall (destination) callsign in AX.25 traffic.
static class StationTracker.DigipeatStatistics
          Address statistics for a particular digipeater.
 
Field Summary
protected  java.util.HashMap<java.lang.String,StationState> stationMap
           
 
Method Summary
 void addDestinationListener(DestinationListener l)
          Register a listener that wants to know when a new tocall or explicit network destination is recorded.
 StationState addMessage(java.lang.String identifier, AX25Message msg, AX25Callsign[] digipeaters, boolean upshiftIdentifier)
          Register a message with the appropriate sending station.
 void addNewDestination(java.lang.String dest)
          Add a new destination to the map of destination callsigns and statistics.
 StationState addNewStationIfNeeded(java.lang.String callsign)
          Get the current StationState record for the specified station or object, creating a new record if one doesn't currently exist.
 void addRelayListener(DigipeatListener l)
          Register a listener that wants to know when a new digipeater is recorded.
 void addTrackerListener(TrackerListener l)
          Register a listener to be informed of changes to the station histories.
 void aprsMessageReceived(Message msg)
          Delivers the next message received by YAAC that is an APRS message.
 void deleteStation(StationState ss)
          Remove the specified station or object from the tracked history immediately.
protected  void fireMessageAdded(StationState ss, int index, AX25Message msg)
          Inform all registered TrackerListener instances that a new message has arrived from the specified station or about the specified object.
protected  void fireMessageDeleted(StationState ss, int index, AX25Message msg)
          Inform all registered TrackerListener instances that an old message has been deleted from the specified station or about the specified object.
protected  void fireStationAdded(StationState ss, int index)
          Inform all registered TrackerListener instances that a new station or object has been added to the tracker.
 void fireStationDeleted(StationState ss, int index)
          Inform all registered TrackerListener instances that a station or object's state is being deleted due to lack of activity,
 void fireStationUpdated(StationState ss)
          Inform all registered TrackerListener instances that a station's status is being updated.
 java.util.Set<java.lang.String> getCurrentNameSet()
          Get a Set of all the identifiers of stations and objects currently known.
 StationState[] getCurrentTrackedObjectArray()
          Get an array of all the known StationState objects.
 StationState[] getCurrentTrackedObjectArray(boolean includeStations, boolean includeObjects, boolean includeSelf, Filter filter, java.util.Comparator<StationState> sortComparator)
          Get an array of a selected filtered subset of the known StationState instances.
 java.util.ArrayList<StationState> getCurrentTrackedObjectList()
          Get a list of all the known StationState objects.
 java.util.HashMap<java.lang.String,StationTracker.DestinationStatistics> getDestinationsMap()
          Get the raw Map of destination callsigns to statistics counters.
 java.util.Set<java.lang.String> getDestinationsStringSet()
          Get the sorted set of all destination callsign strings.
 java.lang.String[] getDirectStationList(long now)
          Get a list of all stations heard directly by this station.
 java.util.HashMap<java.lang.String,StationTracker.DigipeatStatistics> getFinalSendersMap()
          Get the map of last digipeater statistics
 java.util.Set<java.lang.String> getFinalSendersSet()
          Get all the callsigns of the final digipeaters/I-gates used by all stations in the history.
static StationTracker getInstance()
          Get the singleton instance of the StationTracker.
 RadiusFilter getRangeLimitFilter()
          Get a reference to the RadiusFilter used for deciding if a station or object has changed between being in-range and out-of-range.
 int getStationTypeCount(char symTableId, char symbolCode)
          Count the number of known stations of a specified type.
 StationState getTrackedObject(java.lang.String name)
          Get the state object for the specified station or object.
 java.util.Iterator<StationState> iterator()
          Returns an iterator over a set of elements of type StationState.
 void parsedAX25MessageReceived(byte pid, AX25Message msg)
          Delivers the next message received by YAAC that is some sort of parsed AX.25 higher-level message.
 void purgeStaleTraffic()
          Delete all cached messages older than the purge threshold.
 void removeDestinationListener(DestinationListener l)
          Remove a listener that no longer wants to know when a new tocall or explicit network destination is recorded.
 void removeRelayListener(DigipeatListener l)
          Unregister a listener that no longer wants to know when a new digipeater is recorded.
 void removeTrackerListener(TrackerListener l)
          Unregister a listener.
 java.lang.String toString()
          Return String describing the StationTracker object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

stationMap

protected final java.util.HashMap<java.lang.String,StationState> stationMap
Method Detail

purgeStaleTraffic

public void purgeStaleTraffic()
Delete all cached messages older than the purge threshold.


getTrackedObject

public StationState getTrackedObject(java.lang.String name)
Get the state object for the specified station or object.

Parameters:
name - callsign or identifier for the desired station or object
Returns:
StationState of the desired object, or null if the identifier is not currently known

getCurrentNameSet

public java.util.Set<java.lang.String> getCurrentNameSet()
Get a Set of all the identifiers of stations and objects currently known.

Returns:
Set of identifier Strings

getCurrentTrackedObjectList

public java.util.ArrayList<StationState> getCurrentTrackedObjectList()
Get a list of all the known StationState objects.

Returns:
ArrayList of all currently known StationState instances

getCurrentTrackedObjectArray

public StationState[] getCurrentTrackedObjectArray()
Get an array of all the known StationState objects.

Returns:
array of all currently known StationState instances

getCurrentTrackedObjectArray

public StationState[] getCurrentTrackedObjectArray(boolean includeStations,
                                                   boolean includeObjects,
                                                   boolean includeSelf,
                                                   Filter filter,
                                                   java.util.Comparator<StationState> sortComparator)
Get an array of a selected filtered subset of the known StationState instances.

Parameters:
includeStations - boolean true if stations (message originators) should be included
includeObjects - boolean true if objects (non-transmitting) should be included
includeSelf - boolean true if own station should be included, regardless of filters and other include flags
filter - a Filter to decide which StationState instances should be included, or null if no filtering should be done
sortComparator - if non-null, a Comparator to use to sort the StationState objects in a desired order while the mutex is being held, to prevent the StationState objects from changing while the sort is in progress
Returns:
array of matching StationState instances

addTrackerListener

public void addTrackerListener(TrackerListener l)
Register a listener to be informed of changes to the station histories.

Parameters:
l - TrackerListener to register

removeTrackerListener

public void removeTrackerListener(TrackerListener l)
Unregister a listener.

Parameters:
l - TrackerListener to unregister

fireStationAdded

protected void fireStationAdded(StationState ss,
                                int index)
Inform all registered TrackerListener instances that a new station or object has been added to the tracker.

Parameters:
ss - newly-added StationState
index - index in tracker list of the new StationState

fireStationUpdated

public void fireStationUpdated(StationState ss)
Inform all registered TrackerListener instances that a station's status is being updated.

Parameters:
ss - StationState receiving update

fireStationDeleted

public void fireStationDeleted(StationState ss,
                               int index)
Inform all registered TrackerListener instances that a station or object's state is being deleted due to lack of activity,

Parameters:
ss - StationState instance being deleted
index - index in tracker list of the station being deleted

fireMessageAdded

protected void fireMessageAdded(StationState ss,
                                int index,
                                AX25Message msg)
Inform all registered TrackerListener instances that a new message has arrived from the specified station or about the specified object.

Parameters:
ss - StationState instance adding a new message
index - index within StationState object of the added message
msg - the AX25Message being added to the station/object

fireMessageDeleted

protected void fireMessageDeleted(StationState ss,
                                  int index,
                                  AX25Message msg)
Inform all registered TrackerListener instances that an old message has been deleted from the specified station or about the specified object.

Parameters:
ss - StationState instance deleting an old message
index - index within StationState object of the deleted message
msg - the AX25Message being deleted from the station/object

toString

public java.lang.String toString()
Return String describing the StationTracker object.

Overrides:
toString in class java.lang.Object
Returns:
descriptive String

deleteStation

public void deleteStation(StationState ss)
Remove the specified station or object from the tracked history immediately.

Parameters:
ss - StationState to remove

getInstance

public static StationTracker getInstance()
Get the singleton instance of the StationTracker.

Returns:
the StationTracker

aprsMessageReceived

public void aprsMessageReceived(Message msg)
Delivers the next message received by YAAC that is an APRS message.

Specified by:
aprsMessageReceived in interface AprsMessageListener
Parameters:
msg - some subclass of Message containing the message contents; the message should have an AX25Frame connected to it
See Also:
AX25Frame, AX25Message.ax25Frame, AX25Message.getAx25Frame()

parsedAX25MessageReceived

public void parsedAX25MessageReceived(byte pid,
                                      AX25Message msg)
Delivers the next message received by YAAC that is some sort of parsed AX.25 higher-level message.

Specified by:
parsedAX25MessageReceived in interface ParsedAX25MessageListener
Parameters:
pid - AX.25 protocol ID
msg - some subclass of Message containing the message contents; the message should have an AX25Frame connected to it
See Also:
AX25Frame

addMessage

public StationState addMessage(java.lang.String identifier,
                               AX25Message msg,
                               AX25Callsign[] digipeaters,
                               boolean upshiftIdentifier)
Register a message with the appropriate sending station.

Parameters:
identifier - String identifier of station or object sending the message
msg - the AX25Message to be recorded
digipeaters - any digipeater stations associated with the message's transmission
upshiftIdentifier - boolean true if identifier should be forced to upper case (i.e., is a station callsign, not an object identifier)
Returns:
the StationState record to which the message was logged

addNewDestination

public void addNewDestination(java.lang.String dest)
Add a new destination to the map of destination callsigns and statistics.

Parameters:
dest - String callsign of destination

addNewStationIfNeeded

public StationState addNewStationIfNeeded(java.lang.String callsign)
Get the current StationState record for the specified station or object, creating a new record if one doesn't currently exist.

Parameters:
callsign - String identifier for the station/object record to find or create
Returns:
StationState record

getStationTypeCount

public int getStationTypeCount(char symTableId,
                               char symbolCode)
Count the number of known stations of a specified type.

Parameters:
symTableId - code identifying the table or overlay being used (only valid primary or alternate table, or APRS 1.2 extensions known to YAAC)
symbolCode - code identifying the station symbol
Returns:
number of StationState records matching the symbol (or alternate table symbol for overlaid symbols without explicit APRS 1.2 definitions)

iterator

public java.util.Iterator<StationState> iterator()
Returns an iterator over a set of elements of type StationState.

Specified by:
iterator in interface java.lang.Iterable<StationState>
Returns:
an Iterator.

getDirectStationList

public java.lang.String[] getDirectStationList(long now)
Get a list of all stations heard directly by this station.

Parameters:
now - reference time (in milliseconds since Java epoch) that messages must not be more than 30 minutes older
Returns:
array of station ID strings directly heard, or null if no locally heard stations

getFinalSendersSet

public java.util.Set<java.lang.String> getFinalSendersSet()
Get all the callsigns of the final digipeaters/I-gates used by all stations in the history.

Returns:
Set of callsign Strings

getFinalSendersMap

public java.util.HashMap<java.lang.String,StationTracker.DigipeatStatistics> getFinalSendersMap()
Get the map of last digipeater statistics

Returns:
HashMap of callsign to statistics

getDestinationsStringSet

public java.util.Set<java.lang.String> getDestinationsStringSet()
Get the sorted set of all destination callsign strings.

Returns:
TreeSet of String station/object names

getDestinationsMap

public java.util.HashMap<java.lang.String,StationTracker.DestinationStatistics> getDestinationsMap()
Get the raw Map of destination callsigns to statistics counters.

Returns:
HashMap of String callsign to DestinationStatistics

addRelayListener

public void addRelayListener(DigipeatListener l)
Register a listener that wants to know when a new digipeater is recorded.

Parameters:
l - DigipeatListener to register

removeRelayListener

public void removeRelayListener(DigipeatListener l)
Unregister a listener that no longer wants to know when a new digipeater is recorded.

Parameters:
l - DigipeatListener to unregister

addDestinationListener

public void addDestinationListener(DestinationListener l)
Register a listener that wants to know when a new tocall or explicit network destination is recorded.

Parameters:
l - DestinationListener to register

removeDestinationListener

public void removeDestinationListener(DestinationListener l)
Remove a listener that no longer wants to know when a new tocall or explicit network destination is recorded.

Parameters:
l - DestinationListener to unregister

getRangeLimitFilter

public RadiusFilter getRangeLimitFilter()
Get a reference to the RadiusFilter used for deciding if a station or object has changed between being in-range and out-of-range.

Returns:
RadiusFilter instance