public abstract class Plugin extends Object implements Saveable, org.kohsuke.stapler.StaplerProxy
A plugin may derive from this class, or it may directly define extension
points annotated with Extension
. For a list of extension
points, see
https://jenkins.io/redirect/developer/extension-points.
One instance of a plugin is created by Hudson, and used as the entry point to plugin functionality.
A plugin is bound to URL space of Hudson as ${rootURL}/plugin/foo/
,
where "foo" is taken from your plugin name "foo.jpi". All your web resources
in src/main/webapp are visible from this URL, and you can also define Jelly
views against your Plugin class, and those are visible in this URL, too.
Plugin
can have an optional config.jelly
page. If present,
it will become a part of the system configuration page (http://server/hudson/configure).
This is convenient for exposing/maintaining configuration that doesn't
fit any Descriptor
s.
Up until Hudson 1.150 or something, subclasses of Plugin
required
@plugin
javadoc annotation, but that is no longer a requirement.
Modifier and Type | Class and Description |
---|---|
static class |
Plugin.DummyImpl
Dummy instance of
Plugin to be used when a plugin didn't
supply one on its own. |
Modifier and Type | Field and Description |
---|---|
static boolean |
SKIP_PERMISSION_CHECK
Escape hatch for StaplerProxy-based access control
|
Modifier | Constructor and Description |
---|---|
protected |
Plugin()
Deprecated.
Use more modern APIs rather than subclassing.
|
Modifier and Type | Method and Description |
---|---|
void |
configure(net.sf.json.JSONObject formData)
Deprecated.
as of 1.305 override
configure(StaplerRequest,JSONObject) instead |
void |
configure(org.kohsuke.stapler.StaplerRequest req,
net.sf.json.JSONObject formData)
Handles the submission for the system configuration.
|
void |
doDynamic(org.kohsuke.stapler.StaplerRequest req,
org.kohsuke.stapler.StaplerResponse rsp)
This method serves static resources in the plugin under
hudson/plugin/SHORTNAME . |
protected XmlFile |
getConfigXml()
|
Object |
getTarget() |
PluginWrapper |
getWrapper()
Gets the paired
PluginWrapper . |
protected void |
load()
Loads serializable fields of this instance from the persisted storage.
|
void |
postInitialize()
Called after
start() is called for all the plugins. |
void |
save()
Saves serializable fields of this instance to the persisted storage.
|
void |
setServletContext(javax.servlet.ServletContext context)
Called when a plugin is loaded to make the
ServletContext object available to a plugin. |
void |
start()
Called to allow plugins to initialize themselves.
|
void |
stop()
Called to orderly shut down Hudson.
|
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) public static boolean SKIP_PERMISSION_CHECK
@Deprecated protected Plugin()
config.jelly
, configure(StaplerRequest, JSONObject)
, load()
, and save()
can be replaced by GlobalConfiguration
start()
and postInitialize()
can be replaced by Initializer
(or ItemListener.onLoaded()
)
stop()
can be replaced by Terminator
setServletContext(javax.servlet.ServletContext)
can be replaced by Jenkins.servletContext
Plugin.DummyImpl
by default,
which will still route the URL space, serve getWrapper()
, and so on.public void setServletContext(javax.servlet.ServletContext context)
ServletContext
object available to a plugin.
This object allows plugins to talk to the surrounding environment.
The default implementation is no-op.
context
- Always non-null.public PluginWrapper getWrapper()
PluginWrapper
.public void start() throws Exception
This method is called after setServletContext(ServletContext)
is invoked.
You can also use Jenkins.get()
to access the singleton Jenkins instance,
although the plugin start up happens relatively early in the initialization
stage and not all the data are loaded in Jenkins.
If a plugin wants to run an initialization step after all plugins and extension points
are registered, a good place to do that is postInitialize()
.
If a plugin wants to run an initialization step after all the jobs are loaded,
ItemListener.onLoaded()
is a good place.
Exception
- any exception thrown by the plugin during the initialization will disable plugin.ExtensionPoint
,
postInitialize()
public void postInitialize() throws Exception
start()
is called for all the plugins.Exception
- any exception thrown by the plugin during the initialization will disable plugin.public void stop() throws Exception
This is a good opportunity to clean up resources that plugin started.
This method will not be invoked if the start()
failed abnormally.
Exception
- if any exception is thrown, it is simply recorded and shut-down of other
plugins continue. This is primarily just a convenience feature, so that
each plugin author doesn't have to worry about catching an exception and
recording it.@Deprecated public void configure(net.sf.json.JSONObject formData) throws IOException, javax.servlet.ServletException, Descriptor.FormException
configure(StaplerRequest,JSONObject)
insteadIOException
javax.servlet.ServletException
Descriptor.FormException
public void configure(org.kohsuke.stapler.StaplerRequest req, net.sf.json.JSONObject formData) throws IOException, javax.servlet.ServletException, Descriptor.FormException
If this class defines config.jelly
view, be sure to
override this method and persists the submitted values accordingly.
The following is a sample config.jelly
that you can start yours with:
<xmp>
<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
<f:section title="Locale">
<f:entry title="${%Default Language}" help="/plugin/locale/help/default-language.html">
<f:textbox name="systemLocale" value="${it.systemLocale}" />
</f:entry>
</f:section>
</j:jelly>
</xmp>
This allows you to access data as formData.getString("systemLocale")
If you are using this method, you'll likely be interested in
using save()
and load()
.
IOException
javax.servlet.ServletException
Descriptor.FormException
public void doDynamic(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) throws IOException, javax.servlet.ServletException
hudson/plugin/SHORTNAME
.IOException
javax.servlet.ServletException
protected void load() throws IOException
If there was no previously persisted state, this method is no-op.
IOException
public void save() throws IOException
save
in interface Saveable
IOException
- if the persistence failed.protected XmlFile getConfigXml()
load()
and save()
persists data.
This method can be also overridden if the plugin wants to
use a custom XStream
instance to persist data.@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) public Object getTarget()
getTarget
in interface org.kohsuke.stapler.StaplerProxy
Copyright © 2004–2021. All rights reserved.