Package hudson.model

Class Items

java.lang.Object
hudson.model.Items
public class Items extends Object
Convenience methods related to Item.
Author:
Kohsuke Kawaguchi

  • Field Details

  • Constructor Details

    • Items

      public Items()

  • Method Details

    • runWhileUpdatingByXml

      public static <T extends Throwable> void runWhileUpdatingByXml(ThrowingRunnable<T> runnable) throws T
      Runs a block while making currentlyUpdatingByXml() be temporarily true. Use this when you are creating or changing an item.
      Type Parameters:
      T - an error type (may be Error)
      Parameters:
      runnable - a block, typically running load(hudson.model.ItemGroup, java.io.File) or Item.onLoad(hudson.model.ItemGroup<? extends hudson.model.Item>, java.lang.String)
      Throws:
      T - anything runnable throws
      Since:
      TODO

    • callWhileUpdatingByXml

      public static <V, T extends Throwable> V callWhileUpdatingByXml(ThrowingCallable<V,T> callable) throws T
      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
      Since:
      TODO

    • whileUpdatingByXml

      public static <V, T extends Throwable> V whileUpdatingByXml(hudson.remoting.Callable<V,T> callable) throws T
      Prefer runWhileUpdatingByXml(jenkins.util.ThrowingRunnable<T>) or callWhileUpdatingByXml(jenkins.util.ThrowingCallable<V, T>).
      Throws:
      T
      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 runWhileUpdatingByXml(jenkins.util.ThrowingRunnable<T>) or callWhileUpdatingByXml(jenkins.util.ThrowingCallable<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

    • all2

      public static List<TopLevelItemDescriptor> all2(org.springframework.security.core.Authentication a, ItemGroup c)
      Returns all the registered TopLevelItemDescriptors that the specified security principal is allowed to create within the specified item group.
      Since:
      2.266

    • all

      @Deprecated public static List<TopLevelItemDescriptor> all(Authentication a, ItemGroup c)
      Deprecated.
      use all2(Authentication, ItemGroup)
      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.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

    • allItems

      @Deprecated public static <T extends Item> Iterable<T> allItems(Authentication authentication, ItemGroup root, Class<T> type)
      Deprecated.
      use allItems2(Authentication, ItemGroup, Class)
      Since:
      2.37

    • 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

    • allItems

      @Deprecated public static <T extends Item> Iterable<T> allItems(Authentication authentication, ItemGroup root, Class<T> type, Predicate<T> pred)
      Deprecated.
      use allItems2(Authentication, ItemGroup, Class, Predicate)
      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