org.ka2ddo.yaac.ax25
Class StationState

java.lang.Object
  extended by org.ka2ddo.yaac.ax25.StationState
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<StationState>

public class StationState
extends java.lang.Object
implements java.lang.Comparable<StationState>, java.io.Serializable

This class maintains a record of the current state of a monitored station, and a reverse-chronologically-ordered history of all messages heard from the station. The accumulated state can be updated or recomputed from history at any time.

See Also:
Serialized Form

Nested Class Summary
static class StationState.SpecialState
          This enumeration identifies special conditions of a monitored station or object that color a background circle behind the icon for the station.
 
Field Summary
protected  char altSymbolCode
          The local alias symbol code within the specified symbol table for representing this station or object on the map.
protected  char altSymTableId
          The local alias symbol table ID (or overlay character for alternate symbols).
 java.lang.String identifier
          The String identifying this particular station or object.
 boolean isViewable
          Whether or not this station or object should be displayed on the map.
 java.lang.String localAlias
          The String identifying a local alias for this Station or Object.
static long MINUTES_80
          Constant defining 80 minutes (the period commonly considered to be out-of-date in APRS) in Java milliseconds.
protected  java.util.HashMap<java.lang.Object,java.lang.Object> miscAttachments
          Place to attach miscellaneous attachments to a station or object.
 float rangeM
          Scratch range variable used for aloha circle calculation.
static java.util.Comparator<StationState> SORT_BY_IDENTIFIER
           
protected  char symbolCode
          The symbol code within the specified symbol table for representing this station or object on the map.
protected  char symTableId
          The symbol table ID (or overlay character for alternate symbols).
 
Constructor Summary
StationState(java.lang.String callsign)
          Create a new StationState object with the specified identifying String and the specified parent node for tree-style display of the information.
 
