Package com.cloudbees.hudson.plugins.folder

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

    • Field Detail

      • CHILD_NAME_FILE

        public static final String CHILD_NAME_FILE
        The name of the file that contains the actual name of the child item. This file is to allow a Jenkins Administrator to determine which child is which when dealing with a folder containing child names that have been mangled.

        If there is nothing else to go on, this file will be used in preference to the child directory name, but as it is too easy for users to mistakenly think changing the contents of the file will rename the child (which could cause data loss for the computed folder's child) it is better for implementations to store the definitive ideal name in a JobProperty, Action or equivalent that is attached directly to the Item.

        See Also:
        Constant Field Values

    • Constructor Detail

      • ChildNameGenerator

        public ChildNameGenerator()

    • Method Detail

      • idealNameFromItem

        @CheckForNull
protected final String idealNameFromItem​(@NonNull
                                         P parent,
                                         @NonNull
                                         I item)
        Looks up the Item to see if we stored the ideal name before invoking the constructor that is having on-disk side-effects before the object has escaped beforeCreateItem(AbstractFolder, String, String)
        Parameters:
        parent - the parent within which the item is being created.
        item - the partially created item.
        Returns:
        the ideal name of the item.

      • 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.

      • recordLegacyName

        public abstract void recordLegacyName​(P parent,
                                      I item,
                                      String legacyDirName)
                               throws IOException
        Record the ideal name inferred in the item when it was missing and has been inferred from the legacy directory name.
        Parameters:
        parent - the parent.
        item - the item.
        legacyDirName - the name of the directory that the item was loaded from.
        Throws:
        IOException - if the ideal name could not be attached to the item.