org.ka2ddo.ax25
Class AX25Callsign

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

public final class AX25Callsign
extends java.lang.Object
implements java.lang.Comparable<AX25Callsign>, java.lang.Cloneable, java.io.Serializable

This class defines a single AX.25 callsign (address).

See Also:
Serialized Form

Field Summary
static java.util.Comparator<AX25Callsign> CALLSIGN_COMPARATOR
          A Comparator to use for callsigns when it is more efficient than using the Comparable interface to AX25Callsign.
 boolean h_c
          Has_been_repeated flag (for digipeater callsigns) or command/response flags (for destination and source callsigns).
 boolean last
          Flag bit in SSID byte indicating this is the last callsign in a digipeater sequence.
 boolean valid
          Indicates whether the callsign in this object can be exported as a valid AX.25 binary protocol address.
 
Constructor Summary
AX25Callsign()
          Construct an empty but assumed-valid callsign.
AX25Callsign(byte[] buf, int offset, int length)
          Extract an AX.25 callsign from a byte array in network byte order.
AX25Callsign(java.lang.String textCallsign)
          Construct a AX25Callsign from the string representation of the callsign.
AX25Callsign(java.lang.String textCallsign, int startPos, int endPos)
          Construct a AX25Callsign from the specified sub-string representation of the callsign.
 
Method Summary
 java.lang.Object clone()
          Creates and returns a copy of this object.
 int compareTo(AX25Callsign o)
          Compares this object with the specified object for order.
 void decrementSSID()
          Decrement a non-zero SSID value, as is done for NewN-n paradigm digipeat aliases.
 AX25Callsign dup()
          Create a shallow clone of this AX25Callsign, discarding any cached toString() value.
 boolean equals(java.lang.Object o)
          Test if some other object is the same as this AX25Callsign.
 java.lang.String getBaseCallsign()
          Gets the base callsign (without the AX.25 SSID extension).
static byte getDefaultReserved()
          Get the current default value for the reserved bits of the AX25 callsign SSID byte.
 byte getReserved()
          Get the reserved bits of the 7th byte of the callsign (per the AX.25 specification).
 int getSSID()
          Return the numeric SSID associated with this callsign.
 boolean hasBeenRepeated()
          Report if the hasBeenRepeated flag in the callsign is set.
 int hashCode()
          Returns a hash code for this callsign.
 boolean isNewNParadigmAlias()
          Test if this callsign appears to be a valid New n-N digipeat alias.
static boolean isNewNParadigmAlias(java.lang.String callsign)
          Test if the parameter appears to be a valid New n-N digipeat alias.
static boolean isRealCallsign(java.lang.String callsign)
          Test if a callsign looks like a real callsign (at least one digit somewhere other than the last character, all letters uppercase).
 boolean isValid()
          Indicates if this callsign has valid syntax to be transmitted in the header of an AX.25 frame.
static void setDefaultReserved(byte defaultReserved)
          Set the default value for the reserved bits of newly generated AX25 callsign SSID byte.
 void setReserved(byte reserved)
          Set the reserved bits of the 7th byte of the callsign (per the AX.25 specification).
 void setSSID(int ssid)
          Specify the numeric SSID associated with this callsign.
 java.lang.String toAnnotatedString()
          Return a String representing this AX25Frame object, with an additional note if the reserved field in the SSID byte is not the default value.
 byte[] toByteArray()
          Return the callsign as the actual byte sequence that would be transmitted over the air (without HDLC bit-stuffing).
 java.lang.String toString()
          Return a String representing this AX25Callsign object.
 void write(java.io.OutputStream os, boolean last)
          Encode this AX25Callsign into binary radio transmission format on a stream.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

h_c

public boolean h_c
Has_been_repeated flag (for digipeater callsigns) or command/response flags (for destination and source callsigns).


last

public boolean last
Flag bit in SSID byte indicating this is the last callsign in a digipeater sequence.


valid

public boolean valid
Indicates whether the callsign in this object can be exported as a valid AX.25 binary protocol address.


CALLSIGN_COMPARATOR

public static final java.util.Comparator<AX25Callsign> CALLSIGN_COMPARATOR
A Comparator to use for callsigns when it is more efficient than using the Comparable interface to AX25Callsign.

See Also:
compareTo(AX25Callsign)
Constructor Detail

AX25Callsign

public AX25Callsign()
Construct an empty but assumed-valid callsign.


AX25Callsign

public AX25Callsign(java.lang.String textCallsign)
Construct a AX25Callsign from the string representation of the callsign.

Parameters:
textCallsign - String to parse into an AX.25-compliant callsign

AX25Callsign

public AX25Callsign(java.lang.String textCallsign,
                    int startPos,
                    int endPos)
Construct a AX25Callsign from the specified sub-string representation of the callsign.

Parameters:
textCallsign - String to parse into an AX.25-compliant callsign
startPos - int position in string where callsign starts
endPos - int position in string where callsign ends

AX25Callsign

public AX25Callsign(byte[] buf,
                    int offset,
                    int length)
             throws java.lang.IndexOutOfBoundsException,
                    java.lang.IllegalArgumentException
Extract an AX.25 callsign from a byte array in network byte order.

Parameters:
buf - byte array containing the AX.25-encoded callsign
offset - index into the array where the callsign begins
length - bytes remaining in the array after the offset
Throws:
java.lang.IndexOutOfBoundsException - if not enough bytes left in the array to contain an AX.25 callsign
java.lang.IllegalArgumentException - if the callsign has an invalid format, such as embedded whitespace in the middle of a callsign with following non-blank characters
Method Detail

