Class StationTracker

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

public class StationTracker extends Object implements 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.
Author:
Andrew Pavlin, KA2DDO
  • Field Details

    • IGATE

      public static final String IGATE
      Capability string included in capabilities if local station functioning as an I-Gate.
      See Also:
    • HEAP_UPPER_PERCENT_THRESHOLD

      public static final int HEAP_UPPER_PERCENT_THRESHOLD
      How close the consumption of the JVM heap can get to the maximum (-Xmx option to JVM) before YAAC starts reducing retention intervals and taking other actions to prevent heap starvation, specified as a percentage.
      See Also:
  • Method Details

    • buildLocalCapabilities

      public static List<String> buildLocalCapabilities()
      Build a list of APRS capabilities this station has, suitable for a response to a "?IGATE" query.
      Returns:
      List of capability Strings
      See Also:
    • addCapabilitiesProvider

      public static void addCapabilitiesProvider(CapabilitiesProvider p)
      Register a CapabilitiesProvider instance.
      Parameters:
      p - CapabilitiesProvider instance
    • removeCapabilitiesProvider

      public static void removeCapabilitiesProvider(CapabilitiesProvider p)
      Unregister a CapabilitiesProvider instance.
      Parameters:
      p - CapabilitiesProvider instance
    • isOptimizeTransmits

      public static boolean isOptimizeTransmits()
      Report whether port optimization of locally-originated message transmits should be performed.
      Returns:
      boolean true if port optimization should be performed
    • setOptimizeTransmits

      public static void setOptimizeTransmits(boolean optimizeTransmits)
      Specify whether port optimization of locally-originated message transmits should be performed.
      Parameters:
      optimizeTransmits - boolean true if port optimization should be performed
    • findBestConnectorForStation

      public Connector findBestConnectorForStation(String callsign)
      Calculate the best Connector to use to reach a particular specified remote station, based on what has been collected about that station's transmissions to the local station. If a best port cannot be determined (due to the station having been heard through a receive-only port or never heard at all), then null will be returned, which typically causes transmit code in YAAC to try all transmit-capable ports.
      Parameters:
      callsign - String of callsign-SSID to lookup
      Returns:
      preferred Connector to use to reach this station, or null if no preferred path can be determined
    • purgeStaleTraffic

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

      public void addPurgeListener(PurgeListener l)
      Register to be informed when purging should be performed.
      Parameters:
      l - PurgeListener to notify when pruning is occurring
    • removePurgeListener

      public void removePurgeListener(PurgeListener l)
      Unregister from being informed when purging should be performed.
      Parameters:
      l - PurgeListener that no longer wants to be notified when pruning is occurring
    • getTrackedObject

      public StationState getTrackedObject(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 Set<String> getCurrentNameSet()
      Get a Set of all the identifiers of stations and objects currently known.
      Returns:
      Set of identifier Strings
    • getCurrentTrackedObjectList

      public ArrayList<StationState> getCurrentTrackedObjectList()
      Get a list of all the known StationState objects.
      Returns:
      ArrayList of all currently known StationState instances
    • getCurrentTrackedObjectList

      public ArrayList<StationState> getCurrentTrackedObjectList(boolean includeStations, boolean includeObjects, boolean includeSelf)
      Get a list of selected members of the known StationState objects.
      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
      Returns:
      ArrayList of all currently known StationState instances
    • getStationByAlias

      public StationState getStationByAlias(String alias)
      Search for the first Station with the specified alias (tactical name).
      Parameters:
      alias - String of tactical name to search for
      Returns:
      StationState of matching station, or null if no match
    • 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, 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
    • getCurrentTrackedObjectArray

      public StationState[] getCurrentTrackedObjectArray(StationState[] oldArray, boolean includeStations, boolean includeObjects, boolean includeSelf, Filter filter, Comparator<StationState> sortComparator)
      Get an array of a selected filtered subset of the known StationState instances, recycling an existing array if it is long enough.
      Parameters:
      oldArray - StationState array to be filled with the data if it is long enough (and null-padded)
      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 String toString()
      Return String describing the StationTracker object.
      Overrides:
      toString in class 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:
    • 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:
    • addMessage

      public StationState addMessage(String identifier, AX25Message msg, AX25Callsign[] digipeaters, boolean isStationName)
      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
      isStationName - 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(String dest)
      Add a new destination to the map of destination callsigns and statistics.
      Parameters:
      dest - String callsign of destination
    • addNewStationIfNeeded

      public StationState addNewStationIfNeeded(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 Iterator<StationState> iterator()
      Returns an iterator over a set of elements of type StationState.
      Specified by:
      iterator in interface Iterable<StationState>
      Returns:
      an Iterator.
    • getDirectStationList

      public 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
    • getDigipeatersSet

      public Set<String> getDigipeatersSet()
      Get all the callsigns of the first and last digipeaters used by all stations in the history.
      Returns:
      Set of callsign Strings
    • getDigipeatersMap

      public HashMap<String,StationTracker.DigipeatStatistics> getDigipeatersMap()
      Get the map of first/last digipeater statistics.
      Returns:
      HashMap of callsign to statistics
    • getFinalSendersSet

      public Set<String> getFinalSendersSet()
      Get all the callsigns of the final digipeaters/I-gates used by all stations in the history.
      Returns:
      Set of callsign Strings
    • getDigipeaterStatisticsFor

      public StationTracker.DigipeatStatistics getDigipeaterStatisticsFor(String callsign)
      Get the DigipeatStatistics record for the specified callsign if it has ever been used as a first or last digipeater (or last I-gate).
      Parameters:
      callsign - String digipeater callsign
      Returns:
      DigipeatStatistics record, or null if not found
    • getDestinationsStringSet

      public Set<String> getDestinationsStringSet()
      Get the sorted set of all destination callsign strings.
      Returns:
      TreeSet of String station/object names
    • getDestinationsMap

      public HashMap<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 last 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 last digipeater is recorded.
      Parameters:
      l - DigipeatListener to unregister
    • isRelayListener

      public boolean isRelayListener(DigipeatListener l)
      Test if the specified DigipeatListener is registered for last digipeater updates.
      Parameters:
      l - DigipeatListener to look for
      Returns:
      boolean true if registered for last digipeater events, false if not
    • add1stDigiListener

      public void add1stDigiListener(DigipeatListener l)
      Register a listener that wants to know when a new first digipeater is recorded.
      Parameters:
      l - DigipeatListener to register
    • remove1stDigiListener

      public void remove1stDigiListener(DigipeatListener l)
      Unregister a listener that no longer wants to know when a new first digipeater is recorded.
      Parameters:
      l - DigipeatListener to unregister
    • is1stDigiListener

      public boolean is1stDigiListener(DigipeatListener l)
      Test if the specified DigipeatListener is registered for first digipeater updates.
      Parameters:
      l - DigipeatListener to look for
      Returns:
      boolean true if registered for first digipeater events, false if not
    • 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