Package org.ka2ddo.yaac.pluginapi
Class Provider
java.lang.Object
org.ka2ddo.yaac.pluginapi.Provider
- Direct Known Subclasses:
CoreProvider
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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
This class describes the name and implementing Class of an interface port driver. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
Resource tag name for YAAC Provider version number is too old for this plugin.static final String
Resource tag name for default generic reason for plugin failure.static final int
Define the version of the Provider superclass-defined that this build of YAAC supports. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected static String
buildNewerYaacNeededMsg
(int minVersion) Helper method to create a localized return error message forgetInitFailureReason()
if the reason is due to using a non-upgraded version of core YAAC.String[]
consumeXMLPreferenceData
(String nodeName, String lastNodeName, String key, String value) Process a Preferences node entry when restoring a configuration XML.protected javax.help.HelpSet
findHelpSet
(String helpBaseName, String filePathString) Helper function to load a helpset if a Provider subclass has one.String[]
Specify attributions, credits/acknowledgements, and license references to be displayed in the About dialog box.final String
Get the provider author's name.Get any panels needed by this Provider to provision or configure the services offered by the Provider.Filter[]
Get any filters to add to the main CumulativeBooleanAndFilter in the main class of YAAC.javax.help.HelpSet
Provide an additional HelpSet to merge into the base HelpSet for complete online documentation.Return an icon image associated with this Provider.final String
getInfo()
Get a short description of what this provider provides.Get the explanation why the call torunInitializersBefore(int)
returned failure status.Get AbstractMenuActions to define new menu items from this Provider.final String
getName()
Get the name of the provider.Get PortConnector drivers provided by this Provider.final String
Get the version of the provider.void
Execute this function after calling all of the other functions of the Provider.boolean
runInitializersBefore
(int providerApiVersion) Execute this function before calling any of the other functions of the Provider.
-
Field Details
-
PROVIDER_API_VERSION
public static final int PROVIDER_API_VERSIONDefine 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:- initial release
- Provider API changes to better separate GUI-platform-specific code from the Provider superclass itself
- ???
- ???
- TrackerListener interface API modified
- add KenwoodConnector radio command interface (for use by repeaterfinder plugin)
- add
MsgEventDispatcher
andMsgEventType
API, refactor sounds plugin to use it - add extra type to
MsgEventType
for arbitrary announcements - add generic extra column support for (initially) the Station/Object table view
- reshuffle
GeoMapIfc
andFullGeoMapIfc
so all maps have the capability of locating an OpenStreetMap feature - addition of
WatchedStationsTracker
, removal of obsolete SoundMaker interface, adding adjustable rollover interval and time zone selection toFileLogger
- add
GeoMapGuiIfc
for access toGeoMapIfc
's implementing graphics widgets, refactorDigipeatListener
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 - restructure the GPSStatusPane and some other Java/Swing GUI components so they can be used by the SmallScreen plugin
- add
GuiIfc.getSpeechCustomGrammarForCurrentView()
method and related interfaces, and restructure menus to support optional speech command plugin - provide Map interface access to
WeatherDistributor
, add ability to parseAge
Strings, add new service methods for plugins to find other plugins (YAAC.getProviderByName(String)
andYAAC.getProviderByClassName(String)
), allow quad-sized icons when all icons are double-sized, allow arbitrary reason to create or remove aWatchedStationsTracker.WatchedStation
, add purple color forAttentionAlert
s forAX25Message.Precedence.WELFARE
Precedence, factor out weather MADIS validation logic so it can be called by other code - add support for detailed plugin activation failure message
- add callsign-SSID prompting option for config importer (to restrict replaced
callsigns to valid AX.25 syntax), add support for
FileLogger
FileLogger.RolloverHandler
s, addMultiEnumCellEditor
for table cells using multiple enum classes, allow plugin activation failure to use localized messages from the failed plugin. - 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.
- add
PortExtendedStatusListener
, allow plugins to specify position ambiguity of StationState objects. - replace RXTX serial library with JSSC, with service functions to allow legacy code to be swapped back in if necessary.
- add UTF8StreamReader/Writer classes to improve performance, some incompatible
API changes in
SignableMessage
andSaveableTable
, eliminating UTF8 and ISO_8859_1 Charset constants in AX25Message class - backwards-incompatible change in abstract method signatures of
AbstractQueryHandler
and theGeoMapIfc
interface, extra methods added toGeoMapGuiIfc
that implementing plugins will also have to support, extra BUTTON_FONT property handled byActionRenderer
, move APRS-specific listener registration out of the genericAX25Stack
to theAPRSStack
(specifically theAPRSStack.addAprsMessageListener(org.ka2ddo.aprs.AprsMessageListener)
method), move debug control flags out of YAAC main class toDebugCtl
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 - add new setter method to
AttentionAlert
to indicate whether alert needs to restore auto map centering when the alert times out. - add
StationTracker.getStationByAlias(String)
method, expose line style editors and renderers, fixMainGui.invokeObjectEditor(String, Message, int, int, ObjectReportTransmitter)
to accept dialog titles outside of the core YAAC ResourceBundles - expose
FillEditor
so plugins can use it, allow forcing theScope
of APRS Objects in the ObjectEditor - 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 - 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 - add support for portrait-layout
MainGui.MessagingPanel
, allowSSRenderer
to auto-size APRS symbol icons based on their associated text font size - make
TelemetryMessage
transmittable from the local station, fixJson
encoding to support embedded objects, bombproofAgeSpinnerModel
against uninitialized values and ensure textually-long ages won't get clipped in JSpinners initialized with a short age text, allow put() call onWeatherDistributor
, allow font size adjustment for OpenStreetMap renderer layer, add enum support to JSON parser. - make StringCellRenderer associated with the health monitor TMWeather table model support font rescaling
- change all AX.25 messages to use
ProtocolFamily
enum to help specify whichPortConnector
a particularAX25Frame
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 toTerminal
. - add the
CapabilitiesProvider
interface and methods to register and unregister instances thereof to theStationTracker
so responses to requests for station capabilities can be customized by plugins, add more statistics to PortConnectors to identify digipeated and I-gated traffic - add more complete
Connector
traffic statistics to allow calculating packet routing performance, add new interfaceHasRemoteAppIfc
for network-basedPortConnector
s so that the remote application and its address can be obtained for reporting purposes, makeAddresseeFilter
dynamically modifiable. - 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. - generalize right-click-on-table popup menu processing with the
PopupMenuMouseAdapter
class; add more accessors toDebugCtl
to support dynamic changing of logging categories; augmentLocalizer
to allow looking up ResourceBundle values without throwing exceptions if value is not present, addAX25Message.originatingDest
toAX25Message
to ensure I-gating is done correctly. - add the
TuneIfc
interface so the Kenwood radio view can call a plugin that knows how to implement the TUNE capability, add newGuiContentType
typeGuiContentType.LOCAL_OBJECTS
. - 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 andGuiOsmConstants.StrokeEnum
, addScrollableJPanel
class to UI so that large panels can stay within a reasonably-sized JScrollPane, addSnifferLogFilter
capability
-
PLUGIN_UNKNOWN_INCOMPATIBILITY
Resource tag name for default generic reason for plugin failure.- See Also:
-
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
Create a new plugin Provider specifying extensions to be added to YAAC.- Parameters:
name
- String human-displayed name for this pluginversion
- String version identifier for this pluginauthor
- String name of author(s) of this plugininfo
- String description of what services this plugin provides
-
-
Method Details
-
findHelpSet
Helper function to load a helpset if a Provider subclass has one.- Parameters:
helpBaseName
- String name of HelpSet file, without the filetype or locale extensionsfilePathString
- directory path relative to the YAAC installation directory to search for .hs files- Returns:
- HelpSet if it can be found, else null
-
getName
Get the name of the provider.- Returns:
- provider name 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
Get the provider author's name.- Returns:
- String name of the software author
-
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
Get the explanation why the call torunInitializersBefore(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 withLocalizer.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
Helper method to create a localized return error message forgetInitFailureReason()
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
Return an icon image associated with this Provider.- Returns:
- String relative pathname for this Provider's icon image, or null for no icon
-
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
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
Get any filters to add to the main CumulativeBooleanAndFilter in the main class of YAAC.- Returns:
- array of Filter implementations
-
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
May be overridden by subclasses that define new menu choices.
- Returns:
- array of Action objects
- See Also:
-
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. -
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 restoredlastNodeName
- the last subnode name of the Preferences Node being restoredkey
- String name of value in the node to be restoredvalue
- String value of the value to be restored- Returns:
- String array of Preferences Node path, key, and value, or null if nothing to store
-