Package com.cloudbees.hudson.plugins.folder

Class ChildNameGenerator<P extends AbstractFolder<I>,I extends TopLevelItem>

java.lang.Object
com.cloudbees.hudson.plugins.folder.ChildNameGenerator<P,I>
Type Parameters:
P - the type of AbstractFolder.
I - the type of TopLevelItem within the folder.
public abstract class ChildNameGenerator<P extends AbstractFolder<I>,I extends TopLevelItem> extends Object
Provides a way for a ComputedFolder to break the association between the directory names on disk that are used to store its items and the Item.getName() which is used to create the URL of the item.

NOTE: if you need to implement this functionality, you need to ensure that users cannot rename items within the ComputedFolder as renaming is not supported when using a ChildNameGenerator.

Challenges:

For a valid implementation, the ComputedFolder using this ChildNameGenerator will be attaching into the Item the actual name, typically via a JobProperty or Action (beware TransientActionFactory implementations may want to invoke PersistenceRoot.getRootDir() which will trigger a stack overflow though, so safer to stick with the JobProperty or equivalent). The itemNameFromItem(AbstractFolder, TopLevelItem) method's task is to find the stored name and return the name stored within or null if that information is missing (in which case itemNameFromLegacy(AbstractFolder, String) will be called to try and infer the name from the disk name that the Item is being loaded from. A similar relation exists for the dirNameFromItem(AbstractFolder, TopLevelItem) and dirNameFromLegacy(AbstractFolder, String) methods.
Since:
5.17

  • Constructor Details

    • ChildNameGenerator

      public ChildNameGenerator()

  • Method Details

    • itemNameFromItem

      @CheckForNull public abstract String itemNameFromItem(@NonNull P parent, @NonNull I item)
      Infers the Item.getName() from the Item instance itself. Challenges include:
      • There are some characters that it would be really bad to return in the item name, such as "/" / "?" / "#" / "[" / "]" / "\" as these could end up modifying the effective URL
      • There are names that it would be bad to return as the item name, such as "" / "." / ".." as these could end creating broken effective URLs
      Parameters:
      parent - the parent within which the item is being loaded.
      item - the partially loaded item (take care what methods you call, the item will not have a reference to its parent).
      Returns:
      the name of the item.

    • dirNameFromItem

      @CheckForNull public abstract String dirNameFromItem(@NonNull P parent, @NonNull I item)
      Infers the directory name in which the Item instance itself should be stored. Challenges include:
      • The only really filesystem safe characters are A-Za-z0-9_.-
      • Because of Windows and allowing for users to migrate their Jenkins from Unix to Windows and vice-versa, some names are reserved names under Windows: AUX, COM1, COM2, ..., COM9, CON, LPT1, LPT2, ..., LPT9, NUL, PRN plus all case variations of these names plus the variants where a single . is appended, you need to map those to something else
      • Don't make the filenames too long. Try to keep them under 32 characters. If you can go smaller, even better.
      • Get it right the first time
      Parameters:
      parent - the parent within which the item is being loaded.
      item - the partially loaded item (take care what methods you call, the item will not have a reference to its parent).
      Returns:
      the filesystem safe mangled equivalent name of the item.

    • itemNameFromLegacy

      @NonNull public abstract String itemNameFromLegacy(@NonNull P parent, @NonNull String legacyDirName)
      itemNameFromItem(AbstractFolder, TopLevelItem) could not help, we are loading the item for the first time since the ChildNameGenerator was enabled for the parent folder type, this method's mission is to pretend the legacyDirName is the "mostly correct" name and turn this into the actual name. Challenges include:
      • Previously the name may have been over-encoded with Util.rawEncode(String) so you may need to decode it first
      • There are some characters that it would be really bad to return in the item name, such as "/" / "?" / "#" / "[" / "]" / "\" as these could end up modifying the effective URL
      • There are names that it would be bad to return as the item name, such as "" / "." / ".." as these could end creating broken effective URLs
      Parameters:
      parent - the parent within which the item is being loaded.
      legacyDirName - the directory name that we are loading an item from.
      Returns:
      the name of the item.

    • dirNameFromLegacy

      @NonNull public abstract String dirNameFromLegacy(@NonNull P parent, @NonNull String legacyDirName)
      dirNameFromItem(AbstractFolder, TopLevelItem) could not help, we are loading the item for the first time since the ChildNameGenerator was enabled for the parent folder type, this method's mission is to pretend the legacyDirName is the "mostly correct" name and turn this into the filesystem safe mangled equivalent name to use going forward. Challenges include:
      • The only really filesystem safe characters are A-Za-z0-9_.-
      • Because of Windows and allowing for users to migrate their Jenkins from Unix to Windows and vice-versa, some names are reserved names under Windows: AUX, COM1, COM2, ..., COM9, CON, LPT1, LPT2, ..., LPT9, NUL, PRN plus all case variations of these names plus the variants where a single . is appended, you need to map those to something else
      • Don't make the filenames too long. Try to keep them under 32 characters. If you can go smaller, even better.
      • Get it right the first time
      Parameters:
      parent - the parent within which the item is being loaded.
      legacyDirName - the directory name that we are loading an item from.
      Returns:
      the filesystem safe mangled equivalent name of the item.