Class Plugin
- All Implemented Interfaces:
PluginEventListener
,ServiceListener
,ExtensionPoint
- Direct Known Subclasses:
ComponentInfoPlugin
,DataTypeDecompilerHoverPlugin
,DbViewerPlugin
,DomainEventDisplayPlugin
,DomainFolderChangesDisplayPlugin
,DWARFExternalDebugFilesPlugin
,EventDisplayPlugin
,FileSystemBrowserPlugin
,FrontEndPlugin
,FunctionSignatureDecompilerHoverPlugin
,GenerateOldLanguagePlugin
,ImporterPlugin
,JavaHelpPlugin
,ListingMergePanelPlugin
,MemorySearchPlugin
,MergeManagerPlugin
,MnemonicSearchPlugin
,ProgramPlugin
,ReferenceDecompilerHoverPlugin
,RuntimeInfoPlugin
,ScalarValueDecompilerHoverPlugin
,ThemeManagerPlugin
,WindowLocationPlugin
Plugins expose their features or capabilities to users via menu items and buttons that
the user can click on, and via "service" APIs that other Plugins can programmatically subscribe
to, and via PluginEvent
s that are broadcast.
Well formed Plugins:
- Derive from
Plugin
(directly or indirectly). - Class name ends with "Plugin" and does not match any other Plugin, regardless of its location in the package tree.
- Have a
@PluginInfo()
annotation. - Have a constructor with exactly 1 parameter: PluginTool.
-
public MyPlugin(PluginTool tool) { ... }
- Usually overrides
protected void init()
.
Class naming
All Plugin Classes MUST END IN "Plugin". If not, the ClassSearcher will not find them.
Some special Plugins marked with the ProgramaticUseOnly
interface are manually
created and do not follow this naming requirement.
Plugin Life cycle
- Your Plugin's constructor is called
-
- Plugin base class constructor is called.
-
- Services listed in the @PluginInfo annotation are automatically added to dependency list
- Your Plugin publishes any services listed in PluginInfo using
registerServiceProvided()
. (required) - Create Actions (optional)
- Register
Options
with thePluginTool.getOptions(String)
. (optional)
- Other Plugins are constructed, dependencies evaluated, etc.
If your dependencies are not available (i.e., not installed, threw an exception during their initialization, etc), your Plugin'sdispose()
will be called and then your Plugin instance will be discarded. - Your Plugin's
init()
method is called (when its dependencies are met). -
- Call
PluginTool.getService(Class)
to get service implementations. (the service class being requested should already be listed in the @PluginInfo) - Create Actions (optional)
- Other initialization stuff.
- Call
- Your Plugin's
readConfigState(SaveState)
is called. - ...user uses Ghidra...
-
- Your Plugin's
processEvent(PluginEvent)
is called for events. - Your Plugin's Action's methods (i.e.,
actionPerformed
) are called. - Your Plugin's published service methods are called by other Plugins.
- Your Plugin's listener methods are called.
- Your Plugin's
- Plugin is unloaded due to shutdown of the Tool or being disabled by user
-
- Your Plugin's
writeConfigState(SaveState)
is called - override this method to write configuration info into the Tool definition. - Your Plugin's
dispose()
is called - override this method to free any resources and perform any needed cleanup. - Your Plugin's services and events are de-registered automatically.
- Your Plugin's
Plugin Service dependency
All Plugins must be tagged with a@PluginInfo(...)
annotation.
The annotation gives you the ability to declare a dependency on another Plugin
via the servicesRequired
Ghidra will ensure that your Plugin will not be initialized
until all
of its required services are loaded successfully and are available for use when your Plugin
calls the PluginTool.getService(Class)
method.
Conversely, any services your Plugin advertises in @PluginInfo must be published via calls to
registerServiceProvided()
in your Plugin's
constructor.
Cyclic dependencies are not allowed and will cause the Plugin management code to fail to load your Plugin. (i.e., PluginA requires a service that PluginB provides, which requires a service that PluginA provides)
Plugin Service implementation
A Plugin may provide a service to other Plugins by advertising in itsPluginInfo
annotation that it provides
an interface class.
Your Plugin can either directly implement the interface in your Plugin class:
public class MyPlugin extends Plugin implements MyService {....}
or it may delegate the handling of the service interface to another object during its constructor:
public MyPlugin(PluginTool tool) {
...
MyService serviceObj = new MyService() { ... };
registerServiceProvided(MyService.class, serviceObj);
}
When your Plugin directly implements the advertised service interface, you should not
call registerServiceProvided
for that service
interface.
Service interface classes are just normal java interface declarations and have no preconditions or other requirements to be used as a Plugin's advertised service interface.
Optionally, service interface classes can be marked with meta-data via a
@ServiceInfo
annotation that can have a
defaultProvider
property which specifies a Plugin's
class (or classname) that should be auto-loaded to provide an implementation of the service
interface when that service is required by some other Plugin. Without the defaultProvider
information, dependent Plugins will fail to load unless the user manually loads a Plugin
that provides the necessary interface service.
Multiple Plugins can implement the same service interface. Plugins that use that
multi-implemented service will either receive a randomly picked instance if using
PluginTool.getService(Class)
or will receive all implementations if using
PluginTool.getServices(Class)
.
Plugin Events
- Every type of plugin event should be represented by some class extending
PluginEvent
. - One PluginEvent subclass may be used for more than one event type as long as there's some natural grouping.
Component Providers
- A plugin may supply a
ComponentProvider
that provides a visual component when the plugin is added to the tool.
Important interfaces Plugins often need to implement
OptionsChangeListener
- to receive notification when a configuration option is changed by the user.ApplicationLevelPlugin
- marks this Plugin as being suitable for inclusion in the application-level tool.ApplicationLevelOnlyPlugin
- marks this Plugin as application-level only, not usable in an application's sub-tools.ProgramaticUseOnly
- marks this Plugin as special and not for user configuration.
-
Field Summary
Modifier and TypeFieldDescriptionprotected final String
Name of this plugin, derived from the simple class name.protected final PluginDescription
Static information about this Plugin, derived from itsPluginInfo
annotation.protected PluginTool
ThePluginTool
that hosts/contains this Plugin. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionboolean
Request plugin to process URL if supported.boolean
acceptData
(DomainFile[] data) Method called if the plugin supports this domain file.protected boolean
canClose()
Called to force this plugin to terminate any tasks it has running and apply any unsaved data to domain objects or files.protected boolean
Override this method if the plugin needs to cancel the closing of the domain objectprotected void
cleanup()
protected void
close()
Close the plugin.void
Notification that all plugins have had their data states restored.boolean
dependsUpon
(Plugin plugin) Check if this plugin depends on the given pluginprotected final void
deregisterService
(Class<?> interfaceClass, Object service) protected void
dispose()
Tells a plugin that it is no longer needed.boolean
final void
eventSent
(PluginEvent event) Notification that the given plugin event was sent.void
firePluginEvent
(PluginEvent event) Fire the given plugin event; the tool notifies all other plugins who are interested in receiving the given event type.getData()
Get the domain files that this plugin has open.final String
getName()
Returns this plugin's name.final PluginDescription
Returns the staticPluginDescription
object that was derived from the@PluginInfo
annotation at the top of your Plugin.Returns the combination of required and non-required used services.Class<?>[]
Return classes of data types that this plugin can support.final PluginTool
getTool()
Get thePluginTool
that hosts/contains this plugin.Returns an object containing the plugins state.getUndoRedoState
(DomainObject domainObject) Returns an object containing the plugin's state as needed to restore itself after an undo or redo operation.int
hashCode()
boolean
Checks if this plugin is missing a required service.protected boolean
Returns true if this plugin has data that needs saving;protected void
init()
Initialization method; override to add initialization for this plugin.protected final void
internalRegisterEventConsumed
(Class<? extends PluginEvent> eventClass) Register event that this plugin consumes.boolean
protected void
prepareToSave
(DomainObject dObj) Called to allow this plugin to flush any caches to the domain object before it is saved.void
processEvent
(PluginEvent event) Method called to process a plugin event.void
readConfigState
(SaveState saveState) Tells the Plugin to read its data-independent (preferences) properties from the input stream.void
readDataState
(SaveState saveState) Tells the Plugin to read its data-dependent state from the given SaveState object.protected final <T> void
registerDynamicServiceProvided
(Class<? super T> interfaceClass, T service) Used to register a service dynamically, during runtime, instead of during the Plugin's constructor.protected final <T> void
registerServiceProvided
(Class<? super T> interfaceClass, T service) Used to register a service (that has already been announced in this Plugin's PluginInfo annotation viaservicesProvided = SomeService.class
) during the Plugin's constructor phase, IFF the service is implemented by an object other than the Plugin instance itself.void
restoreTransientState
(Object state) Provides the transient state object that was returned in the corresponding getTransientState() call.void
restoreUndoRedoState
(DomainObject domainObject, Object state) Updates the plugin's state based on the data stored in the state object.protected boolean
saveData()
Called to force this plugin to save any domain object data it is controlling.void
serviceAdded
(Class<?> interfaceClass, Object service) Notifies this plugin that a service has been added to the plugin tool.void
serviceRemoved
(Class<?> interfaceClass, Object service) Notifies this plugin that service has been removed from the plugin tool.void
writeConfigState
(SaveState saveState) Tells a Plugin to write any data-independent (preferences) properties to the output stream.void
writeDataState
(SaveState saveState) Tells the Plugin to write any data-dependent state to the output stream.
-
Field Details
-
tool
ThePluginTool
that hosts/contains this Plugin. -
name
Name of this plugin, derived from the simple class name. -
pluginDescription
Static information about this Plugin, derived from itsPluginInfo
annotation.
-
-
Constructor Details
-
Plugin
Construct a new Plugin.- Parameters:
tool
- PluginTool that will host/contain this plugin.
-
-
Method Details
-
cleanup
protected void cleanup() -
getName
Returns this plugin's name.- Returns:
- String name, derived from simple class name.
-
eventSent
Description copied from interface:PluginEventListener
Notification that the given plugin event was sent.- Specified by:
eventSent
in interfacePluginEventListener
- Parameters:
event
- plugin event that was sent
-
processEvent
Method called to process a plugin event. Plugins should override this method if the plugin processes PluginEvents;- Parameters:
event
- plugin to process
-
getTool
Get thePluginTool
that hosts/contains this plugin.- Returns:
- PluginTool
-
getSupportedDataTypes
Return classes of data types that this plugin can support.- Returns:
- classes of data types that this plugin can support
-
acceptData
Method called if the plugin supports this domain file.- Parameters:
data
- array ofDomainFile
s- Returns:
- boolean true if can accept
-
accept
Request plugin to process URL if supported. Actual processing may be delayed and interaction with user may occur (e.g., authentication, approval, etc.).- Parameters:
url
- data URL- Returns:
- boolean true if this plugin can process URL.
-
getData
Get the domain files that this plugin has open.- Returns:
- array of
DomainFile
s that are open by this Plugin.
-
init
protected void init()Initialization method; override to add initialization for this plugin. This is where a plugin should acquire its services. When this method is called, all plugins have been instantiated in the tool. -
dispose
protected void dispose()Tells a plugin that it is no longer needed. The plugin should release any resources that it has. All actions, components, services will automatically be cleaned up. -
readConfigState
Tells the Plugin to read its data-independent (preferences) properties from the input stream.- Parameters:
saveState
- object that holds primitives for state information
-
writeConfigState
Tells a Plugin to write any data-independent (preferences) properties to the output stream.- Parameters:
saveState
- object that holds primitives for state information
-
writeDataState
Tells the Plugin to write any data-dependent state to the output stream.- Parameters:
saveState
- object that holds primitives for state information
-
readDataState
Tells the Plugin to read its data-dependent state from the given SaveState object.- Parameters:
saveState
- object that holds primitives for state information
-
firePluginEvent
Fire the given plugin event; the tool notifies all other plugins who are interested in receiving the given event type.- Parameters:
event
- event to fire
-
serviceAdded
Notifies this plugin that a service has been added to the plugin tool. Plugins should override this method if they update their state when a particular service is added.- Specified by:
serviceAdded
in interfaceServiceListener
- Parameters:
interfaceClass
- The interface of the added serviceservice
- service that is being added
-
serviceRemoved
Notifies this plugin that service has been removed from the plugin tool. Plugins should override this method if they update their state when a particular service is removed.- Specified by:
serviceRemoved
in interfaceServiceListener
- Parameters:
interfaceClass
- The interface of the added serviceservice
- that is being removed.
-
dependsUpon
Check if this plugin depends on the given plugin- Parameters:
plugin
- the plugin- Returns:
- true if this plugin depends on the given plugin
-
getMissingRequiredServices
-
hasMissingRequiredService
public boolean hasMissingRequiredService()Checks if this plugin is missing a required service.- Returns:
- boolean true if a required service isn't available via the PluginTool.
-
internalRegisterEventConsumed
Register event that this plugin consumes.This method is for internal use. If plugins wish to manage events consumed, then they should use the
PluginInfo
annotation to do so.- Parameters:
eventClass
- Class for the event; class is required to force it to be loaded
-
registerServiceProvided
Used to register a service (that has already been announced in this Plugin's PluginInfo annotation viaservicesProvided = SomeService.class
) during the Plugin's constructor phase, IFF the service is implemented by an object other than the Plugin instance itself.Do not use this to register a service if your Plugin class implements that service's interface because your Plugin will have been automatically registered as providing that service.
If you need to register a service after the constructor is finished, use
registerDynamicServiceProvided(Class, Object)
.Using this method outside of your constructor will (someday) throw an IllegalArgumentException.
- Parameters:
interfaceClass
- service interface classservice
- service implementation
-
registerDynamicServiceProvided
Used to register a service dynamically, during runtime, instead of during the Plugin's constructor.- Parameters:
interfaceClass
- service interface classservice
- service implementation
-
getServicesRequired
Returns the combination of required and non-required used services.- Returns:
- union of the lists of required and non-required used services.
-
deregisterService
-
canClose
protected boolean canClose()Called to force this plugin to terminate any tasks it has running and apply any unsaved data to domain objects or files. If it can't do this or the user cancels then this returns false.- Returns:
- true if this plugin can close.
-
canCloseDomainObject
Override this method if the plugin needs to cancel the closing of the domain object- Parameters:
dObj
- the domain object- Returns:
- false if the domain object should NOT be closed
-
prepareToSave
Called to allow this plugin to flush any caches to the domain object before it is saved.- Parameters:
dObj
- domain object about to be saved
-
saveData
protected boolean saveData()Called to force this plugin to save any domain object data it is controlling.- Returns:
- false if this plugin controls a domain object, but couldn't save its data or the user canceled the save.
-
hasUnsaveData
protected boolean hasUnsaveData()Returns true if this plugin has data that needs saving;- Returns:
- true if this plugin has data that needs saving;
-
close
protected void close()Close the plugin. This is when the plugin should release resources, such as those from other services. This method should not close resources being used by others (that should happen in dispose()).This method will be called before
dispose()
. -
isDisposed
public boolean isDisposed() -
equals
-
hashCode
public int hashCode() -
restoreTransientState
Provides the transient state object that was returned in the corresponding getTransientState() call. Plugins should override this method if they have state that needs to be saved as domain objects get switched between active and inactive.- Parameters:
state
- the state object that was generated by this plugin's getTransientState() method.
-
getTransientState
Returns an object containing the plugins state. Plugins should override this method if they have state that they want to maintain between domain object state transitions (i.e. when the user tabs to a different domain object and back) Whatever object is returned will be fed back to the plugin after the tool state is switch back to the domain object that was active when the this method was called.- Returns:
- Object to be return in the restoreTransientState() method.
-
dataStateRestoreCompleted
public void dataStateRestoreCompleted()Notification that all plugins have had their data states restored. -
getUndoRedoState
Returns an object containing the plugin's state as needed to restore itself after an undo or redo operation. Plugins should override this method if they have special undo/redo handling.- Parameters:
domainObject
- the object that is about to or has had undoable changes made to it.- Returns:
- the state object
-
restoreUndoRedoState
Updates the plugin's state based on the data stored in the state object. The state object is the object that was returned by this plugin in thegetUndoRedoState(DomainObject)
- Parameters:
domainObject
- the domain object that has had an undo or redo operation applied to it.state
- the state that was recorded before the undo or redo operation.
-
getPluginDescription
Returns the staticPluginDescription
object that was derived from the@PluginInfo
annotation at the top of your Plugin.- Returns:
- the static/shared
PluginDescription
instance that describes this Plugin.
-