hudson.model

Interface Item

All Superinterfaces:

AccessControlled, ModelObject, OnMaster, PersistenceRoot, Saveable, SearchableModelObject, SearchItem

All Known Subinterfaces:

BuildableItem, BuildableItemWithBuildWrappers, ParameterizedJobMixIn.ParameterizedJob<JobT,RunT>, SCMedItem, TopLevelItem

All Known Implementing Classes:

AbstractItem, AbstractProject, AbstractTopLevelItem, FreeStyleProject, Job, Project, ViewJob

public interface Item
extends PersistenceRoot, SearchableModelObject, AccessControlled, OnMaster

Basic configuration unit in Hudson.

Every Item is hosted in an ItemGroup called "parent", and some Items are ItemGroups. This form a tree structure, which is rooted at Jenkins.

Unlike file systems, where a file can be moved from one directory to another, Item inherently belongs to a single ItemGroup and that relationship will not change. Think of Windows device manager — an HDD always show up under 'Disk drives' and it can never be moved to another parent. Similarly, ItemGroup is not a generic container. Each subclass of ItemGroup can usually only host a certain limited kinds of Items.

Items have unique names that distinguish themselves among their siblings uniquely. The names can be combined by '/' to form an item full name, which uniquely identifies an Item inside the whole Jenkins.

Author:

Kohsuke Kawaguchi

See Also:

Items, ItemVisitor

Field Summary

Fields

Modifier and Type	Field and Description
static Permission	BUILD
static Permission	CANCEL
static Permission	CONFIGURE
static Permission	CREATE
static Permission	DELETE
static Permission	DISCOVER
static Permission	EXTENDED_READ Ability to view configuration details.
static PermissionGroup	PERMISSIONS
static Permission	READ
static Permission	WIPEOUT
static Permission	WORKSPACE

Fields inherited from interface hudson.model.Saveable

NOOP

Method Summary

Modifier and Type	Method and Description
void	delete() Deletes this item.
default String	getAbsoluteUrl() Deprecated. This method shall NEVER be used during HTML page rendering, as it won't work with network set up like Apache reverse proxy. This method is only intended for the remote API clients who cannot resolve relative references (even this won't work for the same reason, which should be fixed.)
Collection<? extends Job>	getAllJobs() Gets all the jobs that this Item contains as descendants.
String	getDisplayName() Gets the human readable short name of this item.
String	getFullDisplayName() Works like 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<? extends Item>	getParent() Gets the parent that contains this item.
default String	getRelativeNameFrom(Item item) Short for getRelativeNameFrom(item.getParent())
default String	getRelativeNameFrom(ItemGroup g) Gets the relative name to this item from the specified group.
String	getShortUrl() Returns the URL of this item relative to the parent ItemGroup.
String	getUrl() Returns the URL of this item relative to the context root of the application.
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.
default void	onCreatedFromScratch() When an item is created from scratch (instead of copied), this method will be invoked.
void	onLoad(ItemGroup<? extends Item> parent, String name) Called right after when a Item is loaded from disk.
void	save() Save the settings to a file.

Methods inherited from interface hudson.model.PersistenceRoot

getRootDir

Methods inherited from interface hudson.search.SearchableModelObject

getSearch

Methods inherited from interface hudson.search.SearchItem

getSearchIndex, getSearchName, getSearchUrl

Methods inherited from interface hudson.security.AccessControlled

checkAnyPermission, checkPermission, getACL, hasAnyPermission, hasPermission, hasPermission, hasPermission2

Field Detail

PERMISSIONS

static final PermissionGroup PERMISSIONS

CREATE

static final Permission CREATE

DELETE

static final Permission DELETE

CONFIGURE

static final Permission CONFIGURE

READ

static final Permission READ

DISCOVER

static final Permission DISCOVER

EXTENDED_READ

static final Permission EXTENDED_READ

Ability to view configuration details. If the user lacks CONFIGURE then any Secrets must be masked out, even in encrypted form.

See Also:

Secret.ENCRYPTED_VALUE_PATTERN

BUILD

static final Permission BUILD

WORKSPACE

static final Permission WORKSPACE

WIPEOUT

static final Permission WIPEOUT

CANCEL

static final Permission CANCEL

Method Detail

getParent

ItemGroup<? extends Item> getParent()

Gets the parent that contains this item.

getAllJobs

Collection<? extends Job> getAllJobs()

Gets all the jobs that this Item contains as descendants.

getName

String getName()

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.

See Also:

getFullName()

getFullName

String getFullName()

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.

See Also:

Jenkins.getItemByFullName(String,Class)

getDisplayName

String getDisplayName()

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 ModelObject

getFullDisplayName

String getFullDisplayName()

Works like getDisplayName() but return the full path that includes all the display names of the ancestors.

getRelativeNameFrom

@Nullable
default String getRelativeNameFrom(@CheckForNull
                                             ItemGroup g)

Gets the relative name to this item from the specified group.

Parameters:

g - The ItemGroup instance used as context to evaluate the relative name of this item

Returns:

The name of the current item, relative to g, or null if one of the item's parents is not an Item. Nested ItemGroups are separated by a / character (e.g., ../foo/bar).

Since:

1.419

getRelativeNameFrom

@Nullable
default String getRelativeNameFrom(@NonNull
                                             Item item)

Short for getRelativeNameFrom(item.getParent())

Returns:

String like "../foo/bar". null if one of item parents is not an Item.

Since:

1.419

getUrl

String getUrl()

Returns the URL of this item relative to the context root of the application.

Returns:

URL that ends with '/'.

See Also:

for how to implement this.

getShortUrl

String getShortUrl()

Returns the URL of this item relative to the parent ItemGroup.

Returns:

URL that ends with '/'.

See Also:

for how to implement this.

getAbsoluteUrl

@Deprecated
default String getAbsoluteUrl()

Deprecated. This method shall NEVER be used during HTML page rendering, as it won't work with network set up like Apache reverse proxy. This method is only intended for the remote API clients who cannot resolve relative references (even this won't work for the same reason, which should be fixed.)

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.

Returns:

absolute URL.

Throws:

IllegalStateException - if the method is invoked outside the HTTP request processing.

onLoad

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.

Parameters:

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

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.

onCreatedFromScratch

default void onCreatedFromScratch()

When an item is created from scratch (instead of copied), this method will be invoked. Used as the post-construction initialization.

Since:

1.374

save

void save()
   throws IOException

Save the settings to a file. Use Items.getConfigFile(Item) or AbstractItem.getConfigFile() to obtain the file to save the data.

Specified by:

save in interface Saveable

Throws:

IOException - if the persistence failed.

delete

void delete()
     throws IOException,
            InterruptedException

Deletes this item.

Throws:

IOException

InterruptedException