org.ka2ddo.aprs
Class PositionMessage

java.lang.Object
  extended by org.ka2ddo.ax25.AX25Message
      extended by org.ka2ddo.aprs.Message
          extended by org.ka2ddo.aprs.PositionMessage
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<AX25Message>, CommentedMessage
Direct Known Subclasses:
GpsRawMessage, MaidenheadLocatorBeacon, MicE, ObjectReport, PositionReport

public abstract class PositionMessage
extends Message

This abstract class extends Message to contain positional information, supporting several different kinds of APRS messages with position data.

See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class org.ka2ddo.ax25.AX25Message
AX25Message.Precedence
 
Field Summary
protected  byte abc
          The Mic-E status code ordinal, where 0 is Emergency and -1 means that no Mic-E status code is defined by this message.
 int altitude
          The altitude of this position in meters above mean sea level, or Integer.MIN_VALUE for unknown.
 DistanceUnit altitudeUnit
          The unit for the altitude measurement.
static float COMPRESSED_LAT_SCALING
          Conversion scaling constant for encoding latitude in APRS compressed-text format.
static float CONV_MPH_TO_METERS_PER_SEC
          Convenience constant to convert statute miles-per-hour to meters-per-second.
protected static java.lang.String DHM
          Date format to parse day and hours:minutes (in UTC) for a longer delta into the past.
protected  double fLatitude
          Latitude in fractional degrees North, or NaN if not filled in yet.
protected  float fLatPrecision
          The ambiguity level of the latitude in fractional degrees,
protected  double fLongitude
          Longitude in fractional degrees East, or NaN if not filled in yet.
protected static java.text.DecimalFormat fmtMonitorFreq
          Format string for APRS-standard frequency format.
protected static java.lang.String HMS
          Date format to decode hours/minutes/seconds timestamp string.
protected  boolean isCustom
          If true, indicates that the Mic-E status code should be treated as a custom value rather than the common standard meanings for the ordinal values 1 to 7.
protected  java.lang.String latitude
          The latitude of this position in APRS text format DDMM.MMn.
protected static double LN_BASE1_08
          Scaling factor for encoding speed with compressed position.
protected  java.lang.String longitude
          The longitude of this position in APRS text format DDDMM.MMw.
protected static java.lang.String MDHM
          Date format to parse 8-character date/time strings.
 
Fields inherited from class org.ka2ddo.aprs.Message
comment, extensions, msgType, S_PERMANENT, S_PERMANENT_UC, symbolCode, symTableId, USASCII
 
Fields inherited from class org.ka2ddo.ax25.AX25Message
ax25Frame, invalid, ISO_8859_1, originatingCallsign, PERMANENT, rcptTime, thirdParty, timestamp, UTC, UTF8
 
Constructor Summary
protected PositionMessage()
          Create an uninitialized PositionMessage (let the subclass initialize it).
protected PositionMessage(byte msgType, java.lang.String tp, long rcptTime)
          Create a partially-initialized PositionMessage.
 
Method Summary
protected static void appendAreaParameters(java.lang.StringBuilder b, java.util.Map<java.lang.Enum,java.lang.Object> extensionMap)
          Appends the area "symbol" parameters to a StringBuilder for producing a transmittable version of this position message.
protected  void appendRepeaterParameters(java.lang.StringBuilder b)
          Appends the repeater parameters (if any) to a StringBuilder for producing a transmittable version of this position message.
protected static void appendSignpostParameters(java.lang.StringBuilder b, java.util.Map<java.lang.Enum,java.lang.Object> extensionMap)
          Appends the signpost parameters (if any) to a StringBuilder for producing a transmittable version of this position message.
 boolean bodyEquals(AX25Message o)
          Compare the contents of the body of the message, reporting if they match.
 ObjectReport createObjectFromThisPosition()
          Create an ObjectReport from this PositionMessage.
 int decodeDataExtension(byte[] body, int pos)
          Decode data extension if it exists.
 double decodeLatitude()
          Get the latitude from this PositionMessage in decimal degrees North.
 double decodeLongitude()
          Get the longitude from this PositionMessage in decimal degrees East.
static double decodeOnlyLatitude(java.lang.String latitude)
          Decode standard long-format latitude without caring about the accuracy.
