org.ka2ddo.opentrac

Class OpenTracEntity

java.lang.Object

org.ka2ddo.opentrac.OpenTracElement

org.ka2ddo.opentrac.OpenTracEntity

All Implemented Interfaces:

java.io.Serializable

public class OpenTracEntity
extends OpenTracElement

This class defines a sub-component of an OpenTracMessage, for the information elements about one entity managed by a station, where entity extension ID #0 is the station itself. Note that the station callsign-SSID does not have to be for the transmitting station (i.e., this can be a digipeated or I-gated message whose Level 2 wrapper is using the callsign-SSID of the repeating station, not the originating station).

Author:

Andrew Pavlin, KA2DDO

See Also:

Serialized Form

Field Summary

Fields inherited from class org.ka2ddo.opentrac.OpenTracElement

id

Constructor Summary

Constructors

Constructor and Description
OpenTracEntity() Create an empty uninitialized OpenTracEntity.
OpenTracEntity(AX25Callsign station, short extensionId) Create an empty uninitialized OpenTracEntity for the specified callsign/SSID and extension ID.
OpenTracEntity(byte[] body, int offset, int length, boolean includesExtension) Read an OpenTracEntity from a byte array.
OpenTracEntity(int sequenceNumber, OpenTracEntity oldEntity) Create an uninitialized clone of another OpenTracEntity with the changed sequence number.
OpenTracEntity(java.lang.String station, short extensionId) Create an empty uninitialized OpenTracEntity for the specified callsign/SSID and extension ID.

Method Summary

Modifier and Type	Method and Description
void	appendElement(OpenTracElement element) Add another element to this entity.
int	computeBody(byte[] buf, int offset) Generate an OpenTrac entity ID element for this entity.
boolean	equals(java.lang.Object obj) Indicates whether some other object is "equal to" this one.
boolean	equalsElement(OpenTracElement other) Test if this OpenTracElement has the same type and value as another OpenTracElement.
java.lang.String	getCallsign() Get the callsign of this entity with any appended SSID.
java.lang.String	getEntityName() Get the full name of this entity with any appended SSID and entity ID
short	getExtensionId() Get the ID number of the extension being reported by this entity.
OpenTracElement	getMatchingElement(int type) Get the first element of this entity of the specified OpenTrac element ID.
static short	getNextAvailableEntityId(java.lang.String entityName) Get an unused entity ID number for an OpenTracEntity record.
AX25Message.Precedence	getPrecedence() Report the traffic-handling precedence for this entity's elements.
int	getSequenceNumber() Get the sequence number for the data in this entity.
int	hashCode() Returns a hash code value for the object.
boolean	isEntityAddressed() Test if this entity has been properly addressed.
boolean	isEntityEmpty() Test if this entity has any elements.
int	length() Return the number of bytes needed to encode this entity, including all its child elements.
static void	reserveEntityId(short id, java.lang.String entityName) Reserve an entity ID value as already in use.
void	setCallsign(java.lang.String callsign) Set the callsign-SSID of this entity.
java.lang.String	valueString() Returns a string representation of the value of this entity.

Methods inherited from class org.ka2ddo.opentrac.OpenTracElement

getId, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

OpenTracEntity

public OpenTracEntity()

Create an empty uninitialized OpenTracEntity.

OpenTracEntity

public OpenTracEntity(AX25Callsign station,
                      short extensionId)

Create an empty uninitialized OpenTracEntity for the specified callsign/SSID and extension ID.

Parameters:

station - AX25Callsign of station containing the entity

extensionId - extension ID for sub-element within the station

OpenTracEntity

public OpenTracEntity(java.lang.String station,
                      short extensionId)

Create an empty uninitialized OpenTracEntity for the specified callsign/SSID and extension ID.

Parameters:

station - String of station containing the entity

extensionId - extension ID for sub-element within the station

OpenTracEntity

public OpenTracEntity(int sequenceNumber,
                      OpenTracEntity oldEntity)

Create an uninitialized clone of another OpenTracEntity with the changed sequence number.

Parameters:

sequenceNumber - the sequence number to use for this copy

oldEntity - OpenTracEntity whose identifiers should be copied

