Package hudson.model

Class Items

  • public class Items
extends Object
    Convenience methods related to Item.
    Author:
    Kohsuke Kawaguchi

    • Constructor Detail

      • Items

        public Items()

    • Method Detail

      • 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

      • toNameList

        public static String toNameList​(Collection<? extends Item> items)
        Converts a list of items into a comma-separated list of full names.

      • 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.getAuthentication2() 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.getAuthentication2() 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

      • allItems2

        public static <T extends Item> Iterable<T> allItems2​(org.springframework.security.core.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.266

      • allItems2

        public static <T extends Item> Iterable<T> allItems2​(org.springframework.security.core.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.266

      • 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