static double decodeOnlyLongitude(java.lang.String longitude)
          Decode the specified String as a standard-format longitude "dddmm.mmE".
static java.lang.String encodeLatitudeCompressed(double latitude)
          Convert a double-precision fractional degrees North latitude into APRS-standard compressed string format.
static java.lang.String encodeLatitudePlainText(double latitude)
          Convert a double-precision fractional degrees North latitude into APRS-standard string format.
static java.lang.String encodeLongitudeCompressed(double longitude)
          Convert a double-precision fractional degrees East longitude into APRS-standard compressed string format.
static java.lang.String encodeLongitudePlainText(double longitude)
          Convert a double-precision fractional degrees East longitude into APRS-standard string format.
protected  java.lang.String extractCompressedLatitude(byte[] body, int offset)
          Decode a compressed format latitude from a byte array.
protected  java.lang.String extractCompressedLongitude(byte[] body, int offset)
          Decode a compressed format longitude from a byte array.
protected  int extractLatitude(byte[] body, int pos)
          Service method to decode a fragment of an AX.25 frame that is supposed to contain an APRS-standard non-compressed latitude expression.
protected  int extractLongitude(byte[] body, int pos)
          Service method to decode a fragment of an AX.25 frame that is supposed to contain an APRS-standard non-compressed longitude expression.
 byte getAbc()
          Returns the decoded MicE status (if any) from this PositionMessage.
 int getAltitude()
          Get the altitude of this position relative to mean sea level.
 DistanceUnit getAltitudeUnit()
          Get the size unit for altitude in this position message.
 boolean getCustom()
          Indicate whether the MicE status code is a standard code or a custom code.
 java.lang.String getLatitude()
          Get the string format latitude of this message.
 float getLatitudeAccuracy()
          Computes the precision of the latitude value in fractional degrees
 java.lang.String getLongitude()
          Get the string format longitude of this message.
 boolean hasPosition()
          Report if this AX25Message contains position data.
 boolean isEnabled()
          Test if message should still be transmitted.
 boolean isShowDate()
          Test whether a transmission of this message should include the timestamp.
 boolean isUsingCompressedFormat()
          Indicates whether this PositionMessage is using compressed-mode (but not Mic-E) encoding of latitude and longitude, because this affects what are legal symbol overlay codes.
protected static boolean looksLikeFrequency(byte[] body, int pos)
          Check if the ASCII character sequence in a byte array contains something that looks like an APRS frequency value.
protected static boolean looksLikeFrequency(java.lang.String body, int pos)
          Check if the character sequence in a String contains something that looks like an APRS frequency value.
 java.lang.String paramString()
          Descriptive text about this message, to be included in the toString() method's response.
 void setAbc(byte abc)
          Set the encoded MicE status (if any) for this PositionMessage.
 void setLatitude(java.lang.String latitude)
          Set the string format latitude of this message.
 void setLocation(double latitude, double longitude)
          Set the latitude and longitude of this PositionMessage to the desired coordinates.
 void setLongitude(java.lang.String longitude)
          Set the string format longitude of this message.
 void setShowDate(boolean showDate)
          Specify whether this message should include the timestamp when transmitted or displayed.
protected static boolean testIfValidCompressedLocation(byte[] body, int offset)
          Test if the passed APRS byte array looks like a valid compressed-mode APRS position.
 
Methods inherited from class org.ka2ddo.aprs.Message
compareTo, decodeDatestamp, decodeHurricaneParams, decodeTimestamp, decodeWeatherParams, decodeWeatherParams, dup, encodeTimestamp, extractComment, extractComment, extractSymbol, formatBody, getComment, getExtension, getExtensionString, getMsgType, getReadOnlyExtensionMap, getSymbolCode, getSymTableId, hasWeather, inferSymbol, isSymbolInferred, looksLikeLongFormatLatitude, setComment, setSymbolCode, setSymTableId, storeExtension, toString
 
Methods inherited from class org.ka2ddo.ax25.AX25Message
equals, extractSource, getAx25Frame, getFirstDigipeat, getLastDigipeat, getOriginalDestination, getOriginalSource, getOriginatingCallsign, getPrecedence, getRcptTime, getTimestamp, hashCode, hasThisFirstDigi, indexOf, indexOf, isInvalid, onlyDigits, onlyDigits, onlyDigitsOrPeriod, onlyDigitsOrSpace, onlyDigitsPlus, onlyPeriods, setAx25Frame, setInvalid, setOriginatingCallsign, setRcptTime, setTimestamp, split
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

