org.ka2ddo.aprs

Class ObjectReport

java.lang.Object

org.ka2ddo.ax25.AX25Message

org.ka2ddo.aprs.Message

org.ka2ddo.aprs.PositionMessage

org.ka2ddo.aprs.ObjectReport

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<AX25Message>, SetBeaconRatesIfc, CommentedMessage, ScopeableMessage, SendableMessage, PositionSrc

public class ObjectReport
extends PositionMessage
implements ScopeableMessage, SetBeaconRatesIfc

This class defines an APRS Object Report (';') or Item Report (')') message (APRS protocol specification chapter 11). It also supports sending these reports as OpenTRAC entity messages.

Author:

Andrew Pavlin, KA2DDO

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.ka2ddo.ax25.AX25Message

AX25Message.Precedence

Field Summary

Fields

Modifier and Type	Field and Description
int	decayRatio The ratio of expansion of the transmission interval as the rate slows from the fast rate to the slow rate.
java.lang.String[]	digipeatPaths Digipeating paths (in proportional pathing order) for transmitting locally-originated Objects.
int	fastSendRate The transmission rate to initially use for this Object.
char	life Flag indicating whether Object is still active (alive) or has been decommissioned (dead).
static int	NUM_KILLED_TRANSMISSIONS The number of times a "killed" Object/Item should be transmitted so everyone knows it is killed.
java.lang.String	objectName Name of Object or Item.
java.lang.String	qruCategory QRU category to associate with locally-originated Item, or null for no QRU group.
java.lang.String	savedTimestamp Timestamp in Object message (null for Items).
Scope	scope Scope for the transmission of locally-originated Objects.
int	slowSendRate The transmission rate to decay to for this Object.

Fields inherited from class org.ka2ddo.aprs.PositionMessage

abc, altitude, altitudeUnit, COMPRESSED_LAT_SCALING, CONV_MPH_TO_METERS_PER_SEC, DHM, enabledForTransmit, fLatitude, fLatPrecision, fLongitude, fmtMonitorFreq, HMS, HUNDREDTH_MINUTE_F, isCustom, latitude, LN_BASE1_08, longitude, ONE_DEGREE_F, ONE_MINUTE_F, TEN_MINUTES_F, TENTH_MINUTE_F

Fields inherited from class org.ka2ddo.aprs.Message

appendCR, APRS_AND_OPENTRAC_AND_RAW, APRS_AND_RAW, comment, msgType, S_PERMANENT, S_PERMANENT_UC, symbolCode, symTableId

Fields inherited from class org.ka2ddo.ax25.AX25Message

APRS_AND_OPENTRAC, ax25Frame, extensions, invalid, originatingCallsign, originatingDest, PERMANENT, rcptTime, thirdParty, timestamp, UTC

Constructor Summary

Constructors

Constructor and Description
ObjectReport(boolean isItem, java.lang.String objectName, boolean alive, java.util.Date date, char symTableId, char symbolCode) Create an ObjectReport suitable for transmission with the basic parameters filled in (some fields will still have to be filled before the message is safe to transmit).
ObjectReport(byte[] body, int offset, java.lang.String tp, AX25Callsign[] digipeaters, long rcvTimestamp) Constructor for Object or Item message when decoding a binary AX.25 frame.
ObjectReport(byte[] body, int offset, java.lang.String tp, long rcvTimestamp) Constructor for Object or Item message when decoding a binary AX.25 frame.
ObjectReport(java.lang.String strBody, long rcvTimestamp) Constructor for Item reports embedded in a Message (the Item-in-Msg encapsulation)

Method Summary

