Folders, especially computed folders, may have requirements for using a different on-disk file name for child
items than the url-segment name. Typically this is to work around filesystem naming rules.
Regular folders typically would leave the naming of child items to
ProjectNamingStrategy and thereby
prevent users from creating child items with names that do not comply with the
ProjectNamingStrategy.
However,
ComputedFolder instances may not have that luxury. The children of a
ComputedFolder may have names that come from an external system and the matching item must be created,
always. The obvious solution is that the
ComputedFolder should mangle the supplied
Item#getName()but the side-effect is that the URLs of the child items will now be mangled. Additionally the filename
requirements can be rather onerous. Here is the most portable list of filename specification:
- Assume case insensitive
- Assume no filename can be longer than 32 characters
- Assume that only the characters
A-Za-z0-9_.- are available
- Assume that there are some special reserved names such as
. and
..
- Assume that there are some problematic names to avoid such as
AUX,
CON,
NUL, etc.
See
Microsoft's page on "Naming Files, Paths, and Namespaces"
(What's that you say, "Oh but we only run on Linux", perhaps but users may want to migrate from one OS
to an other by moving their
JENKINS_HOME (or even parts of it) so if you are
mangling names, be sure to ensure that the mangled name is the same on all OSes
- NFC vs. NFD may be a concern as different filesystems
apply different rules and normalization to the filenames. This is primarily a concern when migrating from
before having a
ChildNameGenerator to having a
ChildNameGenerator as the migration will
require inference of the un-mangled name from the filesystem, which may or may not match the un-mangled
name from the source of the computation. Now POSIX does not specify how the filesystem is supposed to handle
encoding of filenames and there can be strange behaviours, e.g.
File#listFiles() is rumoured to always return
NFC on OS-X
The
ChildNameGenerator at least allows an
AbstractFolder to apply an on-disk naming strategy
that differs from the names used for the URLs.
If you implement a
ChildNameGenerator it is strongly recommended to return a singleton for performance
reasons.