hudson.model

Class Items

java.lang.Object

hudson.model.Items

public class Items
extends Object

Convenience methods related to Item.

Author:

Kohsuke Kawaguchi

Field Summary

Fields

Modifier and Type	Field and Description
static Comparator<Item>	BY_FULL_NAME A comparator of Item instances that uses a case-insensitive comparison of Item.getFullName().
static Comparator<Item>	BY_NAME A comparator of Item instances that uses a case-insensitive comparison of Item.getName().
static List<TopLevelItemDescriptor>	LIST Deprecated. as of 1.286 Use all() for read access and Extension for registration.
static com.thoughtworks.xstream.XStream	XSTREAM Used to load/save job configuration.
static XStream2	XSTREAM2 Alias to XSTREAM so that one can access additional methods on XStream2 more easily.

Constructor Summary

Constructors

Constructor and Description
Items()

Method Summary

Modifier and Type	Method and Description
static DescriptorExtensionList<TopLevelItem,TopLevelItemDescriptor>	all() Returns all the registered TopLevelItemDescriptors.
static List<TopLevelItemDescriptor>	all(org.acegisecurity.Authentication a, ItemGroup c) Returns all the registered TopLevelItemDescriptors that the specified security principal is allowed to create within the specified item group.
static List<TopLevelItemDescriptor>	all(ItemGroup c) Returns all the registered TopLevelItemDescriptors that the current security principal is allowed to create within the specified item group.
static <T extends Item> Iterable<T>	allItems(org.acegisecurity.Authentication authentication, ItemGroup root, Class<T> type) Gets a read-only view all the Items recursively in the ItemGroup tree visible to the supplied authentication without concern for the order in which items are returned.
static <T extends Item> Iterable<T>	allItems(org.acegisecurity.Authentication authentication, ItemGroup root, Class<T> type, Predicate<T> pred) Gets a read-only view all the Items recursively matching supplied type and predicate conditions in the ItemGroup tree visible to the supplied authentication without concern for the order in which items are returned.
static <T extends Item> Iterable<T>	allItems(ItemGroup root, Class<T> type) Gets a read-only view of all the Items recursively in the ItemGroup tree visible to Jenkins.getAuthentication() without concern for the order in which items are returned.
static <T extends Item> Iterable<T>	allItems(ItemGroup root, Class<T> type, Predicate<T> pred) Gets a read-only view of all the Items recursively matching type and predicate in the ItemGroup tree visible to Jenkins.getAuthentication() without concern for the order in which items are returned.
static String	computeRelativeNamesAfterRenaming(String oldFullName, String newFullName, String relativeNames, ItemGroup context) Computes the relative name of list of items after a rename or move occurred.
static boolean	currentlyUpdatingByXml() Checks whether we are in the middle of creating or configuring an item via XML.
static <T extends Item> T	findNearest(Class<T> type, String name, ItemGroup context) Finds an item whose name (when referenced from the specified context) is closest to the given name.
static <T extends Item> List<T>	fromNameList(ItemGroup context, String list, Class<T> type) Does the opposite of toNameList(Collection).
static <T extends Item> List<T>	fromNameList(String list, Class<T> type) Deprecated. as of 1.406 Use fromNameList(ItemGroup, String, Class)
static <T extends Item> List<T>	getAllItems(ItemGroup root, Class<T> type) Gets all the Items recursively in the ItemGroup tree and filter them by the given type.
static <T extends Item> List<T>	getAllItems(ItemGroup root, Class<T> type, Predicate<T> pred) Similar to getAllItems(ItemGroup, Class) but with a predicate to pre-filter items to avoid checking ACLs unnecessarily and returning items not required by the caller
static String	getCanonicalName(ItemGroup context, String path) Computes the canonical full name of a relative path in an ItemGroup context, handling relative positions ".." and "." as absolute path starting with "/".
static XmlFile	getConfigFile(File dir) The file we save our configuration.
static XmlFile	getConfigFile(Item item) The file we save our configuration.
static TopLevelItemDescriptor	getDescriptor(String fqcn) Deprecated. Underspecified what the parameter is. Descriptor.getId()? A Describable class name?
static Item	load(ItemGroup parent, File dir) Loads a Item from a config file.
static <I extends AbstractItem & TopLevelItem> I	move(I item, DirectlyModifiableTopLevelItemGroup destination) Moves an item between folders (or top level).
static String	toNameList(Collection<? extends Item> items) Converts a list of items into a comma-separated list of full names.
static <V,T extends Throwable> V	whileUpdatingByXml(hudson.remoting.Callable<V,T> callable) Runs a block while making currentlyUpdatingByXml() be temporarily true.

Methods inherited from class java.lang.Object

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

Field Detail

LIST

@Deprecated
public static final List<TopLevelItemDescriptor> LIST