Modifier and Type	Method and Description
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.
void	disableForTransmit() Specify that message should no longer be transmitted.
byte[]	getBody(boolean countTransmission, ProtocolFamily protocolId, AX25Frame frame) Get an instance of this message, suitable for transmitting.
int	getDecayRatio() Get the scaling factor by which the message repeat interval is enlarged (until the default slow send rate is reached).
int	getInitialSendRate() Get the time interval between retransmissions when a message is newly introduced into the system.
java.lang.String	getObjectName() Report the name of the Object or Item.
Scope	getScope() Get the transmission scope for this message (so the digipeat path can be derived).
int	getSlowSendRate() The slowest rate a message should be sent.
java.lang.String	getStringAPRSBody(boolean countTransmission) Build the transmittable body of a APRS Object or Item message from this data structure,
boolean	isAlive() Test if Object/Item is still alive.
boolean	isEnabled() Test if message should still be transmitted.
boolean	isSetEnabled() Report whether the enable flag is set for this message (independent of expiration or limited scope).
boolean	isUseGpsForPosition() Indicate whether beacon data source can dynamically change its position (latitude/longitude), such as for a mobile station with a GPS.
java.lang.String	paramString() Descriptive text about this message, to be included in the toString() method's response.
static ObjectReport	readFromPreferences(java.util.prefs.Preferences prefs, java.lang.String objectName) Restore a new instance of an Object or Item from its backing store in Java Preferences.
void	removeFromPreferences(java.util.prefs.Preferences prefs) Clear this Object/Item from Java Preferences,
void	setDecayRatio(int decayRatio) Set the scaling factor by which the message repeat interval is enlarged (until the default slow send rate is reached).
void	setEnabled(boolean enabled) Specify whether this message should be transmitted.
void	setInitialSendRate(int initialSendRate) Set the time interval between retransmissions when a message is newly introduced into the system.
void	setScope(Scope scope) Set the transmission scope for this message (so the digipeat path can be derived).
void	setSlowSendRate(int slowSendRate) Set the slowest rate a message should be sent.
void	setTimestamp(long when) Change the timestamp associated with this Object (should only be done on retransmitted locally-originated Objects).
void	writeToPreferences(java.util.prefs.Preferences prefs) Persist this Object/Item in Java Preferences.

Methods inherited from class org.ka2ddo.aprs.PositionMessage

appendAreaParameters, appendRepeaterParameters, appendSignpostParameters, decodeDataExtension, decodeLatitude, decodeLongitude, decodeOnlyLatitude, decodeOnlyLongitude, encodeLatitudeCompressed, encodeLatitudePlainText, encodeLongitudeCompressed, encodeLongitudePlainText, extractCompressedLatitude, extractCompressedLongitude, extractLatitude, extractLongitude, getAbc, getAltitude, getAltitudeUnit, getHorizontalAccuracy, getLatitude, getLatitudeAccuracy, getLongitude, getPositionAltitude, getPositionLatitude, getPositionLongitude, getPositionTime, hasPosition, isCustom, isShowDate, isUsingCompressedFormat, looksLikeFrequency, looksLikeFrequency, setAbc, setAmbiguity, setCustom, setLatitude, setLocation, setLongitude, setShowDate, testIfValidCompressedLocation

Methods inherited from class org.ka2ddo.aprs.Message

compareTo, decodeDatestamp, decodeHurricaneParams, decodeTimestamp, decodeWeatherParams, decodeWeatherParams, dup, encodeTimestamp, extractComment, extractComment, extractSymbol, formatBody, getComment, getExtensionString, getMsgType, getPrecedence, getProtocols, getSymbolCode, getSymTableId, hasWeather, inferSymbol, isAppendCR, isSymbolInferred, looksLikeLongFormatLatitude, setAppendCR, setComment, setSymbolCode, setSymTableId, toString

Methods inherited from class org.ka2ddo.ax25.AX25Message

equals, extractSource, getAx25Frame, getExtension, getFirstDigipeat, getLastDigipeat, getNthDigipeat, getOriginalDestination, getOriginalSource, getOriginatingCallsign, getOriginatingDest, getRcptTime, getReadOnlyExtensionMap, getTimestamp, hashCode, hasThisFirstDigi, indexOf, indexOf, isDirect, isInvalid, isRf, onlyDigits, onlyDigits, onlyDigitsOrMinus, onlyDigitsOrPeriod, onlyDigitsOrSpace, onlyDigitsPlus, onlyPeriods, setAx25Frame, setInvalid, setOriginatingCallsign, setRcptTime, split, storeExtension

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.ka2ddo.ax25.SendableMessage

dup

Field Detail

NUM_KILLED_TRANSMISSIONS

public static final int NUM_KILLED_TRANSMISSIONS

The number of times a "killed" Object/Item should be transmitted so everyone knows it is killed.

See Also:

Constant Field Values

objectName

public java.lang.String objectName

Name of Object or Item. Limited to 9 characters,

life

public char life

Flag indicating whether Object is still active (alive) or has been decommissioned (dead).

savedTimestamp

public java.lang.String savedTimestamp

Timestamp in Object message (null for Items).

scope