isRealCallsign

public static boolean isRealCallsign(java.lang.String callsign)
Test if a callsign looks like a real callsign (at least one digit somewhere other than the last character, all letters uppercase). Note this will automatically strip off the SSID (if any) before testing. Note this is safe for empty strings, and will properly report them as not being a valid real-station callsign,

Parameters:
callsign - String callsign to test
Returns:
boolean true if callsign looks like real

isNewNParadigmAlias

public boolean isNewNParadigmAlias()
Test if this callsign appears to be a valid New n-N digipeat alias. Such callsigns are all uppercase ASCII letters except for the last character, which must be a digit between 1 and 7, and the SSID must be less than or equal to the number corresponding to that digit (i.e., WIDE1-7 is not valid).

Returns:
boolean true if this callsign looks like a New n-N digipeat alias

isNewNParadigmAlias

public static boolean isNewNParadigmAlias(java.lang.String callsign)
Test if the parameter appears to be a valid New n-N digipeat alias. Such callsigns are all uppercase ASCII letters except for the last character, which must be a digit between 1 and 7, and the SSID (if present) must be less than or equal to the number corresponding to that digit (i.e., WIDE1-7 is not valid).

Parameters:
callsign - String supposedly containing an AX.25 callsign
Returns:
boolean true if this callsign looks like a New n-N digipeat alias

equals

public boolean equals(java.lang.Object o)
Test if some other object is the same as this AX25Callsign.

Overrides:
equals in class java.lang.Object
Parameters:
o - Object to compare against this callsign
Returns:
boolean true if o is a AX25Callsign with the same value

hashCode

public int hashCode()
Returns a hash code for this callsign.

Overrides:
hashCode in class java.lang.Object
Returns:
a hash code value for this object.

toString

public java.lang.String toString()
Return a String representing this AX25Callsign object.

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

toAnnotatedString

public java.lang.String toAnnotatedString()
Return a String representing this AX25Frame object, with an additional note if the reserved field in the SSID byte is not the default value.

Returns:
descriptive String

compareTo

public int compareTo(AX25Callsign o)
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. Callsigns are compared in the ASCII order of their strings, then using their SSIDs as a tie-breaker. Note that lowercase is not supposed to be used in a callsign, but this comparator ignores it.

Specified by:
compareTo in interface java.lang.Comparable<AX25Callsign>
Parameters:
o - the object 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.ClassCastException - if the specified object's type prevents it from being compared to this object.

write

public void write(java.io.OutputStream os,
                  boolean last)
           throws java.io.IOException
Encode this AX25Callsign into binary radio transmission format on a stream.

Parameters:
os - the OutputStream to write the binary encoding to
last - boolean true if this callsign should have the last bit set in its last byte to indicate there will be no following callsigns according to the AX.25 protocol specification
Throws:
java.io.IOException - if callsign could not be written to the stream

toByteArray

public byte[] toByteArray()
Return the callsign as the actual byte sequence that would be transmitted over the air (without HDLC bit-stuffing).

Returns:
byte array of the callsign

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Creates and returns a copy of this object.

Overrides:
clone in class java.lang.Object
Returns:
a clone of this instance.
Throws:
java.lang.CloneNotSupportedException - if the object's class does not support the Cloneable interface. Will never be thrown by this class.

dup

public AX25Callsign dup()
Create a shallow clone of this AX25Callsign, discarding any cached toString() value.

Returns:
a copy AX25Callsign

getBaseCallsign

public java.lang.String getBaseCallsign()
Gets the base callsign (without the AX.25 SSID extension). Note that the extension may be included in this string if the overall callsign does not comply with AX.25 requirements.

Returns:
String of the base callsign name

getSSID

public int getSSID()
Return the numeric SSID associated with this callsign. Will be zero if the overall callsign does not comply with AX.25 requirements.

Returns:
numeric SSID in the range 0 to 15

setSSID

public void setSSID(int ssid)
Specify the numeric SSID associated with this callsign.

Parameters:
ssid - numeric SSID in the range 0 to 15

decrementSSID

public void decrementSSID()
Decrement a non-zero SSID value, as is done for NewN-n paradigm digipeat aliases.


hasBeenRepeated

public boolean hasBeenRepeated()
Report if the hasBeenRepeated flag in the callsign is set.

Returns:
boolean true if the hasBeenRepeated bit is set

getReserved

public byte getReserved()
Get the reserved bits of the 7th byte of the callsign (per the AX.25 specification).

Returns:
the value of the reserved bits

setReserved

public void setReserved(byte reserved)
Set the reserved bits of the 7th byte of the callsign (per the AX.25 specification).

Parameters:
reserved - the new value of the reserved bits (masked to the range 0 to 3)

isValid

public boolean isValid()
Indicates if this callsign has valid syntax to be transmitted in the header of an AX.25 frame.

Returns:
boolean true if callsign is legal for AX.25 frame transmission

getDefaultReserved

public static byte getDefaultReserved()
Get the current default value for the reserved bits of the AX25 callsign SSID byte.

Returns:
current default RR bit value

setDefaultReserved

public static void setDefaultReserved(byte defaultReserved)
Set the default value for the reserved bits of newly generated AX25 callsign SSID byte.

Parameters:
defaultReserved - current default RR bit value