Package org.ka2ddo.yaac.pluginapi

Class Provider

java.lang.Object
org.ka2ddo.yaac.pluginapi.Provider
Direct Known Subclasses:
CoreProvider
public abstract class Provider extends Object
This class defines the structure of a plugin extension's definition. All additions to the core YAAC functionality is specified by querying methods on subclasses of this class.
Author:
Andrew Pavlin, KA2DDO

  • Field Details

    • PROVIDER_API_VERSION

      public static final int PROVIDER_API_VERSION
      Define the version of the Provider superclass-defined that this build of YAAC supports. Used so that plugins depending on newer-version plugin loaders can detect when they are installed on an incompatible release of YAAC. The history of API version changes (to understand why certain plugins need upgrades) is as follows:
      1. initial release
      2. Provider API changes to better separate GUI-platform-specific code from the Provider superclass itself
      3. ???
      4. ???
      5. TrackerListener interface API modified
      6. add KenwoodConnector radio command interface (for use by repeaterfinder plugin)
      7. add MsgEventDispatcher and MsgEventType API, refactor sounds plugin to use it
      8. add extra type to MsgEventType for arbitrary announcements
      9. add generic extra column support for (initially) the Station/Object table view
      10. reshuffle GeoMapIfc and FullGeoMapIfc so all maps have the capability of locating an OpenStreetMap feature
      11. addition of WatchedStationsTracker, removal of obsolete SoundMaker interface, adding adjustable rollover interval and time zone selection to FileLogger
      12. add GeoMapGuiIfc for access to GeoMapIfc's implementing graphics widgets, refactor DigipeatListener interface to support both first and last digipeaters, add Provider callback for processing saved Preference data, add hooks to APRS packet creation to allow plugins to add real-time extra data
      13. restructure the GPSStatusPane and some other Java/Swing GUI components so they can be used by the SmallScreen plugin
      14. add GuiIfc.getSpeechCustomGrammarForCurrentView() method and related interfaces, and restructure menus to support optional speech command plugin
      15. provide Map interface access to WeatherDistributor, add ability to parse Age Strings, add new service methods for plugins to find other plugins (YAAC.getProviderByName(String) and YAAC.getProviderByClassName(String)), allow quad-sized icons when all icons are double-sized, allow arbitrary reason to create or remove a WatchedStationsTracker.WatchedStation, add purple color for AttentionAlerts for AX25Message.Precedence.WELFARE Precedence, factor out weather MADIS validation logic so it can be called by other code
      16. add support for detailed plugin activation failure message
      17. add callsign-SSID prompting option for config importer (to restrict replaced callsigns to valid AX.25 syntax), add support for FileLogger FileLogger.RolloverHandlers, add MultiEnumCellEditor for table cells using multiple enum classes, allow plugin activation failure to use localized messages from the failed plugin.
      18. phase out YAAC-local copies of US_ASCII, ISO_8859_1 and UTF_8 CharSet instances (use StandardCharsets instead), expose CTCSS tone code strings without decimal points.
      19. add PortExtendedStatusListener, allow plugins to specify position ambiguity of StationState objects.
      20. replace RXTX serial library with JSSC, with service functions to allow legacy code to be swapped back in if necessary.
      21. add UTF8StreamReader/Writer classes to improve performance, some incompatible API changes in SignableMessage and SaveableTable, eliminating UTF8 and ISO_8859_1 Charset constants in AX25Message class
      22. backwards-incompatible change in abstract method signatures of AbstractQueryHandler and the GeoMapIfc interface, extra methods added to GeoMapGuiIfc that implementing plugins will also have to support, extra BUTTON_FONT property handled by ActionRenderer, move APRS-specific listener registration out of the generic AX25Stack to the APRSStack (specifically the APRSStack.addAprsMessageListener(org.ka2ddo.aprs.AprsMessageListener) method), move debug control flags out of YAAC main class to DebugCtl utility class, add ability to use other HTTP methods besides GET in the mini-webserver, add font rescaling support to the custom table renderers, support for selectively refusing to use IPv6 network addresses
      23. add new setter method to AttentionAlert to indicate whether alert needs to restore auto map centering when the alert times out.
      24. add StationTracker.getStationByAlias(String) method, expose line style editors and renderers, fix MainGui.invokeObjectEditor(String, Message, int, int, ObjectReportTransmitter) to accept dialog titles outside of the core YAAC ResourceBundles
      25. expose FillEditor so plugins can use it, allow forcing the Scope of APRS Objects in the ObjectEditor
      26. refactored the GPSDistributor so most of its methods are now static, and ensuring that multiple SimpleDateFormat objects can be created to process parallel GPS data streams without collisions in non-thread-safe code
      27. added a GuiSymbols.getQuadStationIcon(char, char) method to GuiSymbols, make GPSStatusPane subpanels rescalable, adding font and icon rescaling for various table cell renderers that didn't already have it, upgrade release of OpenMap to 5.1.15
      28. add support for portrait-layout MainGui.MessagingPanel, allow SSRenderer to auto-size APRS symbol icons based on their associated text font size
      29. make TelemetryMessage transmittable from the local station, fix Json encoding to support embedded objects, bombproof AgeSpinnerModel against uninitialized values and ensure textually-long ages won't get clipped in JSpinners initialized with a short age text, allow put() call on WeatherDistributor, allow font size adjustment for OpenStreetMap renderer layer, add enum support to JSON parser.
      30. make StringCellRenderer associated with the health monitor TMWeather table model support font rescaling
      31. change all AX.25 messages to use ProtocolFamily enum to help specify which PortConnector a particular AX25Frame should be transmitted through (this is incompatible with previous builds, so all dependencies must be updated); fix up AX.25 stack connected-mode protocol support; add getter access to blacklist; add ctl-shift-V clipboard pasting and column width changing escape sequences to Terminal.
      32. add the CapabilitiesProvider interface and methods to register and unregister instances thereof to the StationTracker so responses to requests for station capabilities can be customized by plugins, add more statistics to PortConnectors to identify digipeated and I-gated traffic
      33. add more complete Connector traffic statistics to allow calculating packet routing performance, add new interface HasRemoteAppIfc for network-based PortConnectors so that the remote application and its address can be obtained for reporting purposes, make AddresseeFilter dynamically modifiable.
      34. clearly identify what type of traffic (realtime or hostorical) is returned by a Connector object, so digipeating/I-gating decisions can be made more accurately; add support for plugins to register NMEA-0183 parsers for specific sentence types; add ability to look up installed plugin providers by their primary JAR file name (same as in exported XML configuration); augment some of the generic GUI input dialogs to allow pre-populating with default or old values.
      35. generalize right-click-on-table popup menu processing with the PopupMenuMouseAdapter class; add more accessors to DebugCtl to support dynamic changing of logging categories; augment Localizer to allow looking up ResourceBundle values without throwing exceptions if value is not present, add AX25Message.originatingDest to AX25Message to ensure I-gating is done correctly.
      36. add the TuneIfc interface so the Kenwood radio view can call a plugin that knows how to implement the TUNE capability, add new GuiContentType type GuiContentType.LOCAL_OBJECTS.
      37. add standard code for finding the default location where YAAC will store per-user data (even though many configuration options allow putting selected parts of the data elsewhere, this is the default in a subdirectory of the user's home directory), fix LineEditor class to work with strokes and GuiOsmConstants.StrokeEnum, add ScrollableJPanel class to UI so that large panels can stay within a reasonably-sized JScrollPane, add SnifferLogFilter capability
      See Also:

    • PLUGIN_UNKNOWN_INCOMPATIBILITY

      public static final String PLUGIN_UNKNOWN_INCOMPATIBILITY
      Resource tag name for default generic reason for plugin failure.
      See Also:

    • PLUGIN_NEEDS_NEWER_YAAC_PROTOCOL

      public static final String PLUGIN_NEEDS_NEWER_YAAC_PROTOCOL
      Resource tag name for YAAC Provider version number is too old for this plugin.

      Parameters are:

      {0} - protocol version of running YAAC release, i.e. PROVIDER_API_VERSION

      {1} - minimum protocol number supported by the plugin

      See Also:

  • Constructor Details

    • Provider

      protected Provider(String name, String version, String author, String info)
      Create a new plugin Provider specifying extensions to be added to YAAC.
      Parameters:
      name - String human-displayed name for this plugin
      version - String version identifier for this plugin
      author - String name of author(s) of this plugin
      info - String description of what services this plugin provides

  • Method Details

    • findHelpSet

      protected javax.help.HelpSet findHelpSet(String helpBaseName, String filePathString)
      Helper function to load a helpset if a Provider subclass has one.
      Parameters:
      helpBaseName - String name of HelpSet file, without the filetype or locale extensions
      filePathString - directory path relative to the YAAC installation directory to search for .hs files
      Returns:
      HelpSet if it can be found, else null

    • getName

      public final String getName()
      Get the name of the provider.
      Returns:
      provider name String

    • getVersion

      public final String getVersion()
      Get the version of the provider. Note that, for compatibility with the APRS-IS backbone servers, this string may not contain any embedded spaces.
      Returns:
      String version identifier of this provider

    • getAuthor

      public final String getAuthor()
      Get the provider author's name.
      Returns:
      String name of the software author

    • getInfo

      public final String getInfo()
      Get a short description of what this provider provides.
      Returns:
      descriptive String

    • runInitializersBefore

      public boolean runInitializersBefore(int providerApiVersion)
      Execute this function before calling any of the other functions of the Provider. This allows any Provider-specific initialization to run before menus and drivers are loaded, and also permits the Provider to block usage of the plugin (for example, if the plugin provides services only available on Microsoft Windows, but YAAC is being executed on Mac OS X).

      If this method returns failure, it should provide an explanation for failure via the getInitFailureReason() method; the default implementation of getInitFailureReason() is only to support older plugin builds before this new Provider method was added.

      Parameters:
      providerApiVersion - the int version of the Provider API supported by the build of YAAC trying to load this plugin
      Returns:
      boolean false if this plugin cannot be loaded for some reason (such as missing pre-requisite software on the executing platform, or requiring a version of YAAC newer than the executing one)

    • getInitFailureReason

      public String getInitFailureReason()
      Get the explanation why the call to runInitializersBefore(int) returned failure status. If this is an older plugin that does not override this method, the answer will always be "unknown plugin incompatibility." If the string contains a package-qualified file name followed by a colon and more string text, it will be assumed to be a translation tag that should be looked up with Localizer.getMsg(String), otherwise it will be displayed as-is to the user. If the localized error message has parameters that should be substituted into it, overrides of this method should do the lookup and MessageFormat substitution itself rather than expecting YAAC to do it, i.e., return MessageFormat.format(Localizer.getMsg(PLUGIN_NEEDS_NEWER_YAAC_PROTOCOL), YAAC.getCoreProviderVersion(), 15);

      The superclass method buildNewerYaacNeededMsg(int) is available to produce one particular case of such a message if needed.

      Returns:
      String of failure reason (or resource tag name if begun with a package-qualified Resource name), or null if the plugin successfully initialized
      See Also:

    • buildNewerYaacNeededMsg

      protected static String buildNewerYaacNeededMsg(int minVersion)
      Helper method to create a localized return error message for getInitFailureReason() if the reason is due to using a non-upgraded version of core YAAC.
      Parameters:
      minVersion - the minimum provider API version number this plugin will accept
      Returns:
      formatted localized error String stating that YAAC needs an upgrade before using this plugin

    • getImageIconPath

      public String getImageIconPath()
      Return an icon image associated with this Provider.
      Returns:
      String relative pathname for this Provider's icon image, or null for no icon

    • getPortConnectorTypes

      public Provider.PortEntry[] getPortConnectorTypes()
      Get PortConnector drivers provided by this Provider. May be overridden by subclasses that define new drivers.
      Returns:
      array of PortEntry objects pairing port type names to drivers (may be zero-length)

    • getConfigurationPanels

      public Map<String,String> getConfigurationPanels()
      Get any panels needed by this Provider to provision or configure the services offered by the Provider. The class names are expected to have a wildcard '*' in then to indicate where a platform-specific package variation should be plugged in (such as 'gui' for a conventional Java AWT/Swing GUI, or 'android' for an Android configuration view). Note that it expects already-localized strings for the panel names; this is safe because this method is not called until the File->Configure->Expert Mode menu command (installed by the default Provider subclass, CoreProvider) is invoked, by which time all Providers and their associated localized ResourceBundles will be loaded.
      Returns:
      Map of localized tab names to class names of GUI-displayable components to add to the expert-mode ConfigurationDialog when it is invoked (usually, a LinkedHashMap, so the tabs can be provided in a specific order)
      See Also:

    • getFilters

      public Filter[] getFilters()
      Get any filters to add to the main CumulativeBooleanAndFilter in the main class of YAAC.
      Returns:
      array of Filter implementations

    • getMenuItems

      public AbstractMenuAction[] getMenuItems()
      Get AbstractMenuActions to define new menu items from this Provider. Actions must define the following properties:
      • PRE_LOCALIZE_MENU_TAG_NAME - the pre-ResourceBundle.getString() lookup of NAME that potential overriding menu entries can be identified (i.e., "menu.View.Weather.Wind")
      • PRE_LOCALIZED_MENU_HIERARCHY - the array of localization tag names for the menu names in hierarchical order to contain this menu entry (i.e., { "menu.View", "menu.View.Weather" })
      • SMALL_ICON (optional) - to label the menu entry
      Other properties defined by Action or this class may also be specified. In particular, "selected" triggers use of checkbox or radio button menu items, and "BUTTON_GROUP_NAME" differentiates between them (radio button menu items are always associated with button groups).

      May be overridden by subclasses that define new menu choices.

      Returns:
      array of Action objects
      See Also:

    • getAboutAttributions

      public String[] getAboutAttributions()
      Specify attributions, credits/acknowledgements, and license references to be displayed in the About dialog box. This method is called when the Help->About menu choice is selected.

      Expected to be overridden by subclasses.

      Returns:
      array of localized Strings, each containing one attribution or acknowledgement

    • getHelpSet

      public javax.help.HelpSet getHelpSet()
      Provide an additional HelpSet to merge into the base HelpSet for complete online documentation.
      Returns:
      a JavaHelp HelpSet to merge if this Provider has one, or null for no additional HelpSet

    • runInitializersAfter

      public void runInitializersAfter()
      Execute this function after calling all of the other functions of the Provider. This allows any Provider-specific initialization to run after menus and drivers are loaded, such as registering event handlers of various types.
      See Also:

    • consumeXMLPreferenceData

      public String[] consumeXMLPreferenceData(String nodeName, String lastNodeName, String key, String value)
      Process a Preferences node entry when restoring a configuration XML. Note that the provider can ignore this entirely (default implementation) if it does not have persisted configuration data or does not want it copied to another installation of YAAC, or can selectively choose how to process the data if it belongs to the particular Provider.
      Parameters:
      nodeName - the full relative path String of the Preferences Node being restored
      lastNodeName - the last subnode name of the Preferences Node being restored
      key - String name of value in the node to be restored
      value - String value of the value to be restored
      Returns:
      String array of Preferences Node path, key, and value, or null if nothing to store