public Scope scope

Scope for the transmission of locally-originated Objects.

digipeatPaths

public java.lang.String[] digipeatPaths

Digipeating paths (in proportional pathing order) for transmitting locally-originated Objects.

qruCategory

public java.lang.String qruCategory

QRU category to associate with locally-originated Item, or null for no QRU group.

fastSendRate

public int fastSendRate

The transmission rate to initially use for this Object. If left at -1, the default for the transmitting program is obtained and used.

decayRatio

public int decayRatio

The ratio of expansion of the transmission interval as the rate slows from the fast rate to the slow rate.

slowSendRate

public int slowSendRate

The transmission rate to decay to for this Object. If left at -1, the default for the transmitting program is obtained and used.

Constructor Detail

ObjectReport

public ObjectReport(byte[] body,
                    int offset,
                    java.lang.String tp,
                    long rcvTimestamp)

Constructor for Object or Item message when decoding a binary AX.25 frame.

Parameters:

body - byte array of frame body

offset - int array index offset for start of message (non-zero for encapsulated messages)

tp - third-party relay String for encapsulated messages, or null for no third-party wrapper

rcvTimestamp - Unix time when message was actually received by YAAC

ObjectReport

public ObjectReport(byte[] body,
                    int offset,
                    java.lang.String tp,
                    AX25Callsign[] digipeaters,
                    long rcvTimestamp)

Constructor for Object or Item message when decoding a binary AX.25 frame.

Parameters:

body - byte array of frame body

offset - int array index offset for start of message (non-zero for encapsulated messages)

tp - third-party relay String for encapsulated messages, or null for no third-party wrapper

digipeaters - array of digipeater AX25Callsigns from the original frame, or null to indicate no digipeaters

rcvTimestamp - Unix time when message was actually received by YAAC

ObjectReport

public ObjectReport(java.lang.String strBody,
                    long rcvTimestamp)

Constructor for Item reports embedded in a Message (the Item-in-Msg encapsulation)

Parameters:

strBody - the Message comment containing the Item report

rcvTimestamp - Unix time when this message was received by YAAC

ObjectReport

public ObjectReport(boolean isItem,
                    java.lang.String objectName,
                    boolean alive,
                    java.util.Date date,
                    char symTableId,
                    char symbolCode)

Create an ObjectReport suitable for transmission with the basic parameters filled in (some fields will still have to be filled before the message is safe to transmit).

Parameters:

isItem - boolean true if message is for a non-timestamped Item instead of an Object

objectName - the String name of the Object or Item (truncated to 9 characters if needed)

alive - boolean true if the Object/Item is alive

date - Date when this Object was created (meaningless but required for Items)

symTableId - APRS symbol table ID (or overlay character) for this Object/Item

symbolCode - APRS symbol code for this Object/Item

Method Detail

paramString

public java.lang.String paramString()

Descriptive text about this message, to be included in the toString() method's response.

Overrides:

paramString in class PositionMessage

Returns:

String describing the contents of this message

See Also:

Message.toString()

getBody

public byte[] getBody(boolean countTransmission,
                      ProtocolFamily protocolId,
                      AX25Frame frame)

Get an instance of this message, suitable for transmitting.

Specified by:

getBody in interface SendableMessage

Parameters:

countTransmission - number of times this message has been transmitted

protocolId - AX.25 protocol ID to format this message in

frame - AX25Frame into which the message will be placed, so any alternate AX25Message can be linked to it

Returns:

byte array of message

See Also:

AX25Frame.parsedAX25Msg

getStringAPRSBody

public java.lang.String getStringAPRSBody(boolean countTransmission)

Build the transmittable body of a APRS Object or Item message from this data structure,

Parameters:

countTransmission - boolean true if this should update the transmission counters

Returns:

ASCII String of this ObjectReport in APRS format (APRS protocol specification chapter 11)

isEnabled

public boolean isEnabled()

Test if message should still be transmitted.

Specified by:

isEnabled in interface SendableMessage

Overrides:

isEnabled in class PositionMessage

Returns:

boolean true if message should still be transmitted

setEnabled

public void setEnabled(boolean enabled)

Specify whether this message should be transmitted. Applicable only to locally originated Obects/Items.

Parameters:

enabled - boolean true if Object can be transmitted

disableForTransmit

public void disableForTransmit()

Specify that message should no longer be transmitted.

Specified by:

