hudson

Class Plugin

java.lang.Object

hudson.Plugin

All Implemented Interfaces:

Saveable, org.kohsuke.stapler.StaplerProxy

Direct Known Subclasses:

Plugin.DummyImpl

public abstract class Plugin
extends Object
implements Saveable, org.kohsuke.stapler.StaplerProxy

Base class of Hudson plugin.

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://www.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 Descriptors.

Up until Hudson 1.150 or something, subclasses of Plugin required @plugin javadoc annotation, but that is no longer a requirement.

Since:

1.42

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested Classes

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.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	SKIP_PERMISSION_CHECK Escape hatch for StaplerProxy-based access control

Fields inherited from interface hudson.model.Saveable

NOOP

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Plugin() Deprecated. Use more modern APIs rather than subclassing.

Method Summary

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() Controls the file where load() and save() persists data.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SKIP_PERMISSION_CHECK

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static boolean SKIP_PERMISSION_CHECK

Escape hatch for StaplerProxy-based access control

Constructor Detail

Plugin

@Deprecated
protected Plugin()

Deprecated. Use more modern APIs rather than subclassing.

You do not need to create custom subtypes:

• 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

Note that every plugin gets a Plugin.DummyImpl by default, which will still route the URL space, serve getWrapper(), and so on.

Method Detail

setServletContext

public void setServletContext(javax.servlet.ServletContext context)

Called when a plugin is loaded to make the ServletContext object available to a plugin. This object allows plugins to talk to the surrounding environment.

The default implementation is no-op.

Parameters:

context - Always non-null.

Since:

1.42

getWrapper

public PluginWrapper getWrapper()

Gets the paired PluginWrapper.

Since:

1.426

start

public void start()
           throws Exception

Called to allow plugins to initialize themselves.

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.

Throws:

Exception - any exception thrown by the plugin during the initialization will disable plugin.

Since:

1.42

See Also:

ExtensionPoint, postInitialize()

postInitialize

public void postInitialize()
                    throws Exception

Called after start() is called for all the plugins.

Throws:

Exception - any exception thrown by the plugin during the initialization will disable plugin.

stop

public void stop()
          throws Exception

Called to orderly shut down Hudson.

This is a good opportunity to clean up resources that plugin started. This method will not be invoked if the start() failed abnormally.

Throws:

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.

Since:

1.42

configure

@Deprecated
public void configure(net.sf.json.JSONObject formData)
                           throws IOException,
                                  javax.servlet.ServletException,
                                  Descriptor.FormException

Deprecated. as of 1.305 override configure(StaplerRequest,JSONObject) instead

Throws:

IOException

javax.servlet.ServletException

Descriptor.FormException

Since:

1.233

configure

public void configure(org.kohsuke.stapler.StaplerRequest req,
                      net.sf.json.JSONObject formData)
               throws IOException,
                      javax.servlet.ServletException,
                      Descriptor.FormException

Handles the submission for the system configuration.

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().

Throws:

IOException

javax.servlet.ServletException

Descriptor.FormException

Since:

1.305

doDynamic

public void doDynamic(org.kohsuke.stapler.StaplerRequest req,
                      org.kohsuke.stapler.StaplerResponse rsp)
               throws IOException,
                      javax.servlet.ServletException

This method serves static resources in the plugin under hudson/plugin/SHORTNAME.

Throws:

IOException

javax.servlet.ServletException

load

protected void load()
             throws IOException

Loads serializable fields of this instance from the persisted storage.

If there was no previously persisted state, this method is no-op.

Throws:

IOException

Since:

1.245

save

public void save()
          throws IOException

Saves serializable fields of this instance to the persisted storage.

Specified by:

save in interface Saveable

Throws:

IOException - if the persistence failed.

Since:

1.245

getConfigXml

protected XmlFile getConfigXml()

Controls the file where load() and save() persists data. This method can be also overridden if the plugin wants to use a custom XStream instance to persist data.

Since:

1.245

getTarget

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public Object getTarget()

Specified by:

getTarget in interface org.kohsuke.stapler.StaplerProxy