MDHM

protected static final java.lang.String MDHM
Date format to parse 8-character date/time strings.

See Also:
Constant Field Values

DHM

protected static final java.lang.String DHM
Date format to parse day and hours:minutes (in UTC) for a longer delta into the past.

See Also:
Constant Field Values

HMS

protected static final java.lang.String HMS
Date format to decode hours/minutes/seconds timestamp string.

See Also:
Constant Field Values

fmtMonitorFreq

protected static final java.text.DecimalFormat fmtMonitorFreq
Format string for APRS-standard frequency format.


COMPRESSED_LAT_SCALING

public static final float COMPRESSED_LAT_SCALING
Conversion scaling constant for encoding latitude in APRS compressed-text format.

See Also:
Constant Field Values

CONV_MPH_TO_METERS_PER_SEC

public static final float CONV_MPH_TO_METERS_PER_SEC
Convenience constant to convert statute miles-per-hour to meters-per-second.


LN_BASE1_08

protected static final double LN_BASE1_08
Scaling factor for encoding speed with compressed position.


latitude

protected java.lang.String latitude
The latitude of this position in APRS text format DDMM.MMn.


longitude

protected java.lang.String longitude
The longitude of this position in APRS text format DDDMM.MMw.


fLatitude

protected double fLatitude
Latitude in fractional degrees North, or NaN if not filled in yet.


fLongitude

protected double fLongitude
Longitude in fractional degrees East, or NaN if not filled in yet.


fLatPrecision

protected float fLatPrecision
The ambiguity level of the latitude in fractional degrees,


altitude

public int altitude
The altitude of this position in meters above mean sea level, or Integer.MIN_VALUE for unknown.


altitudeUnit

public DistanceUnit altitudeUnit
The unit for the altitude measurement.


abc

protected byte abc
The Mic-E status code ordinal, where 0 is Emergency and -1 means that no Mic-E status code is defined by this message.


isCustom

protected boolean isCustom
If true, indicates that the Mic-E status code should be treated as a custom value rather than the common standard meanings for the ordinal values 1 to 7.

Constructor Detail

PositionMessage

protected PositionMessage()
Create an uninitialized PositionMessage (let the subclass initialize it).


PositionMessage

protected PositionMessage(byte msgType,
                          java.lang.String tp,
                          long rcptTime)
Create a partially-initialized PositionMessage.

Parameters:
msgType - msgType character (should correspond to the subclass being created)
tp - third-party routing string, or null if this message is still on its original network
rcptTime - time in Java milliseconds in 1 Jan 1970 UTC when this message was received
Method Detail

extractLatitude

protected int extractLatitude(byte[] body,
                              int pos)
                       throws java.lang.IllegalArgumentException
Service method to decode a fragment of an AX.25 frame that is supposed to contain an APRS-standard non-compressed latitude expression. The decoded latitude is stored in the PositionMessage's latitude field.

Parameters:
body - byte array containing the message
pos - int into array where latitude expression should start
Returns:
index immediately following the latitude expression
Throws:
java.lang.IllegalArgumentException - if the pointed string is not a valid latitude expression
See Also:
latitude

decodeLatitude

public double decodeLatitude()
Get the latitude from this PositionMessage in decimal degrees North.

Returns:
fractional degrees North latitude

decodeOnlyLatitude

public static double decodeOnlyLatitude(java.lang.String latitude)
Decode standard long-format latitude without caring about the accuracy.

Parameters:
latitude - String in standard ddmm.mmN latitude format
Returns:
latitude in fractional degrees North

getLatitudeAccuracy

public float getLatitudeAccuracy()
Computes the precision of the latitude value in fractional degrees

Returns:
the double precision least significant digit range in fractional degrees

testIfValidCompressedLocation

protected static boolean testIfValidCompressedLocation(byte[] body,
                                                       int offset)
Test if the passed APRS byte array looks like a valid compressed-mode APRS position.