Deprecated. as of 1.286 Use all() for read access and Extension for registration.

List of all installed TopLevelItem types.

BY_NAME

public static final Comparator<Item> BY_NAME

A comparator of Item instances that uses a case-insensitive comparison of Item.getName(). If you are replacing getAllItems(ItemGroup, Class) with allItems(ItemGroup, Class) and need to restore the sort order of a further filtered result, you probably want BY_FULL_NAME.

Since:

2.37

BY_FULL_NAME

public static final Comparator<Item> BY_FULL_NAME

A comparator of Item instances that uses a case-insensitive comparison of Item.getFullName().

Since:

2.37

XSTREAM

public static final com.thoughtworks.xstream.XStream XSTREAM

Used to load/save job configuration. When you extend Job in a plugin, try to put the alias so that it produces a reasonable XML.

XSTREAM2

public static final XStream2 XSTREAM2

Alias to XSTREAM so that one can access additional methods on XStream2 more easily.

Constructor Detail

Items

public Items()

Method Detail

whileUpdatingByXml

public static <V,T extends Throwable> V whileUpdatingByXml(hudson.remoting.Callable<V,T> callable)
                                                    throws T extends Throwable

Runs a block while making currentlyUpdatingByXml() be temporarily true. Use this when you are creating or changing an item.

Type Parameters:

V - a return value type (may be Void)

T - an error type (may be Error)

Parameters:

callable - a block, typically running load(hudson.model.ItemGroup, java.io.File) or Item.onLoad(hudson.model.ItemGroup<? extends hudson.model.Item>, java.lang.String)

Returns:

whatever callable returned

Throws:

T - anything callable throws

T extends Throwable

Since:

1.546

currentlyUpdatingByXml

public static boolean currentlyUpdatingByXml()

Checks whether we are in the middle of creating or configuring an item via XML. Used to determine the newInstance parameter for Trigger.start(J, boolean).

Returns:

true if whileUpdatingByXml(hudson.remoting.Callable<V, T>) is currently being called, false for example when merely starting Jenkins or reloading from disk

Since:

1.546

all

public static DescriptorExtensionList<TopLevelItem,TopLevelItemDescriptor> all()

Returns all the registered TopLevelItemDescriptors.

all

public static List<TopLevelItemDescriptor> all(ItemGroup c)

Returns all the registered TopLevelItemDescriptors that the current security principal is allowed to create within the specified item group.

Since:

1.607

all

public static List<TopLevelItemDescriptor> all(org.acegisecurity.Authentication a,
                                               ItemGroup c)

Returns all the registered TopLevelItemDescriptors that the specified security principal is allowed to create within the specified item group.

Since:

1.607

getDescriptor

@Deprecated
public static TopLevelItemDescriptor getDescriptor(String fqcn)

Deprecated. Underspecified what the parameter is. Descriptor.getId()? A Describable class name?

toNameList

public static String toNameList(Collection<? extends Item> items)

Converts a list of items into a comma-separated list of full names.

fromNameList

@Deprecated
public static <T extends Item> List<T> fromNameList(String list,
                                                                Class<T> type)

Deprecated. as of 1.406 Use fromNameList(ItemGroup, String, Class)

fromNameList

public static <T extends Item> List<T> fromNameList(ItemGroup context,
                                                    @Nonnull
                                                    String list,
                                                    @Nonnull
                                                    Class<T> type)

Does the opposite of toNameList(Collection).

getCanonicalName

public static String getCanonicalName(ItemGroup context,
                                      String path)

Computes the canonical full name of a relative path in an ItemGroup context, handling relative positions ".." and "." as absolute path starting with "/". The resulting name is the item fullName from Jenkins root.

computeRelativeNamesAfterRenaming

public static String computeRelativeNamesAfterRenaming(String oldFullName,
                                                       String newFullName,
                                                       String relativeNames,
                                                       ItemGroup context)

Computes the relative name of list of items after a rename or move occurred. Used to manage job references as names in plugins to support ItemListener.onLocationChanged(hudson.model.Item, java.lang.String, java.lang.String).

In a hierarchical context, when a plugin has a reference to a job as ../foo/bar this method will handle the relative path as "foo" is renamed to "zot" to compute ../zot/bar

Parameters:

oldFullName - the old full name of the item

newFullName - the new full name of the item

relativeNames - coma separated list of Item relative names

context - the {link ItemGroup} relative names refer to

Returns:

relative name for the renamed item, based on the same ItemGroup context

load

public static Item load(ItemGroup parent,
                        File dir)
                 throws IOException

Loads a Item from a config file.

Parameters:

dir - The directory that contains the config file, not the config file itself.

Throws:

IOException

getConfigFile

public static XmlFile getConfigFile(File dir)

The file we save our configuration.

getConfigFile

public static XmlFile getConfigFile(Item item)

The file we save our configuration.