disableForTransmit in interface SendableMessage

isSetEnabled

public boolean isSetEnabled()

Report whether the enable flag is set for this message (independent of expiration or limited scope).

Returns:

boolean true if this message could be transmitted

isAlive

public boolean isAlive()

Test if Object/Item is still alive.

Returns:

boolean true if object is alive.

getObjectName

public java.lang.String getObjectName()

Report the name of the Object or Item.

Returns:

String name of the Object/Item

getScope

public Scope getScope()

Get the transmission scope for this message (so the digipeat path can be derived).

Specified by:

getScope in interface ScopeableMessage

Returns:

Scope of this message

setScope

public void setScope(Scope scope)

Set the transmission scope for this message (so the digipeat path can be derived).

Parameters:

scope - Scope of this message

setTimestamp

public void setTimestamp(long when)

Change the timestamp associated with this Object (should only be done on retransmitted locally-originated Objects).

Overrides:

setTimestamp in class AX25Message

Parameters:

when - time in Java milliseconds since 1 Jan 1970 UTC for this Object

writeToPreferences

public void writeToPreferences(java.util.prefs.Preferences prefs)

Persist this Object/Item in Java Preferences.

Parameters:

prefs - the Preferences object to contain the record of this Object/Item

removeFromPreferences

public void removeFromPreferences(java.util.prefs.Preferences prefs)

Clear this Object/Item from Java Preferences,

Parameters:

prefs - the Preferences object that contained the record of this Object/Item

readFromPreferences

public static ObjectReport readFromPreferences(java.util.prefs.Preferences prefs,
                                               java.lang.String objectName)

Restore a new instance of an Object or Item from its backing store in Java Preferences.

Parameters:

prefs - the Preferences object containing the record of this Object/Item

objectName - the name of the particular Object/Item to be restored

Returns:

a ready-to-transmit ObjectReport

createObjectFromThisPosition

public ObjectReport createObjectFromThisPosition()

Create an ObjectReport from this PositionMessage.

Overrides:

createObjectFromThisPosition in class PositionMessage

Returns:

new ObjectReport cloned from this PositionMessage

bodyEquals

public boolean bodyEquals(AX25Message o)

Compare the contents of the body of the message, reporting if they match.

Overrides:

bodyEquals in class PositionMessage

Parameters:

o - another AX25Message to compare against

Returns:

boolean true if the body values are equivalent

getDecayRatio

public int getDecayRatio()

Get the scaling factor by which the message repeat interval is enlarged (until the default slow send rate is reached).

Specified by:

getDecayRatio in interface SetBeaconRatesIfc

Returns:

int decay ratio

setDecayRatio

public void setDecayRatio(int decayRatio)

Set the scaling factor by which the message repeat interval is enlarged (until the default slow send rate is reached).

Specified by:

setDecayRatio in interface SetBeaconRatesIfc

Parameters:

decayRatio - int decay ratio (should be 2 or 3)

getInitialSendRate

public int getInitialSendRate()

Get the time interval between retransmissions when a message is newly introduced into the system.

Specified by:

getInitialSendRate in interface SetBeaconRatesIfc

Returns:

send interval in seconds

setInitialSendRate

public void setInitialSendRate(int initialSendRate)

Set the time interval between retransmissions when a message is newly introduced into the system.

Specified by:

setInitialSendRate in interface SetBeaconRatesIfc

Parameters:

initialSendRate - send interval in seconds

getSlowSendRate

public int getSlowSendRate()

The slowest rate a message should be sent. For messages to be terminated, they should stop being requeued when the retransmission interval is enlarged to this.

Specified by:

getSlowSendRate in interface SetBeaconRatesIfc

Returns:

transmission interval in seconds

setSlowSendRate

public void setSlowSendRate(int slowSendRate)

Set the slowest rate a message should be sent. For messages to be terminated, they should stop being requeued when the retransmission interval is enlarged to this.

Specified by:

setSlowSendRate in interface SetBeaconRatesIfc

Parameters:

slowSendRate - transmission interval in seconds

isUseGpsForPosition

public boolean isUseGpsForPosition()

Indicate whether beacon data source can dynamically change its position (latitude/longitude), such as for a mobile station with a GPS.

Specified by:

isUseGpsForPosition in interface SetBeaconRatesIfc

Returns:

boolean true if latitude or longitude of beacon can change dynamically (not just through UI)