Parameters:
body - byte array supposedly containing an APRS position
offset - int array index into body where the position expression starts
Returns:
boolean true if this appears to be a valid compressed-mode position

extractCompressedLatitude

protected java.lang.String extractCompressedLatitude(byte[] body,
                                                     int offset)
Decode a compressed format latitude from a byte array.

Parameters:
body - byte array containing the latitude information
offset - index into the byte array where the latitude information starts
Returns:
APRS standard text-format latitude

encodeLatitudePlainText

public static java.lang.String encodeLatitudePlainText(double latitude)
Convert a double-precision fractional degrees North latitude into APRS-standard string format. Note this can only return the maximum precision, because there is no way to specify the lack of precision.

Parameters:
latitude - the floating-point latitude value
Returns:
the String representation of the latitude

encodeLatitudeCompressed

public static java.lang.String encodeLatitudeCompressed(double latitude)
Convert a double-precision fractional degrees North latitude into APRS-standard compressed string format. Note this can only return the maximum precision, because there is no way to specify the lack of precision.

Parameters:
latitude - the floating-point latitude value
Returns:
the compressed String representation of the latitude

extractLongitude

protected int extractLongitude(byte[] body,
                               int pos)
                        throws java.lang.IllegalArgumentException
Service method to decode a fragment of an AX.25 frame that is supposed to contain an APRS-standard non-compressed longitude expression. The decoded longitude is stored in the PositionMessage's longitude field. This also supports non-standard shortened longitudes with only 2-digit degree values.

Parameters:
body - byte array containing the message
pos - int into array where longitude expression should start
Returns:
index immediately following the longitude expression
Throws:
java.lang.IllegalArgumentException - if the pointed string is not a valid longitude expression
See Also:
longitude

extractCompressedLongitude

protected java.lang.String extractCompressedLongitude(byte[] body,
                                                      int offset)
Decode a compressed format longitude from a byte array.

Parameters:
body - byte array containing the longitude information
offset - index into the byte array where the longitude information starts
Returns:
APRS standard text-format longitude

decodeLongitude

public double decodeLongitude()
Get the longitude from this PositionMessage in decimal degrees East.

Returns:
fractional degrees East longitude

decodeOnlyLongitude

public static double decodeOnlyLongitude(java.lang.String longitude)
Decode the specified String as a standard-format longitude "dddmm.mmE".

Parameters:
longitude - String to decode as a longitude
Returns:
longitude in fractional degrees East

encodeLongitudePlainText

public static java.lang.String encodeLongitudePlainText(double longitude)
Convert a double-precision fractional degrees East longitude into APRS-standard string format. Note this can only return the maximum precision, because there is no way to specify the lack of precision.

Parameters:
longitude - the floating-point longitude value
Returns:
the String representation of the longitude

encodeLongitudeCompressed

public static java.lang.String encodeLongitudeCompressed(double longitude)
Convert a double-precision fractional degrees East longitude into APRS-standard compressed string format. Note this can only return the maximum precision, because there is no way to specify the lack of precision.

Parameters:
longitude - the floating-point longitude value
Returns:
the compressed String representation of the latitude

setLocation

public void setLocation(double latitude,
                        double longitude)
Set the latitude and longitude of this PositionMessage to the desired coordinates.

Parameters:
latitude - latitude in fractional degrees North
longitude - longitude in fractional degrees East

decodeDataExtension

public int decodeDataExtension(byte[] body,
                               int pos)
Decode data extension if it exists. The following extensions are supported:

Parameters:
body - byte array containing the message
pos - starting index in array
Returns:
updated index in array

looksLikeFrequency

protected static boolean looksLikeFrequency(byte[] body,
                                            int pos)
Check if the ASCII character sequence in a byte array contains something that looks like an APRS frequency value.

Parameters:
body - byte array to search
pos - zero-based index into array to start pattern match
Returns:
boolean true if specified index has a ddd.ddd pattern in it

looksLikeFrequency

protected static boolean looksLikeFrequency(java.lang.String body,
                                            int pos)
Check if the character sequence in a String contains something that looks like an APRS frequency value.

Parameters:
body - byte array to search
pos - zero-based index into array to start pattern match
Returns:
boolean true if specified index has a ddd.ddd pattern in it

paramString

public java.lang.String paramString()
Descriptive text about this message, to be included in the toString() method's response.