getAllItems

public static <T extends Item> List<T> getAllItems(ItemGroup root,
                                                   Class<T> type)

Gets all the Items recursively in the ItemGroup tree and filter them by the given type. The returned list will represent a snapshot view of the items present at some time during the call. If items are moved during the call, depending on the move, it may be possible for some items to escape the snapshot entirely.

If you do not need to iterate all items, or if the order of the items is not required, consider using allItems(ItemGroup, Class) instead.

Parameters:

root - Root node to start searching from

type - Given type of of items being searched for

Returns:

List of items matching given criteria

Since:

1.512

getAllItems

public static <T extends Item> List<T> getAllItems(ItemGroup root,
                                                   Class<T> type,
                                                   Predicate<T> pred)

Similar to getAllItems(ItemGroup, Class) but with a predicate to pre-filter items to avoid checking ACLs unnecessarily and returning items not required by the caller

Parameters:

root - Root node to start searching from

type - Given type of of items being searched for

pred - Predicate condition to filter items

Returns:

List of items matching given criteria

Since:

2.221

allItems

public static <T extends Item> Iterable<T> allItems(ItemGroup root,
                                                    Class<T> type)

Gets a read-only view of all the Items recursively in the ItemGroup tree visible to Jenkins.getAuthentication() without concern for the order in which items are returned. Each iteration of the view will be "live" reflecting the items available between the time the iteration was started and the time the iteration was completed, however if items are moved during an iteration - depending on the move - it may be possible for such items to escape the entire iteration.

Type Parameters:

T - the type.

Parameters:

root - the root.

type - the type.

Returns:

An Iterable for all items.

Since:

2.37

allItems

public static <T extends Item> Iterable<T> allItems(ItemGroup root,
                                                    Class<T> type,
                                                    Predicate<T> pred)

Gets a read-only view of all the Items recursively matching type and predicate in the ItemGroup tree visible to Jenkins.getAuthentication() without concern for the order in which items are returned. Each iteration of the view will be "live" reflecting the items available between the time the iteration was started and the time the iteration was completed, however if items are moved during an iteration - depending on the move - it may be possible for such items to escape the entire iteration.

Type Parameters:

T - the type.

T - the predicate.

Parameters:

root - the root.

type - the type.

Returns:

An Iterable for all items.

Since:

2.221

allItems

public static <T extends Item> Iterable<T> allItems(org.acegisecurity.Authentication authentication,
                                                    ItemGroup root,
                                                    Class<T> type)

Gets a read-only view all the Items recursively in the ItemGroup tree visible to the supplied authentication without concern for the order in which items are returned. Each iteration of the view will be "live" reflecting the items available between the time the iteration was started and the time the iteration was completed, however if items are moved during an iteration - depending on the move - it may be possible for such items to escape the entire iteration.

Type Parameters:

T - the type.

Parameters:

root - the root.

type - the type.

Returns:

An Iterable for all items.

Since:

2.37

allItems

public static <T extends Item> Iterable<T> allItems(org.acegisecurity.Authentication authentication,
                                                    ItemGroup root,
                                                    Class<T> type,
                                                    Predicate<T> pred)

Gets a read-only view all the Items recursively matching supplied type and predicate conditions in the ItemGroup tree visible to the supplied authentication without concern for the order in which items are returned. Each iteration of the view will be "live" reflecting the items available between the time the iteration was started and the time the iteration was completed, however if items are moved during an iteration - depending on the move - it may be possible for such items to escape the entire iteration.

Type Parameters:

T - the type.

Parameters:

root - the root.

type - the type.

pred - the predicate.

Returns:

An Iterable for all items.

Since:

2.221

findNearest

@CheckForNull
public static <T extends Item> T findNearest(Class<T> type,
                                                           String name,
                                                           ItemGroup context)

Finds an item whose name (when referenced from the specified context) is closest to the given name.

Type Parameters:

T - the type of item being considered

Parameters:

type - same as T

name - the supplied name

context - a context to start from (used to compute relative names)

Returns:

the closest available item

Since:

1.538

move

public static <I extends AbstractItem & TopLevelItem> I move(I item,
                                                             DirectlyModifiableTopLevelItemGroup destination)
                                                      throws IOException,
                                                             IllegalArgumentException

Moves an item between folders (or top level). Fires all relevant events but does not verify that the item’s directory is not currently being used in some way (for example by a running build). Does not check any permissions.

Parameters:

item - some item (job or folder)

destination - the destination of the move (a folder or Jenkins); not the current parent (or you could just call AbstractItem.renameTo(java.lang.String))

Returns:

the new item (usually the same object as item)

Throws:

IOException - if the move fails, or some subsequent step fails (directory might have already been moved)

IllegalArgumentException - if the move would really be a rename, or the destination cannot accept the item, or the destination already has an item of that name

Since:

1.548