Package org.ka2ddo.yaac.io

Class PortConfig

java.lang.Object
org.ka2ddo.yaac.io.PortConfig
All Implemented Interfaces:
Serializable, Comparable<PortConfig>
public class PortConfig extends Object implements Serializable, Comparable<PortConfig>
This class contains all the parameters for configuring a PortConnector in this application, and the encoding and decoding code for saving its value in the persisted configuration data.
Author:
Andrew Pavlin, KA2DDO
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    PortConfig.Cfg
    Port-type-specific configuration parameters for a PortConnector.
    static enum 
    PortConfig.Fields
    Enumeration identifying all the fields in a Cfg sub-record.
    static enum 
    PortConfig.HintType
    For the ConfigImporter, provide hints of how required but non-transferable config fields should be asked for.
    static class 
    PortConfig.RequireFile
    Data structure describing how the ConfigImporter should ask for missing (or blanked-out) required port configuration parameters when they are a file in the filesystem.
    static class 
    PortConfig.RequireHints
    Data structure describing how the ConfigImporter should ask for missing (or blanked-out) required port configuration parameters.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    boolean
    enabled
    Whether port should be opened automatically upon startup.
    static final int
    FLAGS_ALWAYS_RETRY
    Indicates that port opening should always retry if it fails, even on initial opening.
    static final int
    FLAGS_DONT_COALESCE
    When using timeslotting on a TNC port, don't coalesce duplicate packets (such as beacons or status frames).
    static final int
    FLAGS_HARDWARE
    Indicate that PortConfig.Cfg.deviceName is of a hardware device rather than some software concept (like a network port).
    static final int
    FLAGS_HF
    Indicates this is a TNC port over HF (low bandwidth, wide geographic coverage).
    static final int
    FLAGS_IS_SRV_INST_NAME
    When looking up a TCP/IP network object, the deviceName is not a fully-qualified domain name (FQDN) or numeric IP address of the target, but rather a service instance name for some service supported by the port per Internet RFC 6763 (DNS-Based Service Discovery), such that the code needs to do a service discovery to get the correct host name prior to using DNS to translate the host name.
    static final int
    FLAGS_LOCAL
    Indicates that this data should be consumed locally as well as transmitted.
    static final int
    FLAGS_MASK_KISSPORT
    These four bits contain the KISS device ID to be used in KISS frames sent through this port.
    static final int
    FLAGS_NODTR
    Indicates that non-flow-control serial ports should not raise the DTR and RTS signals.
    static final int
    FLAGS_PIPELINED
    Indicates that this port does not require the port driver to wait for the external device to finish processing the last outbound traffic before sending more traffic.
    static final int
    FLAGS_SHIFT_KISSPORT
    This constant gets the number of bits to shift the above FLAGS_MASK_KISSPORT bits right to put them in the least significant bits of an integer value.
    static final int
    FLAGS_UDP
    Indicates this is a UDP socket (not TCP).
    static final int
    FLAGS_USE_WORKAROUND
    Indicates that work-around for strange device features should be used on this port.
    static final int
    MAX_PROTOCOL_BIT
    Highest bit number supported in protocol bit mask.
    static final String[]
    NO_ALIASES
    Empty array for ports that have no supported aliases.
    String
    portType
    Type of PortConnector used to implement this port, generally defined as a String constant named PORT_TYPE on the PortConnector subclass.
    static final int
    PROTOCOL_APRS
    Flag bit indicating this port allows transmitting APRS packets.
    static final int
    PROTOCOL_AX25
    Flag bit indicating this port allows transmitting AX.25 frames containing traffic of types other than APRS or OpenTRAC UI frames.
    static final int
    PROTOCOL_OPENTRAC
    Flag bit indicating this port allows transmitting OpenTRAC packets.
    static final int
    SENTENCE_GPWPL
    Send NMEA standard waypoint message back to GPS.
    static final int
    SENTENCE_NONE
    No waypoint sentences sent to GPS on this port.
    static final int
    SENTENCE_PKWDWPL
    Send Kenwood-specific waypoint message back to GPS.

  • Constructor Summary

    Constructors
    Constructor
    Description
    PortConfig()
    Create a new PortConfig record with a new port instance identifier.
    PortConfig(String displayName)
    Craete a PortConfig record with the specified port instance identifier.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    assignPortNumber()
    Allocate a new port number for this PortConfig object.
    int
    compareTo(PortConfig other)
    Compares this object with the specified object for order.
    void
    copyInto(PortConfig dest)
    Do a deep copy of this PortConfig object into another object..
    final PortConfig.Cfg
    current()
    Get the port-type-specific configuration parameters for the currently specified port type.
    void
    decodePreferenceValue(String values)
    Decode the storage format used to store a PortConfig in Java Preferences into this PortConfig object.
    PortConfig
    dup()
    Make a deep copy of this PortConfig object.
    boolean
    equals(Object obj)
    Indicates whether some other object is "equal to" this one.
    String
    generatePrefsString()
    Generate the encoded String for storing the PortConfig into Java Preferences.
    String
    getDisplayName()
    Get the name by which this port will be identified.
    int
    getPortNumber()
    Get the arbitrary sequence port number assigned to this configuration record.
    int
    hashCode()
    Returns a hash code value for the object.
    static PortConfig
    readFromPreferences(Preferences root, String displayName)
    Read a PortConfig object from Java Preferences.
    void
    removeFromPreferences(Preferences root)
    Delete this PortConfig from the Java Preferences backing store.
    final PortConfig.Cfg
    specific(String portType)
    Get the port-type-specific configuration parameters for a specific port type.
    String
    toString()
    Returns a string representation of the object.
    void
    writeToPreferences(Preferences root)
    Write this PortConfig object to Java Preferences on the Ports sub-node of the specified Preferences node.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • NO_ALIASES

      public static final String[] NO_ALIASES
      Empty array for ports that have no supported aliases.
      See Also:

    • PROTOCOL_APRS

      public static final int PROTOCOL_APRS
      Flag bit indicating this port allows transmitting APRS packets.
      See Also:

    • PROTOCOL_OPENTRAC

      public static final int PROTOCOL_OPENTRAC
      Flag bit indicating this port allows transmitting OpenTRAC packets.
      See Also:

    • PROTOCOL_AX25

      public static final int PROTOCOL_AX25
      Flag bit indicating this port allows transmitting AX.25 frames containing traffic of types other than APRS or OpenTRAC UI frames.
      See Also:

    • MAX_PROTOCOL_BIT

      public static final int MAX_PROTOCOL_BIT
      Highest bit number supported in protocol bit mask.
      See Also:

    • SENTENCE_NONE

      public static final int SENTENCE_NONE
      No waypoint sentences sent to GPS on this port.
      See Also:

    • SENTENCE_GPWPL

      public static final int SENTENCE_GPWPL
      Send NMEA standard waypoint message back to GPS.
      See Also:

    • SENTENCE_PKWDWPL

      public static final int SENTENCE_PKWDWPL
      Send Kenwood-specific waypoint message back to GPS.
      See Also:

    • FLAGS_HF

      public static final int FLAGS_HF
      Indicates this is a TNC port over HF (low bandwidth, wide geographic coverage).
      See Also:

    • FLAGS_UDP

      public static final int FLAGS_UDP
      Indicates this is a UDP socket (not TCP).
      See Also:

    • FLAGS_LOCAL

      public static final int FLAGS_LOCAL
      Indicates that this data should be consumed locally as well as transmitted.
      See Also:

    • FLAGS_NODTR

      public static final int FLAGS_NODTR
      Indicates that non-flow-control serial ports should not raise the DTR and RTS signals.
      See Also:

    • FLAGS_ALWAYS_RETRY

      public static final int FLAGS_ALWAYS_RETRY
      Indicates that port opening should always retry if it fails, even on initial opening. Meant for APRS-IS port driver when used with flaky and/or intermittent Internet connection.
      See Also:

    • FLAGS_USE_WORKAROUND

      public static final int FLAGS_USE_WORKAROUND
      Indicates that work-around for strange device features should be used on this port. For example, the KISS protocol ports use this to control the work-around for Kenwood APRS/TNC radios that could interpret certain characters in a KISS packet as commands from the memory programming application and thereby screw up the radio's settings. However, other TNCs do not accept the work-around.
      See Also:

    • FLAGS_PIPELINED

      public static final int FLAGS_PIPELINED
      Indicates that this port does not require the port driver to wait for the external device to finish processing the last outbound traffic before sending more traffic. This is for ports such as Serial_TNC, which could be connected to quarter-duplex devices like old TNCs that can't handle receiving another outbound packet from the computer while still transmitting the last packet to RF.
      See Also:

    • FLAGS_DONT_COALESCE

      public static final int FLAGS_DONT_COALESCE
      When using timeslotting on a TNC port, don't coalesce duplicate packets (such as beacons or status frames). This is useful for cases such as meteor-scatter operation. Not all TNC port types may support this capability. Note this is coded as a negative value to preserve backwards compatibility with YAAC installations configured at an earlier build.
      See Also:

    • FLAGS_MASK_KISSPORT

      public static final int FLAGS_MASK_KISSPORT
      These four bits contain the KISS device ID to be used in KISS frames sent through this port. This supports the KissOverTcpConnector port type when talking to the DireWolf software TNC which can support up to 6 audio devices (and therefore up to 6 device IDs in KISS frames). Conveniently, since these bits weren't used before, the backwards-compatible default KISS device ID is zero.
      See Also:

    • FLAGS_SHIFT_KISSPORT

      public static final int FLAGS_SHIFT_KISSPORT
      This constant gets the number of bits to shift the above FLAGS_MASK_KISSPORT bits right to put them in the least significant bits of an integer value.
      See Also:

    • FLAGS_IS_SRV_INST_NAME

      public static final int FLAGS_IS_SRV_INST_NAME
      When looking up a TCP/IP network object, the deviceName is not a fully-qualified domain name (FQDN) or numeric IP address of the target, but rather a service instance name for some service supported by the port per Internet RFC 6763 (DNS-Based Service Discovery), such that the code needs to do a service discovery to get the correct host name prior to using DNS to translate the host name.
      See Also:

    • FLAGS_HARDWARE

      public static final int FLAGS_HARDWARE
      Indicate that PortConfig.Cfg.deviceName is of a hardware device rather than some software concept (like a network port).
      See Also:

    • portType

      public String portType
      Type of PortConnector used to implement this port, generally defined as a String constant named PORT_TYPE on the PortConnector subclass.

    • enabled

      public boolean enabled
      Whether port should be opened automatically upon startup.

  • Constructor Details

    • PortConfig

      public PortConfig()
      Create a new PortConfig record with a new port instance identifier.

    • PortConfig

      public PortConfig(String displayName)
      Craete a PortConfig record with the specified port instance identifier.
      Parameters:
      displayName - port identifier name to use

  • Method Details

    • current

      public final PortConfig.Cfg current()
      Get the port-type-specific configuration parameters for the currently specified port type.
      Returns:
      type-specific Cfg record

    • specific

      public final PortConfig.Cfg specific(String portType)
      Get the port-type-specific configuration parameters for a specific port type.
      Parameters:
      portType - the name of the port type whose configuration parameters should be obtained
      Returns:
      type-specific Cfg record (created if it did not previously exist)

    • assignPortNumber

      public void assignPortNumber()
      Allocate a new port number for this PortConfig object.

    • equals

      public boolean equals(Object obj)
      Indicates whether some other object is "equal to" this one.
      Overrides:
      equals in class Object
      Parameters:
      obj - the reference object with which to compare.
      Returns:
      true if this object is the same as the obj argument; false otherwise.
      See Also:

    • hashCode

      public int hashCode()
      Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.
      Overrides:
      hashCode in class Object
      Returns:
      a hash code value for this object.
      See Also:

    • getDisplayName

      public String getDisplayName()
      Get the name by which this port will be identified.
      Returns:
      String port name

    • getPortNumber

      public int getPortNumber()
      Get the arbitrary sequence port number assigned to this configuration record.
      Returns:
      port number

    • toString

      public String toString()
      Returns a string representation of the object.
      Overrides:
      toString in class Object
      Returns:
      a string representation of the object.

    • dup

      public PortConfig dup()
      Make a deep copy of this PortConfig object.
      Returns:
      duplicate PortConfig

    • copyInto

      public void copyInto(PortConfig dest)
      Do a deep copy of this PortConfig object into another object..
      Parameters:
      dest - destination PortConfig

    • compareTo

      public int compareTo(PortConfig other)
      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.
      Specified by:
      compareTo in interface Comparable<PortConfig>
      Parameters:
      other - 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:
      ClassCastException - if the specified object's type prevents it from being compared to this object.

    • writeToPreferences

      public void writeToPreferences(Preferences root)
      Write this PortConfig object to Java Preferences on the Ports sub-node of the specified Preferences node.
      Parameters:
      root - Preferences node to use to store the Ports sub-node

    • generatePrefsString

      public String generatePrefsString()

      Generate the encoded String for storing the PortConfig into Java Preferences. The preferences String consists of multiple expressions separated by semicolon ";" characters. The first expression (required) will have the following format:

      portType,deviceName,baudRateOrPortNumber,callsign,passcode,transmitEnabled[,digipeatAlias[,...]]

      where deviceName and passcode are escaped to be legitimate text in an XML tag body, transmitEnabled is either "true" or "false", and there can be any number of digipeat aliases in the syntax of display-format AX.25 callsign-SSID values.

      The second expression is a APRS-IS filter expression.

      The third expression is "true" or "false" for whether this port is enabled for operation.

      The fourth expression is "true" or "false" for whether flow control (or something overloading the meaning of this field) should be enabled or not.

      The fifth expression is a decimal number of the value of the PortConfig.Cfg.acceptableProtocolsMask bitmask.

      The sixth expression is two decimal numbers separated by a slash "/" character representing the timeslot offset (relative to the top of the cycle) in seconds and the length of the timeslot cycle in seconds. Negative cycle length indicates that timeslotting is not used, but the values are preserved in case the user wants to turn timeslotting back on.

      The seventh expression is a decimal number of the value of the PortConfig.Cfg.flags bitmask. Bit meanings are portType-specific.

      The eighth expression is a pipe "|" separated list of names of BeaconData definitions that should be transmitted through this port. Only meaningful for ports capable of transmitting APRS or OpenTRAC packets.

      Returns:
      encoded String
      See Also:

    • removeFromPreferences

      public void removeFromPreferences(Preferences root)
      Delete this PortConfig from the Java Preferences backing store.
      Parameters:
      root - Preferences node used to store the Ports sub-node

    • readFromPreferences

      public static PortConfig readFromPreferences(Preferences root, String displayName)
      Read a PortConfig object from Java Preferences.
      Parameters:
      root - Preferences node used to store the Ports sub-node
      displayName - the String port identifier name to read
      Returns:
      a populated PortConfig object for the specified name, or null if no such record exists in the specified node of Preferences

    • decodePreferenceValue

      public void decodePreferenceValue(String values)
      Decode the storage format used to store a PortConfig in Java Preferences into this PortConfig object.
      Parameters:
      values - String of encoded values
      See Also: