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, ModelObjectWithContextMenu, OnMaster, org.kohsuke.stapler.HttpDeletable, org.kohsuke.stapler.StaplerProxy

Direct Known Subclasses:

AbstractTopLevelItem, Job

@ExportedBean
public abstract class AbstractItem
extends Actionable
implements Item, org.kohsuke.stapler.HttpDeletable, AccessControlled, DescriptorByNameOwner, org.kohsuke.stapler.StaplerProxy

Partial default implementation of Item.

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested classes/interfaces inherited from interface jenkins.model.ModelObjectWithContextMenu

ModelObjectWithContextMenu.ContextMenu, ModelObjectWithContextMenu.ContextMenuVisibility, ModelObjectWithContextMenu.MenuItem

Field Summary

Fields

Modifier and Type	Field and Description
protected String	description Project description.
protected String	displayName
protected String	name Project name.
static AlternativeUiTextProvider.Message<AbstractItem>	PRONOUN Replaceable pronoun of that points to a job.
static boolean	SKIP_PERMISSION_CHECK Escape hatch for StaplerProxy-based access control
static AlternativeUiTextProvider.Message<AbstractItem>	TASK_NOUN Replaceable noun for describing the kind of task that this item represents.

Fields inherited from interface hudson.model.Item

BUILD, CANCEL, CONFIGURE, CREATE, DELETE, DISCOVER, EXTENDED_READ, PERMISSIONS, READ, WIPEOUT, WORKSPACE

Fields inherited from interface hudson.model.Saveable

NOOP

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractItem(ItemGroup parent, String name)

Method Summary

Modifier and Type	Method and Description
protected void	checkRename(String newName) Allows subclasses to block renames for domain-specific reasons.
void	delete() Deletes this item.
void	delete(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp)
FormValidation	doCheckNewName(String newName) Called by doConfirmRename(java.lang.String) and rename.jelly to validate renames.
void	doConfigDotXml(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Accepts config.xml submission, as well as serve it.
org.kohsuke.stapler.HttpResponse	doConfirmRename(String newName) Renames this item
void	doDoDelete(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Deletes this item.
void	doReload() Reloads this job from the disk.
protected void	doSetName(String name) Just update name without performing the rename operation, which would involve copying files and etc.
void	doSubmitDescription(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Accepts the new description.
String	getAbsoluteUrl() Returns the absolute URL of this item.
ACL	getACL() Returns the ACL for this object.
abstract Collection<? extends Job>	getAllJobs() Gets all the jobs that this Item contains as descendants.
Api	getApi() Remote API access.
XmlFile	getConfigFile()
String	getDescription() Gets the project description HTML.
String	getDisplayName() Gets the human readable short name of this item.
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.
String	getFullDisplayName() Works like Item.getDisplayName() but return the full path that includes all the display names of the ancestors.
String	getFullName() Gets the full name of this item, like "abc/def/ghi".
String	getName() Gets the name of the item.
ItemGroup	getParent() This bridge method is to maintain binary compatibility with Item.getParent().
String	getPronoun() Get the term used in the UI to represent this kind of Item.
String	getRelativeDisplayNameFrom(ItemGroup p) Gets the display name of the current item relative to the given group.
String	getRelativeNameFromGroup(ItemGroup p) This method only exists to disambiguate Item.getRelativeNameFrom(ItemGroup) and Item.getRelativeNameFrom(Item)
File	getRootDir() Gets the root directory on the file system that this Item can use freely for storing the configuration data.
String	getSearchName() Default implementation that returns the display name.
String	getSearchUrl() Returns the URL of this item relative to the parent SearchItem.
String	getShortUrl() Returns the URL of this item relative to the parent ItemGroup.
Object	getTarget()
String	getTaskNoun() Gets the term used in the UI to represent the kind of Queue.Task associated with this kind of Item.
String	getUrl() Returns the URL of this item relative to the context root of the application.
boolean	isNameEditable() Controls whether the default rename action is available for this item.
void	movedTo(DirectlyModifiableTopLevelItemGroup destination, AbstractItem newItem, File destDir) Notify this item it's been moved to another location, replaced by newItem (might be the same object, but not guaranteed).
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.
void	onLoad(ItemGroup<? extends Item> parent, String name) Called right after when a Item is loaded from disk.
protected void	performDelete() Does the real job of deleting the item.
protected void	renameTo(String newName) Renames this item.
static AbstractItem	resolveForCLI(String name) Used for CLI binding.
void	save() Save the settings to a file.
void	setDescription(String description) Sets the project description HTML.
void	setDisplayName(String displayName)
void	setDisplayNameOrNull(String displayName) 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.
String	toString()
void	updateByXml(Source source) Updates an Item by its XML definition.
void	updateByXml(StreamSource source) Deprecated. as of 1.473 Use updateByXml(Source)
void	writeConfigDotXml(OutputStream os) Writes config.xml to the specified output stream.
protected Object	writeReplace()

Methods inherited from class hudson.model.Actionable

addAction, addOrReplaceAction, doContextMenu, getAction, getAction, getActions, getActions, getAllActions, getDynamic, removeAction, removeActions, replaceAction, replaceActions

Methods inherited from class hudson.model.AbstractModelObject

getSearch, getSearchIndex, makeSearchIndex, requirePOST, sendError, sendError, sendError, sendError, sendError

Methods inherited from class java.lang.Object

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

Methods inherited from interface hudson.model.Item

getRelativeNameFrom, getRelativeNameFrom, onCreatedFromScratch

Methods inherited from interface hudson.search.SearchableModelObject

getSearch

Methods inherited from interface hudson.search.SearchItem

getSearchIndex

Methods inherited from interface hudson.security.AccessControlled

checkAnyPermission, checkPermission, hasAnyPermission, hasPermission, hasPermission, hasPermission2

Methods inherited from interface hudson.model.DescriptorByNameOwner

getDescriptorByName

Field Detail

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(value=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 Detail

AbstractItem

protected AbstractItem(ItemGroup parent,
                       String name)

Method Detail

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:

Item.getFullName()

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:

checkRename(java.lang.String), renameTo(java.lang.String)

doConfirmRename

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public org.kohsuke.stapler.HttpResponse doConfirmRename(@QueryParameter
                                                                                                                               String newName)
                                                                                                                        throws IOException

Renames this item

Throws:

IOException

doCheckNewName

@Restricted(value=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:

Job.checkRename(java.lang.String)

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:

Items.move(AbstractItem, jenkins.model.DirectlyModifiableTopLevelItemGroup)

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:

Jenkins.getItemByFullName(String,Class)

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:

Item.getRelativeNameFrom(ItemGroup)

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:

for how to implement this.

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:

for how to implement this.

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 StaplerRequest 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

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.StaplerRequest req,
                                org.kohsuke.stapler.StaplerResponse rsp)
                         throws IOException,
                                javax.servlet.ServletException

Accepts the new description.

Throws:

IOException

javax.servlet.ServletException

doDoDelete

public void doDoDelete(org.kohsuke.stapler.StaplerRequest req,
                       org.kohsuke.stapler.StaplerResponse rsp)
                throws IOException,
                       javax.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

javax.servlet.ServletException

InterruptedException

delete

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

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

Specified by:

delete in interface Item

Throws:

IOException

InterruptedException

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.StaplerRequest req,
                                                         org.kohsuke.stapler.StaplerResponse rsp)
                                                  throws IOException

Accepts config.xml submission, as well as serve it.

Throws:

IOException

writeConfigDotXml

@Restricted(value=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 detected will be masked out.

Throws:

IOException

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

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(value=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