public class Plugin
extends java.lang.Object
Common superclass for plugins that can be loaded by the app at startup or during runtime. Subclasses must have public no-arg constructor or they will not be loaded.
Shuffleboard will load plugins from all jars found in in the plugin directory
.
This will overwrite pre-existing plugins with the same ID string (eg "edu.wpi.first.shuffleboard.Base") in
encounter order, which is alphabetical by jar name. For example, if a jar file "my_plugins.jar" defines a plugin
with ID "foo.bar" and another jar file "more_plugins.jar" also defines a plugin with that ID, the plugin
from "more_plugins" will be loaded first, then unloaded and replaced with the one from "my_plugins.jar". For this
reason, plugin authors should be careful to use unique group IDs. We recommend Java's reverse-DNS naming scheme.
Plugins must define their properties (developer group ID, name, current version, and summary) with a
@Description
annotation. Defining it in an annotation rather than an instance or class method or
field allows shuffleboard to get data about the plugin without having to load the class or create a new instance of
it. This approach prevents NoClassDefFoundErrors
and
NoSuchMethodErrors
that can arise if a plugin depends on another, or on classes defined in
another plugin JAR, that has not been loaded or is not on the classpath.
For the same reasons, a plugin that depends on another must provide that information with a
@Requires
or @Requirements
annotation. The former is a repeatable
annotation for which the latter is a wrapper; as such, it is recommended to use @Requires
annotations to
increase readability.
Type | Property and Description |
---|---|
javafx.beans.property.BooleanProperty |
loaded |
Modifier | Constructor and Description |
---|---|
protected |
Plugin()
Creates a new plugin instance.
|
Modifier and Type | Method and Description |
---|---|
boolean |
equals(java.lang.Object obj) |
java.lang.String |
fullIdString()
Gets an ID string unique to this plugin in the format
"{groupId}:{name}:{version} . |
java.util.List<ComponentType> |
getComponents()
Gets a list of the non-annotated components defined by this plugin.
|
java.util.List<ElementTypeAdapter<?>> |
getCustomTypeAdapters()
Gets the custom JSON serializers that this plugin requires to properly save and load custom components.
|
java.util.List<DataType> |
getDataTypes()
Gets a list of custom data types that this plugin defines.
|
java.util.Map<DataType,ComponentType> |
getDefaultComponents()
Gets a map of the default components to use for each data type.
|
java.util.List<TabInfo> |
getDefaultTabInfo()
Gets a list of information about any default tabs that shuffleboard should use.
|
java.lang.String |
getGroupId()
The group ID of this plugin.
|
java.lang.String |
getName()
Gets the name of this plugin.
|
java.util.List<javafx.beans.property.Property<?>> |
getProperties()
Deprecated.
use
getSettings() instead |
java.util.List<Converter> |
getRecordingConverters()
Gets a list of converters used to convert Shuffleboard recording files to other formats.
|
java.util.List<Group> |
getSettings()
Gets the user-configurable settings for this plugin.
|
java.util.List<SourceType> |
getSourceTypes()
Gets a list of custom source types that this plugin defines.
|
java.lang.String |
getSummary()
Gets a descriptive string describing what this plugin provides.
|
java.util.List<Theme> |
getThemes()
Gets a list of themes that this plugin defines.
|
java.util.List<TypeAdapter> |
getTypeAdapters() |
com.cedarsoft.version.Version |
getVersion()
Gets the version of this plugin.
|
int |
hashCode() |
java.lang.String |
idString()
Gets an ID string unique to this plugin in the format
"{groupId}:{name}" . |
boolean |
isLoaded()
Checks if this plugin has been loaded.
|
javafx.beans.property.BooleanProperty |
loadedProperty() |
void |
onLoad()
Called when a plugin is loaded.
|
void |
onUnload()
Called when a plugin is unloaded.
|
void |
setLoaded(boolean loaded)
Flags this plugin as loaded or unloaded.
|
static void |
validatePluginClass(java.lang.Class<? extends Plugin> pluginClass)
Validates that a plugin class has valid description and dependency annotations.
|
public final javafx.beans.property.BooleanProperty loadedProperty
isLoaded()
,
setLoaded(boolean)
protected Plugin()
@Description
annotation that
defines the group ID, name, version, and summary of the plugin. If the plugin depends on another (eg the camera
server plugin depends on the network tables one), that should be specified with a @Requires
annotation.InvalidPluginDefinitionException
- if no @Description
annotation is present, or if thepublic static void validatePluginClass(java.lang.Class<? extends Plugin> pluginClass)
pluginClass
- the plugin class to validateInvalidPluginDefinitionException
- if the class has an invalid definitionpublic final java.lang.String getGroupId()
edu.wpi.first.shuffleboard
.
This must combine with getName()
to create a unique identifier for this plugin.public final java.lang.String getName()
public final com.cedarsoft.version.Version getVersion()
public final java.lang.String idString()
"{groupId}:{name}"
.public final java.lang.String fullIdString()
"{groupId}:{name}:{version}
. For example,
"foo.bar:baz:1.0.0".public final java.lang.String getSummary()
public void onLoad()
public void onUnload()
public java.util.List<DataType> getDataTypes()
public java.util.List<SourceType> getSourceTypes()
public java.util.List<ComponentType> getComponents()
public java.util.Map<DataType,ComponentType> getDefaultComponents()
public java.util.List<TypeAdapter> getTypeAdapters()
public java.util.List<Theme> getThemes()
@Deprecated public java.util.List<javafx.beans.property.Property<?>> getProperties()
getSettings()
insteadFlushableProperty
to ensure that a change will only
occur when a user manually confirms the change.public java.util.List<Group> getSettings()
FlushableProperty
to ensure that a change will only
occur when a user manually confirms the change.public java.util.List<TabInfo> getDefaultTabInfo()
public java.util.List<ElementTypeAdapter<?>> getCustomTypeAdapters()
public java.util.List<Converter> getRecordingConverters()
public final boolean isLoaded()
public final javafx.beans.property.BooleanProperty loadedProperty()
isLoaded()
,
setLoaded(boolean)
public final void setLoaded(boolean loaded)
public final boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
public final int hashCode()
hashCode
in class java.lang.Object