Overrides:
paramString in class Message
Returns:
String describing the contents of this message
See Also:
Message.toString()

isShowDate

public boolean isShowDate()
Test whether a transmission of this message should include the timestamp.

Returns:
boolean true if timestamp is included

setShowDate

public void setShowDate(boolean showDate)
Specify whether this message should include the timestamp when transmitted or displayed.

Parameters:
showDate - boolean true to show the timestamp (separate from the receive time)

hasPosition

public boolean hasPosition()
Report if this AX25Message contains position data.

Overrides:
hasPosition in class AX25Message
Returns:
boolean true if message contains position information

getLatitude

public java.lang.String getLatitude()
Get the string format latitude of this message.

Returns:
latitude String

getLongitude

public java.lang.String getLongitude()
Get the string format longitude of this message.

Returns:
longitude String

setLatitude

public void setLatitude(java.lang.String latitude)
                 throws java.lang.IllegalArgumentException
Set the string format latitude of this message.

Parameters:
latitude - String latitude to use
Throws:
java.lang.IllegalArgumentException - if string has illegal format

setLongitude

public void setLongitude(java.lang.String longitude)
                  throws java.lang.IllegalArgumentException
Set the string format longitude of this message.

Parameters:
longitude - String longitude to use
Throws:
java.lang.IllegalArgumentException - if string has illegal format

getAltitude

public int getAltitude()
Get the altitude of this position relative to mean sea level.

Returns:
altitude in the specified units or Integer,MIN_VALUE to indicate the altitude is unknown
See Also:
getAltitudeUnit()

getAltitudeUnit

public DistanceUnit getAltitudeUnit()
Get the size unit for altitude in this position message.

Returns:
DistanceUnit for this message's altitude

appendAreaParameters

protected static void appendAreaParameters(java.lang.StringBuilder b,
                                           java.util.Map<java.lang.Enum,java.lang.Object> extensionMap)
Appends the area "symbol" parameters to a StringBuilder for producing a transmittable version of this position message.

Parameters:
b - StringBuilder to add area parameters to
extensionMap - Map of message extensions containing the area information

appendSignpostParameters

protected static void appendSignpostParameters(java.lang.StringBuilder b,
                                               java.util.Map<java.lang.Enum,java.lang.Object> extensionMap)
Appends the signpost parameters (if any) to a StringBuilder for producing a transmittable version of this position message.

Parameters:
b - StringBuilder to add area parameters to
extensionMap - Map of message extensions containing the signpost information

appendRepeaterParameters

protected void appendRepeaterParameters(java.lang.StringBuilder b)
Appends the repeater parameters (if any) to a StringBuilder for producing a transmittable version of this position message.

Parameters:
b - StringBuilder to add repeater/monitor parameters to

getAbc

public byte getAbc()
Returns the decoded MicE status (if any) from this PositionMessage.

Returns:
MicE status code, or -1 if this PositionMessage does not contain a MicE status code

setAbc

public void setAbc(byte abc)
Set the encoded MicE status (if any) for this PositionMessage.

Parameters:
abc - MicE status code, or -1 if this PositionMessage should not contain a MicE status code

getCustom

public boolean getCustom()
Indicate whether the MicE status code is a standard code or a custom code.

Returns:
boolean true if custom MicE status, boolean false if standard MicE status or this message does not have MicE status

isEnabled

public boolean isEnabled()
Test if message should still be transmitted.

Returns:
boolean true if message should still be transmitted

createObjectFromThisPosition

public ObjectReport createObjectFromThisPosition()
Create an ObjectReport from this PositionMessage.

Returns:
new ObjectReport cloned from this PositionMessage

isUsingCompressedFormat

public boolean isUsingCompressedFormat()
Indicates whether this PositionMessage is using compressed-mode (but not Mic-E) encoding of latitude and longitude, because this affects what are legal symbol overlay codes. Intended to be overridden by appropriate subclasses.

Returns:
boolean true if compressed encoding in use

bodyEquals

public boolean bodyEquals(AX25Message o)
Compare the contents of the body of the message, reporting if they match.

Overrides:
bodyEquals in class Message
Parameters:
o - another AX25Message to compare against
Returns:
boolean true if the body values are equivalent