Method Summary
 int addMessage(AX25Message msg)
          Add a message to the accumulated history for this station.
 java.lang.StringBuilder appendAliasKV(java.lang.StringBuilder b)
          Append the tactical alias for this station (or the undefinition if this station doesn't have an alias).
 void clearState()
          Clear all accumulated inferred information about the station or object.
 int compareTo(StationState ss)
          Compares this object with the specified object for order.
 boolean equals(java.lang.Object obj)
          Indicates whether some other object is "equal to" this one.
 AX25Message get(int childIndex)
          Get the Nth oldest message received from this station or object.
 long getAge(long now)
          Report the time since this station's information was updated.
 int getAliasKVLength()
          Return the length in characters of the tactical callsign exchange phrase for this station/object.
 char getAltSymbolCode()
          Return the currently defined local alias symbolCode reported for this station or object.
 char getAltSymTableId()
          Return the currently defined local alias identifier of the table containing the symbol reported for this station or object.
 float getAmsl()
          Get the last known altitude of the specified station or object.
 java.lang.Object getAttachment(java.lang.Object key)
          Get a named attachment for this station.
 java.lang.Object[] getAttachmentKeys()
          Get all the keys for attachments on this station or object.
 float getBearing()
          Get the last known course bearing for this station.
 java.lang.String getIdentifier()
          Get the identifying name of the station or object described by this StationState.
 long getLastDigiTime()
          Get the last time this station appeared as a digipeater.
 long getLastPosTime()
          Get the timestamp when the position was last updated.
 double getLatitude()
          Get the most recently reported or inferred latitude for this station or object.
 java.lang.String getLocalAlias()
          Get the current locally defined alias for this Station or Object.
 double getLongitude()
          Get the most recently reported or inferred longitude for this station or object.
 long getMostRecentPacketTime()
          Get the last time a Message was received on behalf of this station or object or anything this station digipeated.
 PositionMessage getMostRecentPosition()
          Get the last APRS position message reported for this station or object.
 long getMostRecentRcptTimeOfSelf()
          Get the last time a Message was received on behalf of this station or object.
 AX25Message.Precedence getPrecedence()
          Get the current Precedence state of this station or object.
static long getPurgeThresholdSecs()
          Get the time in seconds that messages will be kept before purging.
 float getRadiusOfConfidence()
          Return the last reported position ambiguity,
 StationState.SpecialState getSpecialState(long now, long age)
          Derive the background color for a given object.
 float getSpeed()
          Return the last known speed of travel of this station or object.
 char getSymbolCode()
          Return the last symbolCode reported for this station or object.
 char getSymTableId()
          Return the identifier of the table containing the symbol reported for this station or object.
 java.util.Map<java.lang.Enum,java.lang.Object> getWeatherStateMap()
          Get the map containing extracted weather and hurricane information.
 int hashCode()
          Returns a hash code value for the object.
 boolean hasHurricane()
          Report if this station is providing hurricane information.
 boolean hasPlaybackMessages()
          Report if this station or object has any messages from played-back log files.
 boolean hasRealtimeMessages()
          Report if this station has received any messages in real-time.
 boolean hasWeather()
          Report if this station is providing weather information.
 boolean isActiveObject()
          Indicates if this "station" is actually an Object or Item that is currently active (not killed).
 boolean isDirect(long oldestAllowed)
          Report if the station has been directly heard by the local YAAC instance (without being digipeated) recently.
static boolean isDoVicinityPlot()
          Efficiently test if vicinity plotting should be done for stations not reporting position.
 boolean isIGateOnly()
          Indicate if the station has only been heard via a IGate connection to the APRS-IS backbone.
 boolean isLocalRf(long oldestAllowed, int maxDigis)
          Indicate if the station is accessible over local RF.
 boolean isObject()
          Reports if this station was last reported as a non-transmitting object or item, as defined by the APRS specifications.
 boolean isObjectOnly()
          Reports if this station is actually a non-transmitting object or item, as defined by the APRS specifications.
 boolean isOnlyOverrapidGpsFixes()
          If entire history of this station is GpsRawMessages at too fast a rate for APRS messaging, than it must be either a moron or a remote GPS (as defined in the SerialGpsConnector and SerialGpsPortEditor).
 StationState.SpecialState isStationMoving(long now)
          Test if the station monitored by this StationState appears to be moving or remaining in a fixed location.
 boolean isTimeInRange(long timestamp)
          Test if this station has any messages meeting the specified time range.
 java.util.Iterator<AX25Message> iterator()
          Obtain an iterator to cycle through the messages accumulated for this station or object.
 int pruneOldMessages(long then)
          Delete all messages from this StationState object whose receive times are older than the specified old age.
 java.lang.Object putAttachment(java.lang.Object key, java.lang.Object attachment)
          Add an attachment to this station or object.
 java.lang.Object removeAttachment(java.lang.Object key)
          Remove an attachment from this station or object.
 void setAltSymbolCode(char altSymbolCode)
          Set the currently defined local alias symbolCode reported for this station or object.
 void setAltSymTableId(char altSymTableId)
          Set the currently defined local alias identifier of the table containing the symbol reported for this station or object.
 void setAmsl(float amsl)
          Overwrite the altitude for this station/object.
static void setDoVicinityPlot(boolean doVicinityPlot)
          Remember if vicinity plotting should be done for stations not reporting position.
 void setLocalAlias(java.lang.String localAlias)
          Set the current locally defined alias for this Station or Object.
 void setLocation(double latitude, double longitude, long timestampMsec)
          Set the location for this station or object.
static void setPurgeThresholdSecs(long purgeThresholdSecs)
          Set the time in seconds before messages will be purged.
 void setSymbol(char symTableId, char symbolCode)
          Change the symbol code associated with this station.
 void setVelocity(float bearing, float speedKts)
          Set the speed and direction of motion for this station or object.
 int size()
          Get the number of messages associated with this station or object.
 java.lang.String toString()
          Return a string describing this object.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

MINUTES_80

public static final long MINUTES_80
Constant defining 80 minutes (the period commonly considered to be out-of-date in APRS) in Java milliseconds.

See Also:
Constant Field Values

identifier

public java.lang.String identifier
The String identifying this particular station or object.


localAlias

public java.lang.String localAlias
The String identifying a local alias for this Station or Object.


symTableId

protected char symTableId
The symbol table ID (or overlay character for alternate symbols). '/' indicates a primary table symbol, anything else is an alternate table symbol. Default value until changed is the table for the "Unknown Position" symbol.


symbolCode

protected char symbolCode
The symbol code within the specified symbol table for representing this station or object on the map. Derived from symbol information embedded or inferred from the most recently received Messages. Default value until changed is the code for the "Unknown Position" symbol.

See Also:
symTableId

altSymTableId

protected char altSymTableId
The local alias symbol table ID (or overlay character for alternate symbols). '/' indicates a primary table symbol, anything else is an alternate table symbol.


altSymbolCode

protected char altSymbolCode
The local alias symbol code within the specified symbol table for representing this station or object on the map.

See Also:
altSymTableId

isViewable

public boolean isViewable
Whether or not this station or object should be displayed on the map.

See Also:
SendingStationFilter

rangeM

public float rangeM
Scratch range variable used for aloha circle calculation.

See Also:
AlohaRanger

miscAttachments

protected java.util.HashMap<java.lang.Object,java.lang.Object> miscAttachments
Place to attach miscellaneous attachments to a station or object.


SORT_BY_IDENTIFIER

public static final java.util.Comparator<StationState> SORT_BY_IDENTIFIER
Constructor Detail

StationState

public StationState(java.lang.String callsign)
Create a new StationState object with the specified identifying String and the specified parent node for tree-style display of the information.

Parameters:
callsign - String callsign or name of the station or object
Method Detail

isDoVicinityPlot

public static boolean isDoVicinityPlot()
Efficiently test if vicinity plotting should be done for stations not reporting position.

Returns:
boolean true if stations should be vicinity plotted relative to the original digipeating station

setDoVicinityPlot

public static void setDoVicinityPlot(boolean doVicinityPlot)
Remember if vicinity plotting should be done for stations not reporting position.

Parameters:
doVicinityPlot - boolean true if stations should be vicinity plotted relative to the original digipeating station

getPurgeThresholdSecs

public static long getPurgeThresholdSecs()
Get the time in seconds that messages will be kept before purging.

Returns:
time in seconds before purging (non-positive means no purging)

setPurgeThresholdSecs

public static void setPurgeThresholdSecs(long purgeThresholdSecs)
Set the time in seconds before messages will be purged.

Parameters:
purgeThresholdSecs - time in seconds before messages are purged (non-positive time specifies no purging)

clearState

public void clearState()
Clear all accumulated inferred information about the station or object.


addMessage

public int addMessage(AX25Message msg)
Add a message to the accumulated history for this station.

Parameters:
msg - AX25Message to add to the history of this station state
Returns:
zero-based index within the time-ordered history where the message was inserted

pruneOldMessages

public int pruneOldMessages(long then)
Delete all messages from this StationState object whose receive times are older than the specified old age.

Parameters:
then - long time in milliseconds since Unix epoch that is the oldest time of messages not to be deleted
Returns:
number of deleted messages

isOnlyOverrapidGpsFixes

public boolean isOnlyOverrapidGpsFixes()
If entire history of this station is GpsRawMessages at too fast a rate for APRS messaging, than it must be either a moron or a remote GPS (as defined in the SerialGpsConnector and SerialGpsPortEditor).

Returns:
boolean true if entire message history is excessively frequent raw GPS messages

hasRealtimeMessages

public boolean hasRealtimeMessages()
Report if this station has received any messages in real-time.

Returns:
boolean true if real time messages have been received from this station or about this object

hasPlaybackMessages

public boolean hasPlaybackMessages()
Report if this station or object has any messages from played-back log files.

Returns:
boolean true if real time messages have been received from this station or about this object

isTimeInRange

public boolean isTimeInRange(long timestamp)
Test if this station has any messages meeting the specified time range.

Parameters:
timestamp - border time in Java standard milliseconds since 1970 UTC
Returns:
boolean true if this station meets the specified constraint

getAge

public final long getAge(long now)
Report the time since this station's information was updated.

Parameters:
now - the current time in Java standard milliseconds since 1970 UTC
Returns:
the number of milliseconds since the most recent message from this station, or Long.MAX_VALUE if no messages pass the filter and have timestamps

getAmsl

public float getAmsl()
Get the last known altitude of the specified station or object.

Returns:
altitude in meters, or Float.NaN if altitude unknown

setAmsl

public void setAmsl(float amsl)
Overwrite the altitude for this station/object.

Parameters:
amsl - new altitude in meters above mean sea level relative to WGS84 geoid

getIdentifier

public java.lang.String getIdentifier()
Get the identifying name of the station or object described by this StationState.

Returns:
String name of the station or object

getLatitude

public double getLatitude()
Get the most recently reported or inferred latitude for this station or object.

Returns:
latitude in decimal degrees North, or 0.0 if unknown

getLongitude

public double getLongitude()
Get the most recently reported or inferred longitude for this station or object.

Returns:
longitude in decimal degrees East, or 0.0 if unknown

getLastPosTime

public long getLastPosTime()
Get the timestamp when the position was last updated.

Returns:
milliseconds since Jan 1 1970 UTC, or -1 if no position data is available

getLastDigiTime

public long getLastDigiTime()
Get the last time this station appeared as a digipeater.

Returns:
milliseconds since Jan 1 1970 UTC of last digipeat, or -1 if no digipeat data is available

getBearing

public float getBearing()
Get the last known course bearing for this station. Meaningless if speed returns zero.

Returns:
bearing of travel in clockwise degrees from True North

getSpeed

public float getSpeed()
Return the last known speed of travel of this station or object.

Returns:
speed of travel in decimal knots (nautical miles per hour)
See Also:
DistanceUnit.NM

isDirect

public boolean isDirect(long oldestAllowed)
Report if the station has been directly heard by the local YAAC instance (without being digipeated) recently.

Parameters:
oldestAllowed - the time in milliseconds after which this station must have been locally heard to report true
Returns:
boolean true if station has been locally heard

isLocalRf

public boolean isLocalRf(long oldestAllowed,
                         int maxDigis)
Indicate if the station is accessible over local RF.

Parameters:
oldestAllowed - oldest message time to check for local vs. non-local
maxDigis - maximum number of digipeats to consider
Returns:
true if station is local to current YAAC instance and heard over RF

isIGateOnly

public boolean isIGateOnly()
Indicate if the station has only been heard via a IGate connection to the APRS-IS backbone.

Returns:
true if station messages have only arrived from the Internet

getRadiusOfConfidence

public float getRadiusOfConfidence()
Return the last reported position ambiguity,

Returns:
position ambiguity in meters around the actual reported latitude/longitude, or a negative value if the ambiguity has not been reported yet

getSymbolCode

public final char getSymbolCode()
Return the last symbolCode reported for this station or object.

Returns:
symbol character

getSymTableId

public final char getSymTableId()
Return the identifier of the table containing the symbol reported for this station or object.

Returns:
symbol table ID character or overlay character if overlay used

getAltSymbolCode

public final char getAltSymbolCode()
Return the currently defined local alias symbolCode reported for this station or object.

Returns:
symbol character, or '\0' if no alias used

getAltSymTableId

public final char getAltSymTableId()
Return the currently defined local alias identifier of the table containing the symbol reported for this station or object.

Returns:
symbol table ID character or overlay character if overlay used, or '\0' if no alias used

setAltSymbolCode

public final void setAltSymbolCode(char altSymbolCode)
Set the currently defined local alias symbolCode reported for this station or object.

Parameters:
altSymbolCode - symbol character, or '\0' if no alias used

setAltSymTableId

public final void setAltSymTableId(char altSymTableId)
Set the currently defined local alias identifier of the table containing the symbol reported for this station or object.

Parameters:
altSymTableId - symbol table ID character or overlay character if overlay used, or '\0' if no alias used

hasWeather

public boolean hasWeather()
Report if this station is providing weather information.

Returns:
boolean true if the station has accumulated weather data.

hasHurricane

public boolean hasHurricane()
Report if this station is providing hurricane information.

Returns:
boolean true if the station has accumulated hurricane data.

isObjectOnly

public boolean isObjectOnly()
Reports if this station is actually a non-transmitting object or item, as defined by the APRS specifications.

Returns:
boolean true if this object has only been described by ObjectReport messages.
See Also:
ObjectReport

isObject

public boolean isObject()
Reports if this station was last reported as a non-transmitting object or item, as defined by the APRS specifications.

Returns:
boolean true if this object was last described by an ObjectReport message.
See Also:
ObjectReport

iterator

public java.util.Iterator<AX25Message> iterator()
Obtain an iterator to cycle through the messages accumulated for this station or object.

Returns:
Iterator

getWeatherStateMap

public java.util.Map<java.lang.Enum,java.lang.Object> getWeatherStateMap()
Get the map containing extracted weather and hurricane information.

Returns:
Map of Enums (either WeatherEnum or HurricanceEnum) to corresponding values, or null if no weather data

toString

public java.lang.String toString()
Return a string describing this object.

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

get

public AX25Message get(int childIndex)
Get the Nth oldest message received from this station or object.

Parameters:
childIndex - int index into accumulated message history
Returns:
AX25Message
Throws:
java.lang.IndexOutOfBoundsException - if childIndex not in range
See Also:
size()

size

public int size()
Get the number of messages associated with this station or object.

Returns:
number of messages

getMostRecentRcptTimeOfSelf

public long getMostRecentRcptTimeOfSelf()
Get the last time a Message was received on behalf of this station or object.

Returns:
timestamp in Unix milliseconds since Jan 1, 1970 UTC.

getMostRecentPacketTime

public long getMostRecentPacketTime()
Get the last time a Message was received on behalf of this station or object or anything this station digipeated.

Returns:
timestamp in Unix milliseconds since Jan 1, 1970 UTC.

compareTo

public int compareTo(StationState ss)
Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object. The default ordering for this class is by case-insensitive lexical order of the identifier name of the station or object.

Specified by:
compareTo in interface java.lang.Comparable<StationState>
Parameters:
ss - the StationState to be compared.
Returns:
a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
Throws:
java.lang.NullPointerException - if the specified object is null
java.lang.ClassCastException - if the specified object's type prevents it from being compared to this object.

getSpecialState

public StationState.SpecialState getSpecialState(long now,
                                                 long age)
Derive the background color for a given object.

Parameters:
now - time reference (in milliseconds since Jan 1 1970 UTC) to use to calculate age
age - delta time since last received transmission from this station in milliseconds
Returns:
SpecialState enum for this object, or null if no special state known for this object

isStationMoving

public StationState.SpecialState isStationMoving(long now)
Test if the station monitored by this StationState appears to be moving or remaining in a fixed location.

Parameters:
now - current time in Java milliseconds since Jan 1 1970 UTC
Returns:
one of states MOVING, FIXED, or DEADRECKONED, or null if the movement of the station could not be derived

getPrecedence

public AX25Message.Precedence getPrecedence()
Get the current Precedence state of this station or object.

Returns:
the highest Precedence reported by this station or object in the last 10 minutes

getMostRecentPosition

public PositionMessage getMostRecentPosition()
Get the last APRS position message reported for this station or object. Does not currently work with OpenTRAC position reports.

Returns:
most recent APRS PositionMessage, or null if no APRS positions

isActiveObject

public boolean isActiveObject()
Indicates if this "station" is actually an Object or Item that is currently active (not killed). "Stations" with messages other than Object/Item reports and Status reports are not active Objects.

Returns:
boolean true if this is an active Object/Item, false otherwise

getLocalAlias

public java.lang.String getLocalAlias()
Get the current locally defined alias for this Station or Object.

Returns:
local alias, or null if no alias defined

setLocalAlias

public void setLocalAlias(java.lang.String localAlias)
Set the current locally defined alias for this Station or Object.

Parameters:
localAlias - the String local alias for this Station or Object, or null to clear the alias

setSymbol

public void setSymbol(char symTableId,
                      char symbolCode)
Change the symbol code associated with this station.

Parameters:
symTableId - character for the symbol table and/or overlay for this station/object
symbolCode - character for the symbol within the specified table for this station/object

setLocation

public void setLocation(double latitude,
                        double longitude,
                        long timestampMsec)
Set the location for this station or object.

Parameters:
latitude - latitude in degrees North
longitude - longitude in degrees East
timestampMsec - time in milliseconds since Jan 1 1970 UTC (epoch)

setVelocity

public void setVelocity(float bearing,
                        float speedKts)
Set the speed and direction of motion for this station or object.

Parameters:
bearing - direction of travel in degrees from True North
speedKts - sped of motion in knots (nautical miles per hour)

equals

public boolean equals(java.lang.Object obj)
Indicates whether some other object is "equal to" this one.

Overrides:
equals in class java.lang.Object
Parameters:
obj - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.
See Also:
hashCode(), Hashtable

hashCode

public int hashCode()
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

Overrides:
hashCode in class java.lang.Object
Returns:
a hash code value for this object.
See Also:
Object.equals(Object), Hashtable

getAttachment

public java.lang.Object getAttachment(java.lang.Object key)
Get a named attachment for this station.

Parameters:
key - Object identifying the particular attachment
Returns:
the attached data, or null if no attachment with the specified key

putAttachment

public java.lang.Object putAttachment(java.lang.Object key,
                                      java.lang.Object attachment)
                               throws java.lang.NullPointerException
Add an attachment to this station or object.

Parameters:
key - Object that will identify this particular attachment
attachment - data to be attached
Returns:
previous attachment under this key, or null if no previous attachment
Throws:
java.lang.NullPointerException - if a null attachment is specified

removeAttachment

public java.lang.Object removeAttachment(java.lang.Object key)
Remove an attachment from this station or object.

Parameters:
key - Object identifying the attachment to be removed
Returns:
whatever attachment was formerly associated with this key, or null if no previous attachment

getAttachmentKeys

public java.lang.Object[] getAttachmentKeys()
Get all the keys for attachments on this station or object.

Returns:
array of key objects (may be zero length if no attachments)

getAliasKVLength

public int getAliasKVLength()
Return the length in characters of the tactical callsign exchange phrase for this station/object.

Returns:
number of characters to encode the local alias and/or alternate symbol translation of the identifier, or zero if no alternate defined for this station/object

appendAliasKV

public java.lang.StringBuilder appendAliasKV(java.lang.StringBuilder b)
Append the tactical alias for this station (or the undefinition if this station doesn't have an alias).

Parameters:
b - StringBuilder to append to
Returns:
the updated StringBuilder