org.ka2ddo.opentrac
Class OpenTracEntity

java.lang.Object
  extended by org.ka2ddo.opentrac.OpenTracElement
      extended by 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).

See Also:
Serialized Form

Field Summary
 
Fields inherited from class org.ka2ddo.opentrac.OpenTracElement
id
 
Constructor Summary
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(OpenTracEntity oldEntity, int sequenceNumber)
          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
 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 equals(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()
          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)
          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(OpenTracEntity oldEntity,
                      int sequenceNumber)
Create an uninitialized clone of another OpenTracEntity with the changed sequence number.

Parameters:
oldEntity - OpenTracEntity whose identifiers should be copied
sequenceNumber - the sequence number to use for this copy

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()
                                      throws java.lang.IllegalArgumentException
Get an unused entity ID number for an OpenTracEntity record.

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)
                            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
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.

equals

public boolean equals(OpenTracElement other)
Test if this OpenTracElement has the same type and value as another OpenTracElement.

Specified by:
equals 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)