Items (Jenkins core 2.187 API)

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()

Constructors
Constructor and Description
`Items()`

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static DescriptorExtensionList<TopLevelItem,TopLevelItemDescriptor>`	`all()` Returns all the registered `TopLevelItemDescriptor`s.
`static List<TopLevelItemDescriptor>`	`all(org.acegisecurity.Authentication a, ItemGroup c)` Returns all the registered `TopLevelItemDescriptor`s that the specified security principal is allowed to create within the specified item group.
`static List<TopLevelItemDescriptor>`	`all(ItemGroup c)` Returns all the registered `TopLevelItemDescriptor`s 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 `Item`s 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(ItemGroup root, Class<T> type)` Gets a read-only view of all the `Item`s recursively 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 `Item`s recursively in the `ItemGroup` tree and filter them by the given type.
`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
```
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.
    
    Since:
    
    1.512
  - 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(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
  - 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

Class Items

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LIST

BY_NAME

BY_FULL_NAME

XSTREAM

XSTREAM2

Constructor Detail

Items

Method Detail

whileUpdatingByXml

currentlyUpdatingByXml

all

all

all

getDescriptor

toNameList

fromNameList

fromNameList

getCanonicalName

computeRelativeNamesAfterRenaming

load

getConfigFile

getConfigFile

getAllItems

allItems

allItems

findNearest

move