Package hudson.model

Class AbstractItem

java.lang.Object
hudson.model.AbstractModelObject
hudson.model.Actionable
hudson.model.AbstractItem
All Implemented Interfaces:
DescriptorByNameOwner, Item, ModelObject, PersistenceRoot, Saveable, SearchableModelObject, SearchItem, AccessControlled, Loadable, ModelObjectWithContextMenu, OnMaster, org.kohsuke.stapler.HttpDeletable, org.kohsuke.stapler.StaplerProxy
Direct Known Subclasses:
AbstractTopLevelItem, Job
@ExportedBean public abstract class AbstractItem extends Actionable implements Loadable, Item, org.kohsuke.stapler.HttpDeletable, AccessControlled, DescriptorByNameOwner, org.kohsuke.stapler.StaplerProxy
Partial default implementation of Item.
Author:
Kohsuke Kawaguchi

  • Field Details

    • name

      protected transient String name
      Project name.

    • description

      protected volatile String description
      Project description. Can be HTML.

    • displayName

      protected String displayName

    • SKIP_PERMISSION_CHECK

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

    • PRONOUN

      public static final AlternativeUiTextProvider.Message<AbstractItem> PRONOUN
      Replaceable pronoun of that points to a job. Defaults to "Job"/"Project" depending on the context.

    • TASK_NOUN

      public static final AlternativeUiTextProvider.Message<AbstractItem> TASK_NOUN
      Replaceable noun for describing the kind of task that this item represents. Defaults to "Build".

  • Constructor Details

  • Method Details

    • getName

      @Exported(visibility=999) public String getName()
      Description copied from interface: Item
      Gets the name of the item.

      The name must be unique among other Items that belong to the same parent.

      This name is also used for directory name, so it cannot contain any character that's not allowed on the file system.

      Specified by:
      getName in interface Item
      See Also:

    • getPronoun

      public String getPronoun()
      Get the term used in the UI to represent this kind of Item. Must start with a capital letter.

    • getTaskNoun

      public String getTaskNoun()
      Gets the term used in the UI to represent the kind of Queue.Task associated with this kind of Item. Must start with a capital letter. Defaults to "Build".
      Since:
      2.50

    • getDisplayName

      @Exported public String getDisplayName()
      Description copied from interface: Item
      Gets the human readable short name of this item.

      This method should try to return a short concise human readable string that describes this item. The string need not be unique.

      The returned string should not include the display names of ancestor items.

      Specified by:
      getDisplayName in interface Item
      Specified by:
      getDisplayName in interface ModelObject
      Returns:
      The display name of this object, or if it is not set, the name of the object.

    • getDisplayNameOrNull

      @Exported public String getDisplayNameOrNull()
      This is intended to be used by the Job configuration pages where we want to return null if the display name is not set.
      Returns:
      The display name of this object or null if the display name is not set

    • setDisplayNameOrNull

      public void setDisplayNameOrNull(String displayName) throws IOException
      This method exists so that the Job configuration pages can use getDisplayNameOrNull so that nothing is shown in the display name text box if the display name is not set.
      Throws:
      IOException

    • setDisplayName

      public void setDisplayName(String displayName) throws IOException
      Throws:
      IOException

    • getRootDir

      public File getRootDir()
      Description copied from interface: PersistenceRoot
      Gets the root directory on the file system that this Item can use freely for storing the configuration data.

      This parameter is given by the ItemGroup when Item is loaded from memory.

      Specified by:
      getRootDir in interface PersistenceRoot

    • getParent

      @WithBridgeMethods(value=Jenkins.class, castRequired=true) @NonNull public ItemGroup getParent()
      This bridge method is to maintain binary compatibility with Item.getParent().
      Specified by:
      getParent in interface Item

    • getDescription

      @Exported public String getDescription()
      Gets the project description HTML.

    • setDescription

      public void setDescription(String description) throws IOException
      Sets the project description HTML.
      Throws:
      IOException

    • doSetName

      protected void doSetName(String name)
      Just update name without performing the rename operation, which would involve copying files and etc.

    • isNameEditable

      public boolean isNameEditable()
      Controls whether the default rename action is available for this item.
      Returns:
      whether name can be modified by a user
      Since:
      2.110
      See Also:

    • doConfirmRename

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public org.kohsuke.stapler.HttpResponse doConfirmRename(@QueryParameter String newName) throws IOException
      Renames this item
      Throws:
      IOException

    • doCheckNewName

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) @NonNull public FormValidation doCheckNewName(@QueryParameter String newName)
      Called by doConfirmRename(java.lang.String) and rename.jelly to validate renames.
      Returns:
      FormValidation.ok(java.lang.String) if this item can be renamed as specified, otherwise FormValidation.error(java.lang.String) with a message explaining the problem.

    • checkRename

      protected void checkRename(@NonNull String newName) throws Failure
      Allows subclasses to block renames for domain-specific reasons. Generic validation of the new name (e.g., null checking, checking for illegal characters, and checking that the name is not in use) always happens prior to calling this method.
      Parameters:
      newName - the new name for the item
      Throws:
      Failure - if the rename should be blocked
      Since:
      2.110
      See Also:

    • renameTo

      protected void renameTo(String newName) throws IOException
      Renames this item. Not all the Items need to support this operation, but if you decide to do so, you can use this method.
      Throws:
      IOException

    • movedTo

      public void movedTo(DirectlyModifiableTopLevelItemGroup destination, AbstractItem newItem, File destDir) throws IOException
      Notify this item it's been moved to another location, replaced by newItem (might be the same object, but not guaranteed). This method is executed after the item root directory has been moved to it's new location.

      Derived classes can override this method to add some specific behavior on move, but have to call parent method so the item is actually setup within it's new parent.

      Throws:
      IOException
      See Also:

    • getAllJobs

      public abstract Collection<? extends Job> getAllJobs()
      Gets all the jobs that this Item contains as descendants.
      Specified by:
      getAllJobs in interface Item

    • getFullName

      @Exported public final String getFullName()
      Description copied from interface: Item
      Gets the full name of this item, like "abc/def/ghi".

      Full name consists of names of Items that lead from the root Jenkins to this Item, separated by '/'. This is the unique name that identifies this Item inside the whole Jenkins.

      Specified by:
      getFullName in interface Item
      See Also:

    • getFullDisplayName

      @Exported public final String getFullDisplayName()
      Description copied from interface: Item
      Works like Item.getDisplayName() but return the full path that includes all the display names of the ancestors.
      Specified by:
      getFullDisplayName in interface Item

    • getRelativeDisplayNameFrom

      public String getRelativeDisplayNameFrom(ItemGroup p)
      Gets the display name of the current item relative to the given group.
      Parameters:
      p - the ItemGroup used as point of reference for the item
      Returns:
      String like "foo ยป bar"
      Since:
      1.515

    • getRelativeNameFromGroup

      public String getRelativeNameFromGroup(ItemGroup p)
      This method only exists to disambiguate Item.getRelativeNameFrom(ItemGroup) and Item.getRelativeNameFrom(Item)
      Since:
      1.512
      See Also:

    • onLoad

      public void onLoad(ItemGroup<? extends Item> parent, String name) throws IOException
      Called right after when a Item is loaded from disk. This is an opportunity to do a post load processing.
      Specified by:
      onLoad in interface Item
      name - Name of the directory (not a path --- just the name portion) from which the configuration was loaded. This usually becomes the name of this item.
      Throws:
      IOException

    • onCopiedFrom

      public void onCopiedFrom(Item src)
      When a Item is copied from existing one, the files are first copied on the file system, then it will be loaded, then this method will be invoked to perform any implementation-specific work.
      Specified by:
      onCopiedFrom in interface Item
      Parameters:
      src - Item from which it's copied from. The same type as this. Never null.

    • getUrl

      public final String getUrl()
      Description copied from interface: Item
      Returns the URL of this item relative to the context root of the application.
      Specified by:
      getUrl in interface Item
      Returns:
      URL that ends with '/'.
      See Also:

    • getShortUrl

      public String getShortUrl()
      Description copied from interface: Item
      Returns the URL of this item relative to the parent ItemGroup.
      Specified by:
      getShortUrl in interface Item
      Returns:
      URL that ends with '/'.
      See Also:

    • getSearchUrl

      public String getSearchUrl()
      Description copied from interface: SearchItem
      Returns the URL of this item relative to the parent SearchItem.
      Specified by:
      getSearchUrl in interface SearchItem
      Returns:
      URL like "foo" or "foo/bar". The path can end with '/'. The path that starts with '/' will be interpreted as the absolute path (within the context path of Jenkins.)

    • getAbsoluteUrl

      @Exported(visibility=999, name="url") public final String getAbsoluteUrl()
      Description copied from interface: Item
      Returns the absolute URL of this item. This relies on the current StaplerRequest2 to figure out what the host name is, so can be used only during processing client requests.
      Specified by:
      getAbsoluteUrl in interface Item
      Returns:
      absolute URL.

    • getApi

      public final Api getApi()
      Remote API access.

    • getACL

      @NonNull public ACL getACL()
      Returns the ACL for this object.
      Specified by:
      getACL in interface AccessControlled
      Returns:
      never null.

    • save

      public void save() throws IOException
      Save the settings to a file.
      Specified by:
      save in interface Item
      Specified by:
      save in interface Saveable
      Throws:
      IOException - if the persistence failed.

    • getConfigFile

      public final XmlFile getConfigFile()

    • writeReplace

      protected Object writeReplace()

    • doSubmitDescription

      public void doSubmitDescription(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException, jakarta.servlet.ServletException
      Accepts the new description.
      Throws:
      IOException
      jakarta.servlet.ServletException
      Since:
      2.475

    • doSubmitDescription

      @Deprecated @StaplerNotDispatchable public void doSubmitDescription(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) throws IOException, javax.servlet.ServletException
      Deprecated.
      use doSubmitDescription(StaplerRequest2, StaplerResponse2)
      Throws:
      IOException
      javax.servlet.ServletException

    • doDoDelete

      public void doDoDelete(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException, jakarta.servlet.ServletException, InterruptedException
      Deletes this item. Note on the funny name: for reasons of historical compatibility, this URL is /doDelete since it predates <l:confirmationLink>. /delete goes to a Jelly page which should now be unused by core but is left in case plugins are still using it.
      Throws:
      IOException
      jakarta.servlet.ServletException
      InterruptedException
      Since:
      2.475

    • doDoDelete

      @Deprecated @StaplerNotDispatchable public void doDoDelete(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) throws IOException, javax.servlet.ServletException, InterruptedException
      Deprecated.
      use doDoDelete(StaplerRequest2, StaplerResponse2)
      Throws:
      IOException
      javax.servlet.ServletException
      InterruptedException

    • delete

      public void delete(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException, jakarta.servlet.ServletException
      Specified by:
      delete in interface org.kohsuke.stapler.HttpDeletable
      Throws:
      IOException
      jakarta.servlet.ServletException
      Since:
      2.475

    • delete

      @Deprecated public void delete(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) throws IOException, javax.servlet.ServletException
      Deprecated.
      use delete(StaplerRequest2, StaplerResponse2)
      Specified by:
      delete in interface org.kohsuke.stapler.HttpDeletable
      Throws:
      IOException
      javax.servlet.ServletException

    • delete

      public void delete() throws IOException, InterruptedException
      Deletes this item.

      Any exception indicates the deletion has failed, but AbortException would prevent the caller from showing the stack trace.

      Specified by:
      delete in interface Item
      Throws:
      IOException
      InterruptedException
      See Also:

    • performDelete

      protected void performDelete() throws IOException, InterruptedException
      Does the real job of deleting the item.
      Throws:
      IOException
      InterruptedException

    • doConfigDotXml

      @WebMethod(name="config.xml") public void doConfigDotXml(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException
      Accepts config.xml submission, as well as serve it.
      Throws:
      IOException
      Since:
      2.475

    • doConfigDotXml

      @Deprecated @StaplerNotDispatchable public void doConfigDotXml(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) throws IOException
      Deprecated.
      use doConfigDotXml(StaplerRequest2, StaplerResponse2)
      Throws:
      IOException

    • writeConfigDotXml

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public void writeConfigDotXml(OutputStream os) throws IOException
      Writes config.xml to the specified output stream. The user must have at least Item.EXTENDED_READ. If he lacks Item.CONFIGURE, then any Secrets or other sensitive information detected will be masked out.
      Throws:
      IOException
      See Also:

    • updateByXml

      @Deprecated public void updateByXml(StreamSource source) throws IOException
      Deprecated.
      as of 1.473 Use updateByXml(Source)
      Throws:
      IOException

    • updateByXml

      public void updateByXml(Source source) throws IOException
      Updates an Item by its XML definition.
      Parameters:
      source - source of the Item's new definition. The source should be either a StreamSource or a SAXSource, other sources may not be handled.
      Throws:
      IOException
      Since:
      1.473

    • doReload

      public void doReload() throws IOException
      Reloads this job from the disk. Exposed through CLI as well. TODO: think about exposing this to UI
      Throws:
      IOException
      Since:
      1.556

    • load

      public void load() throws IOException
      Description copied from interface: Loadable
      Loads the state of this object from disk.
      Specified by:
      load in interface Loadable
      Throws:
      IOException - The state could not be loaded.

    • getSearchName

      public String getSearchName()
      Description copied from class: AbstractModelObject
      Default implementation that returns the display name.
      Specified by:
      getSearchName in interface SearchItem
      Overrides:
      getSearchName in class AbstractModelObject

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getTarget

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public Object getTarget()
      Specified by:
      getTarget in interface org.kohsuke.stapler.StaplerProxy

    • resolveForCLI

      @CLIResolver public static AbstractItem resolveForCLI(String name) throws org.kohsuke.args4j.CmdLineException
      Used for CLI binding.
      Throws:
      org.kohsuke.args4j.CmdLineException