Package hudson

Class 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

    • Field Detail

      • SKIP_PERMISSION_CHECK

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

    • 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

      • 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

        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(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public Object getTarget()
        Specified by:
        getTarget in interface org.kohsuke.stapler.StaplerProxy