Package hudson

Class Plugin

java.lang.Object
hudson.Plugin
All Implemented Interfaces:
Saveable, Loadable, org.kohsuke.stapler.StaplerProxy
Direct Known Subclasses:
Plugin.DummyImpl
public abstract class Plugin extends Object implements Loadable, 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
    Description
    static final 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
    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
    Description
    protected
    Plugin()
    Deprecated.
    Use more modern APIs rather than subclassing.

  • Method Summary

    Modifier and Type
    Method
    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.
    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 Details

    • SKIP_PERMISSION_CHECK

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public static boolean SKIP_PERMISSION_CHECK
      Escape hatch for StaplerProxy-based access control

  • Constructor Details

  • Method Details

    • 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:

    • 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

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

      Specified by:
      load in interface Loadable
      Throws:
      IOException - The state could not be loaded.
      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(org.kohsuke.accmod.restrictions.NoExternalUse.class) public Object getTarget()
      Specified by:
      getTarget in interface org.kohsuke.stapler.StaplerProxy