org.ka2ddo.yaac.pluginapi
Class Provider

java.lang.Object
  extended by org.ka2ddo.yaac.pluginapi.Provider
Direct Known Subclasses:
CoreProvider

public abstract class Provider
extends java.lang.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.


Nested Class Summary
static class Provider.PortEntry
          This class describes the name and implementing Class of an interface port driver.
 
Field Summary
static int PROVIDER_API_VERSION
          Define the version of the Provider superclass-defined that this build of YAAC supports.
 
Constructor Summary
protected Provider(java.lang.String name, java.lang.String version, java.lang.String author, java.lang.String info)
          Create a new plugin Provider specifying extensions to be added to YAAC.
 
Method Summary
protected  javax.help.HelpSet findHelpSet(java.lang.String helpBaseName, java.lang.String filePathString)
          Helper function to load a helpset if a Provider subclass has one.
 java.lang.String[] getAboutAttributions()
          Specify attributions, credits/acknowledgements, and license references to be displayed in the About dialog box.
 java.lang.String getAuthor()
          Get the provider author's name.
 java.util.Map<java.lang.String,java.lang.String> getConfigurationPanels()
          Get any panels needed by this Provider to provision or configure the services offered by the Provider.
 Filter[] getFilters()
          Get any filters to add to the main CumulativeBooleanAndFilter in the main class of YAAC.
 javax.help.HelpSet getHelpSet()
          Provide an additional HelpSet to merge into the base HelpSet for complete online documentation.
 java.lang.String getImageIconPath()
          Return an icon image associated with this Provider.
 java.lang.String getInfo()
          Get a short description of what this provider provides.
 AbstractMenuAction[] getMenuItems()
          Get Actions to define new menu items from this Provider.
 java.lang.String getName()
          Get the name of the provider.
 Provider.PortEntry[] getPortConnectorTypes()
          Get PortConnector drivers provided by this Provider.
 java.lang.String getVersion()
          Get the version of the provider.
 void runInitializersAfter()
          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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

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,

See Also:
runInitializersBefore(int), Constant Field Values
Constructor Detail

Provider

protected Provider(java.lang.String name,
                   java.lang.String version,
                   java.lang.String author,
                   java.lang.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 Detail

findHelpSet

protected javax.help.HelpSet findHelpSet(java.lang.String helpBaseName,
                                         java.lang.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 java.lang.String getName()
Get the name of the provider.

Returns:
provider name String

getVersion

public final java.lang.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 java.lang.String getAuthor()
Get the provider author's name.

Returns:
String name of the software author

getInfo

public final java.lang.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).

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)

getImageIconPath

public java.lang.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 java.util.Map<java.lang.String,java.lang.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:
YAAC.getMsg(String), YAAC.getMsg(String, String), YAAC.getMsgBundle(), YAAC.getMsgBundle(String)

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 Actions to define new menu items from this Provider. Actions must define the following properties: Other properties defined by Action or this class may also be specified. In particular, "selected" triggers use of JCheckBoxMenuItem or JRadioButtonMenuItem, and "BUTTON_GROUP_NAME" differentiates between them (JRadioButtonMenuItems are always associated with ButtonGroups).

May be overridden by subclasses that define new menu choices.

Returns:
array of Action objects
See Also:
AbstractMenuAction, AbstractPopupMenuAction

getAboutAttributions

public java.lang.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.