OpenTracEntity

public OpenTracEntity(byte[] body,
                      int offset,
                      int length,
                      boolean includesExtension)

Read an OpenTracEntity from a byte array.

Parameters:

body - byte array to read the entity from

offset - zero-based starting position in the array to read the entity from

length - number of bytes to read from the array

includesExtension - boolean true if entity includes the extension ID in its encoding

Method Detail

getNextAvailableEntityId

public static short getNextAvailableEntityId(java.lang.String entityName)
                                      throws java.lang.IllegalArgumentException

Get an unused entity ID number for an OpenTracEntity record.

Parameters:

entityName - String name of APRS entity that needs an ID (that should be repeated for same object name)

Returns:

a short entity ID value in the range 1 to 32767

Throws:

java.lang.IllegalArgumentException - if no entity ID values are left unused

reserveEntityId

public static void reserveEntityId(short id,
                                   java.lang.String entityName)
                            throws java.lang.IllegalArgumentException,
                                   java.lang.IllegalStateException

Reserve an entity ID value as already in use. Intended for ObjectReports restored on YAAC restart.

Parameters:

id - entity ID value to reserve

entityName - String name of APRS entity that needs an ID (that should be repeated for same object name)

Throws:

java.lang.IllegalArgumentException - if id value is out of range

java.lang.IllegalStateException - if specified entity ID value is already in use

getExtensionId

public short getExtensionId()

Get the ID number of the extension being reported by this entity.

Returns:

entity ID number, or zero if this is for the station itself

getSequenceNumber

public int getSequenceNumber()

Get the sequence number for the data in this entity.

Returns:

sequence number

isEntityEmpty

public boolean isEntityEmpty()

Test if this entity has any elements.

Returns:

boolean true if the entity doesn't have any elements

getMatchingElement

public OpenTracElement getMatchingElement(int type)

Get the first element of this entity of the specified OpenTrac element ID.

Parameters:

type - OpenTrac element ID

Returns:

OpenTracElement of the specified type ID, or null if no matching element on this entity

appendElement

public void appendElement(OpenTracElement element)

Add another element to this entity.

Parameters:

element - OpenTracElement to add

valueString

public java.lang.String valueString()

Returns a string representation of the value of this entity.

Specified by:

valueString in class OpenTracElement

Returns:

a string representation of the entity.

isEntityAddressed

public boolean isEntityAddressed()

Test if this entity has been properly addressed. Locally-generated entities can be left unaddressed until transmit time, so the correct originating callsign for the transmitting port can be filled in.

Returns:

boolean true if entity has an originator's address (callsign-SSID)

getCallsign

public java.lang.String getCallsign()

Get the callsign of this entity with any appended SSID.

Returns:

String form of the SSID-qualified callsign

setCallsign

public void setCallsign(java.lang.String callsign)

Set the callsign-SSID of this entity.

Parameters:

callsign - String form of the SSID-qualified callsign

getEntityName

public java.lang.String getEntityName()

Get the full name of this entity with any appended SSID and entity ID

Returns:

String form of the SSID-qualified callsign

computeBody

public int computeBody(byte[] buf,
                       int offset)

Generate an OpenTrac entity ID element for this entity.

Specified by:

computeBody in class OpenTracElement

Parameters:

buf - byte array to append the element to

offset - starting index in buf to start appending the element

Returns:

the next unused index in buf after appending this element

length

public int length()

Return the number of bytes needed to encode this entity, including all its child elements.

Specified by:

length in class OpenTracElement

Returns:

byte count needed to hold this entity

getPrecedence

public AX25Message.Precedence getPrecedence()

Report the traffic-handling precedence for this entity's elements.

Returns:

Precedence level for this entity

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.

equalsElement

public boolean equalsElement(OpenTracElement other)

Test if this OpenTracElement has the same type and value as another OpenTracElement.

Specified by:

equalsElement in class OpenTracElement

Parameters:

other - OpenTracElement to compare against this element

Returns:

boolean true if elements are of the same type, class, and value

hashCode

public int hashCode()

Returns a hash code value for the object.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value for this object.

See Also:

Object.equals(Object), System.identityHashCode(java.lang.Object)