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:

• See the notes on itemNameFromItem(AbstractFolder, TopLevelItem) and dirNameFromItem(AbstractFolder, TopLevelItem) regarding the constraints on how to name things
• There are some items which need the PersistenceRoot.getRootDir() during construction (those are bold evil item types that leak side-effects, you should fix them if you find them). While you wait for them to be fixed you will need to work-around the issue by ensuring that you call beforeCreateItem(AbstractFolder, String, String) passing the Item.getName() you want the item to have and the ideal unmangled name before you call new ChildItemType(parent,name) and then call afterItemCreated(Trace) when the constructor has returned. Then insure that your itemNameFromItem(AbstractFolder, TopLevelItem) and dirNameFromItem(AbstractFolder, TopLevelItem) fall back to idealNameFromItem(AbstractFolder, TopLevelItem) when the magic property they are looking for is missing.

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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	ChildNameGenerator.Trace	Traces the creation of a new Item in a folder.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CHILD_NAME_FILE	The name of the file that contains the actual name of the child item.

Constructor Summary

Constructors

Constructor	Description
ChildNameGenerator()

Method Summary

Modifier and Type	Method	Description
static ChildNameGenerator.Trace	beforeCreateItem(AbstractFolder<?> project, String itemName, String idealName)	Work-around helper method to "fix" Item constructors that have on-disk side-effects and therefore need PersistenceRoot.getRootDir() to work during the constructor.
abstract String	dirNameFromItem(P parent, I item)	Infers the directory name in which the Item instance itself should be stored.
abstract String	dirNameFromLegacy(P parent, 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.
protected final String	idealNameFromItem(P parent, 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)
abstract String	itemNameFromItem(P parent, I item)	Infers the Item.getName() from the Item instance itself.
abstract String	itemNameFromLegacy(P parent, 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.
final String	readItemName(File directory)	Reads an item name from the given directory.
abstract void	recordLegacyName(P parent, I item, String legacyDirName)	Deprecated. removed without replacement
final String	writeItemName(P parent, I item, File itemDirectory, String childName)	Writes the item name to the given directory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

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 Details

ChildNameGenerator

public ChildNameGenerator()

Method Details

beforeCreateItem

@NonNull
public static ChildNameGenerator.Trace beforeCreateItem(@NonNull
 AbstractFolder<?> project,
 @NonNull
 String itemName,
 @NonNull
 String idealName)

Work-around helper method to "fix" Item constructors that have on-disk side-effects and therefore need PersistenceRoot.getRootDir() to work during the constructor.

Parameters:

project - the AbstractFolder.

itemName - the name that will be returned by Item.getName() when the item is constructed. This is the second parameter of AbstractItem(ItemGroup, String). This one would be the one with URL path segment escaping.

idealName - the original name before whatever URL path segment escaping you applied

Returns:

the ChildNameGenerator.Trace to keep track of when we can remove the memory of the creation process. Please ChildNameGenerator.Trace.close() the trace after the item is created.

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

Deprecated.

removed without replacement

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.

readItemName

@NonNull
public final String readItemName(@NonNull
 File directory)

Reads an item name from the given directory.

Parameters:

directory - the directory containing the item.

Returns:

The item name obtained from the directory, or the directory name if the name file is missing or empty.

writeItemName

@NonNull
public final String writeItemName(@NonNull
 P parent,
 @NonNull
 I item,
 @NonNull
 File itemDirectory,
 @NonNull
 String childName)

Writes the item name to the given directory.

Parameters:

parent - The parent folder of the item.

item - The item we want to write the name for.

itemDirectory - The directory where the item is stored.

childName - The desired name for the item.

Returns:

The name that was written to the directory, and whether the item needs to be saved.