Package hudson

Class Util


  • public class Util
    extends Object
    Various utility methods that don't have more proper home.
    Author:
    Kohsuke Kawaguchi
    • Field Detail

      • XS_DATETIME_FORMATTER

        public static final org.apache.commons.lang.time.FastDateFormat XS_DATETIME_FORMATTER
      • RFC822_DATETIME_FORMATTER

        public static final org.apache.commons.lang.time.FastDateFormat RFC822_DATETIME_FORMATTER
      • NO_SYMLINK

        public static boolean NO_SYMLINK
        On Unix environment that cannot run "ln", set this to true.
      • SYMLINK_ESCAPEHATCH

        public static boolean SYMLINK_ESCAPEHATCH
    • Constructor Detail

      • Util

        public Util()
    • Method Detail

      • filter

        @NonNull
        public static <T> List<T> filter​(@NonNull
                                         Iterable<?> base,
                                         @NonNull
                                         Class<T> type)
        Creates a filtered sublist.
        Since:
        1.176
      • filter

        @NonNull
        public static <T> List<T> filter​(@NonNull
                                         List<?> base,
                                         @NonNull
                                         Class<T> type)
        Creates a filtered sublist.
      • replaceMacro

        @Nullable
        public static String replaceMacro​(@CheckForNull
                                          String s,
                                          @NonNull
                                          Map<String,​String> properties)
        Replaces the occurrence of '$key' by properties.get('key').

        Unlike shell, undefined variables are left as-is (this behavior is the same as Ant.)

      • replaceMacro

        @Nullable
        public static String replaceMacro​(@CheckForNull
                                          String s,
                                          @NonNull
                                          VariableResolver<String> resolver)
        Replaces the occurrence of '$key' by resolver.get('key').

        Unlike shell, undefined variables are left as-is (this behavior is the same as Ant.)

      • loadFile

        @NonNull
        public static String loadFile​(@NonNull
                                      File logfile,
                                      @NonNull
                                      Charset charset)
                               throws IOException
        Reads the entire contents of the text file at logfile into a string using charset for decoding. If no such file exists, an empty string is returned.
        Parameters:
        logfile - The text file to read in its entirety.
        charset - The charset to use for decoding the bytes in logfile.
        Returns:
        The entire text content of logfile.
        Throws:
        IOException - If an error occurs while reading the file.
      • deleteContentsRecursive

        public static void deleteContentsRecursive​(@NonNull
                                                   File file)
                                            throws IOException
        Deletes the contents of the given directory (but not the directory itself) recursively. It does not take no for an answer - if necessary, it will have multiple attempts at deleting things.
        Throws:
        IOException - if the operation fails.
      • deleteContentsRecursive

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
        public static void deleteContentsRecursive​(@NonNull
                                                   Path path,
                                                   @NonNull
                                                   PathRemover.PathChecker pathChecker)
                                            throws IOException
        Deletes the given directory contents (but not the directory itself) recursively using a PathChecker.
        Parameters:
        path - a directory to delete
        pathChecker - a security check to validate a path before deleting
        Throws:
        IOException - if the operation fails
      • deleteFile

        public static void deleteFile​(@NonNull
                                      File f)
                               throws IOException
        Deletes this file (and does not take no for an answer). If necessary, it will have multiple attempts at deleting things.
        Parameters:
        f - a file to delete
        Throws:
        IOException - if it exists but could not be successfully deleted
      • deleteRecursive

        public static void deleteRecursive​(@NonNull
                                           File dir)
                                    throws IOException
        Deletes the given directory (including its contents) recursively. It does not take no for an answer - if necessary, it will have multiple attempts at deleting things.
        Throws:
        IOException - if the operation fails.
      • deleteRecursive

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
        public static void deleteRecursive​(@NonNull
                                           Path dir,
                                           @NonNull
                                           PathRemover.PathChecker pathChecker)
                                    throws IOException
        Deletes the given directory and contents recursively using a filter.
        Parameters:
        dir - a directory to delete
        pathChecker - a security check to validate a path before deleting
        Throws:
        IOException - if the operation fails
      • isSymlink

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
        public static boolean isSymlink​(@NonNull
                                        Path path)
      • isRelativePath

        public static boolean isRelativePath​(String path)
        A mostly accurate check of whether a path is a relative path or not. This is designed to take a path against an unknown operating system so may give invalid results.
        Parameters:
        path - the path.
        Returns:
        true if the path looks relative.
        Since:
        1.606
      • isDescendant

        public static boolean isDescendant​(File forParent,
                                           File potentialChild)
                                    throws IOException
        A check if a file path is a descendant of a parent path
        Parameters:
        forParent - the parent the child should be a descendant of
        potentialChild - the path to check
        Returns:
        true if so
        Throws:
        IOException - for invalid paths
        Since:
        2.80
        See Also:
        InvalidPathException
      • displayIOException

        public static void displayIOException​(@NonNull
                                              IOException e,
                                              @NonNull
                                              TaskListener listener)
        On Windows, error messages for IOException aren't very helpful. This method generates additional user-friendly error message to the listener
      • getWin32ErrorMessage

        @CheckForNull
        public static String getWin32ErrorMessage​(@NonNull
                                                  IOException e)
      • getWin32ErrorMessage

        @CheckForNull
        public static String getWin32ErrorMessage​(Throwable e)
        Extracts the Win32 error message from Throwable if possible.
        Returns:
        null if there seems to be no error code or if the platform is not Win32.
      • getWin32ErrorMessage

        @CheckForNull
        public static String getWin32ErrorMessage​(int n)
        Gets a human readable message for the given Win32 error code.
        Returns:
        null if no such message is available.
      • getHostName

        @NonNull
        public static String getHostName()
        Guesses the current host name.
      • copyStreamAndClose

        @Deprecated
        public static void copyStreamAndClose​(@NonNull
                                              Reader in,
                                              @NonNull
                                              Writer out)
                                       throws IOException
        Deprecated.
        Use IOUtils.copy(Reader, Writer) in a try-with-resources block
        Throws:
        IOException
      • tokenize

        @NonNull
        public static String[] tokenize​(@NonNull
                                        String s,
                                        @CheckForNull
                                        String delimiter)
        Tokenizes the text separated by delimiters.

        In 1.210, this method was changed to handle quotes like Unix shell does. Before that, this method just used StringTokenizer.

        Since:
        1.145
        See Also:
        QuotedStringTokenizer
      • tokenize

        @NonNull
        public static String[] tokenize​(@NonNull
                                        String s)
      • mapToEnv

        @NonNull
        public static String[] mapToEnv​(@NonNull
                                        Map<String,​String> m)
        Converts the map format of the environment variables to the K=V format in the array.
      • min

        public static int min​(int x,
                              @NonNull
                              int... values)
      • nullify

        @CheckForNull
        public static String nullify​(@CheckForNull
                                     String v)
      • removeTrailingSlash

        @NonNull
        public static String removeTrailingSlash​(@NonNull
                                                 String s)
      • ensureEndsWith

        @Nullable
        public static String ensureEndsWith​(@CheckForNull
                                            String subject,
                                            @CheckForNull
                                            String suffix)
        Ensure string ends with suffix
        Parameters:
        subject - Examined string
        suffix - Desired suffix
        Returns:
        Original subject in case it already ends with suffix, null in case subject was null and subject + suffix otherwise.
        Since:
        1.505
      • getDigestOf

        @NonNull
        public static String getDigestOf​(@NonNull
                                         InputStream source)
                                  throws IOException
        Computes MD5 digest of the given input stream. This method should only be used for non-security applications where the MD5 weakness is not a problem.
        Parameters:
        source - The stream will be closed by this method at the end of this method.
        Returns:
        32-char wide string
        Throws:
        IOException
        See Also:
        DigestUtils.md5Hex(InputStream)
      • getDigestOf

        @NonNull
        public static String getDigestOf​(@NonNull
                                         String text)
      • getDigestOf

        @NonNull
        public static String getDigestOf​(@NonNull
                                         File file)
                                  throws IOException
        Computes the MD5 digest of a file.
        Parameters:
        file - a file
        Returns:
        a 32-character string
        Throws:
        IOException - in case reading fails
        Since:
        1.525
      • toAes128Key

        @NonNull
        public static SecretKey toAes128Key​(@NonNull
                                            String s)
        Converts a string into 128-bit AES key.
        Since:
        1.308
      • toHexString

        @NonNull
        public static String toHexString​(@NonNull
                                         byte[] data,
                                         int start,
                                         int len)
      • toHexString

        @NonNull
        public static String toHexString​(@NonNull
                                         byte[] bytes)
      • fromHexString

        @NonNull
        public static byte[] fromHexString​(@NonNull
                                           String data)
      • getTimeSpanString

        @NonNull
        public static String getTimeSpanString​(long duration)
        Returns a human readable text of the time duration, for example "3 minutes 40 seconds". This version should be used for representing a duration of some activity (like build)
        Parameters:
        duration - number of milliseconds.
      • getPastTimeString

        @Deprecated
        @NonNull
        public static String getPastTimeString​(long duration)
        Deprecated.
        Actually identical to getTimeSpanString(long), does not add ago.
        Get a human readable string representing strings like "xxx days ago", which should be used to point to the occurrence of an event in the past.
      • combine

        @NonNull
        @Deprecated
        public static String combine​(long n,
                                     @NonNull
                                     String suffix)
        Deprecated.
        Use individual localization methods instead. See Messages.Util_year(Object) for an example. Deprecated since 2009-06-24, remove method after 2009-12-24.
        Combines number and unit, with a plural suffix if needed.
      • createSubList

        @NonNull
        public static <T> List<T> createSubList​(@NonNull
                                                Collection<?> source,
                                                @NonNull
                                                Class<T> type)
        Create a sub-list by only picking up instances of the specified type.
      • encode

        @NonNull
        public static String encode​(@NonNull
                                    String s)
        Escapes non-ASCII characters in URL.

        Note that this methods only escapes non-ASCII but leaves other URL-unsafe characters, such as '#'. rawEncode(String) should generally be used instead, though be careful to pass only a single path component to that method (it will encode /, but this method does not).

      • rawEncode

        @NonNull
        public static String rawEncode​(@NonNull
                                       String s)
        Encode a single path component for use in an HTTP URL. Escapes all non-ASCII, general unsafe (space and "#%<>[\]^`{|}~) and HTTP special characters (/;:?) as specified in RFC1738. (so alphanumeric and !@$&*()-_=+',. are not encoded) Note that slash (/) is encoded, so the given string should be a single path component used in constructing a URL. Method name inspired by PHP's rawurlencode.
      • fullEncode

        @NonNull
        public static String fullEncode​(@NonNull
                                        String s)
        Encode a single path component for use in an HTTP URL. Escapes all special characters including those outside of the characters specified in RFC1738. All characters outside numbers and letters without diacritic are encoded. Note that slash (/) is encoded, so the given string should be a single path component used in constructing a URL.
        Since:
        2.308
      • singleQuote

        public static String singleQuote​(String s)
        Surrounds by a single-quote.
      • escape

        @Nullable
        public static String escape​(@CheckForNull
                                    String text)
        Escapes HTML unsafe characters like <, & to the respective character entities.
      • xmlEscape

        @NonNull
        public static String xmlEscape​(@NonNull
                                       String text)
      • touch

        public static void touch​(@NonNull
                                 File file)
                          throws IOException
        Creates an empty file if nonexistent or truncates the existing file. Note: The behavior of this method in the case where the file already exists is unlike the POSIX touch utility which merely updates the file's access and/or modification time.
        Throws:
        IOException
      • copyFile

        @Deprecated
        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
        @RestrictedSince("2.335")
        public static void copyFile​(@NonNull
                                    File src,
                                    @NonNull
                                    File dst)
                             throws org.apache.tools.ant.BuildException
        Deprecated.
        since 2.335; use Files.copy(Path, Path, CopyOption...) directly
        Copies a single file by using Ant.
        Throws:
        org.apache.tools.ant.BuildException
      • fixNull

        @NonNull
        public static String fixNull​(@CheckForNull
                                     String s)
        Convert null to "".
      • fixNull

        @NonNull
        public static <T> T fixNull​(@CheckForNull
                                    T s,
                                    @NonNull
                                    T defaultValue)
        Convert null to a default value.
        Parameters:
        defaultValue - Default value. It may be immutable or not, depending on the implementation.
        Since:
        2.144
      • fixEmpty

        @CheckForNull
        public static String fixEmpty​(@CheckForNull
                                      String s)
        Convert empty string to null.
      • fixEmptyAndTrim

        @CheckForNull
        public static String fixEmptyAndTrim​(@CheckForNull
                                             String s)
        Convert empty string to null, and trim whitespace.
        Since:
        1.154
      • fixNull

        @NonNull
        public static <T> List<T> fixNull​(@CheckForNull
                                          List<T> l)
        Type Parameters:
        T - Type of the list.
        Parameters:
        l - list to check.
        Returns:
        l if l is not null. An empty immutable list if l is null.
      • fixNull

        @NonNull
        public static <T> Set<T> fixNull​(@CheckForNull
                                         Set<T> l)
        Type Parameters:
        T - Type of the set.
        Parameters:
        l - set to check.
        Returns:
        l if l is not null. An empty immutable set if l is null.
      • fixNull

        @NonNull
        public static <T> Collection<T> fixNull​(@CheckForNull
                                                Collection<T> l)
        Type Parameters:
        T - Type of the collection.
        Parameters:
        l - collection to check.
        Returns:
        l if l is not null. An empty immutable set if l is null.
      • fixNull

        @NonNull
        public static <T> Iterable<T> fixNull​(@CheckForNull
                                              Iterable<T> l)
        Type Parameters:
        T - Type of the iterable.
        Parameters:
        l - iterable to check.
        Returns:
        l if l is not null. An empty immutable set if l is null.
      • getFileName

        @NonNull
        public static String getFileName​(@NonNull
                                         String filePath)
        Cuts all the leading path portion and get just the file name.
      • join

        @NonNull
        public static <T> List<T> join​(@NonNull
                                       Collection<? extends T>... items)
        Combines all the given collections into a single list.
      • createFileSet

        @NonNull
        public static org.apache.tools.ant.types.FileSet createFileSet​(@NonNull
                                                                       File baseDir,
                                                                       @NonNull
                                                                       String includes,
                                                                       @CheckForNull
                                                                       String excludes)
        Creates Ant FileSet with the base dir and include pattern.

        The difference with this and using AbstractFileSet.setIncludes(String) is that this method doesn't treat whitespace as a pattern separator, which makes it impossible to use space in the file path.

        Parameters:
        includes - String like "foo/bar/*.xml" Multiple patterns can be separated by ',', and whitespace can surround ',' (so that you can write "abc, def" and "abc,def" to mean the same thing.
        excludes - Exclusion pattern. Follows the same format as the 'includes' parameter. Can be null.
        Since:
        1.172
      • createFileSet

        @NonNull
        public static org.apache.tools.ant.types.FileSet createFileSet​(@NonNull
                                                                       File baseDir,
                                                                       @NonNull
                                                                       String includes)
      • createSymlink

        public static void createSymlink​(@NonNull
                                         File baseDir,
                                         @NonNull
                                         String targetPath,
                                         @NonNull
                                         String symlinkPath,
                                         @NonNull
                                         TaskListener listener)
                                  throws InterruptedException
        Creates a symlink to targetPath at baseDir+symlinkPath.

        If there's a prior symlink at baseDir+symlinkPath, it will be overwritten.

        Parameters:
        baseDir - Base directory to resolve the 'symlinkPath' parameter.
        targetPath - The file that the symlink should point to. Usually relative to the directory of the symlink but may instead be an absolute path.
        symlinkPath - Where to create a symlink in (relative to baseDir)
        Throws:
        InterruptedException
      • resolveSymlink

        @CheckForNull
        public static String resolveSymlink​(@NonNull
                                            File link)
                                     throws IOException
        Resolves symlink, if the given file is a symlink. Otherwise return null.

        If the resolution fails, report an error.

        Returns:
        null if the given file is not a symlink. If the symlink is absolute, the returned string is an absolute path. If the symlink is relative, the returned string is that relative representation. The relative path is meant to be resolved from the location of the symlink.
        Throws:
        IOException
      • encodeRFC2396

        @Deprecated
        public static String encodeRFC2396​(String url)
        Deprecated.
        since 2008-05-13. This method is broken (see JENKINS-1666). It should probably be removed but I'm not sure if it is considered part of the public API that needs to be maintained for backwards compatibility. Use encode(String) instead.
        Encodes the URL by RFC 2396. I thought there's another spec that refers to UTF-8 as the encoding, but don't remember it right now.
        Since:
        1.204
      • wrapToErrorSpan

        @NonNull
        public static String wrapToErrorSpan​(@NonNull
                                             String s)
        Wraps with the error icon and the CSS class to render error message.
        Since:
        1.173
      • tryParseNumber

        @CheckForNull
        public static Number tryParseNumber​(@CheckForNull
                                            String numberStr,
                                            @CheckForNull
                                            Number defaultNumber)
        Returns the parsed string if parsed successful; otherwise returns the default number. If the string is null, empty or a ParseException is thrown then the defaultNumber is returned.
        Parameters:
        numberStr - string to parse
        defaultNumber - number to return if the string can not be parsed
        Returns:
        returns the parsed string; otherwise the default number
      • isOverridden

        public static boolean isOverridden​(@NonNull
                                           Class<?> base,
                                           @NonNull
                                           Class<?> derived,
                                           @NonNull
                                           String methodName,
                                           @NonNull
                                           Class<?>... types)
        Checks whether the method defined on the base type with the given arguments is overridden in the given derived type.
        Parameters:
        base - The base type.
        derived - The derived type.
        methodName - The name of the method.
        types - The types of the arguments for the method.
        Returns:
        true when derived provides the specified method other than as inherited from base.
        Throws:
        IllegalArgumentException - When derived does not derive from base, or when base does not contain the specified method.
      • ifOverridden

        public static <T> T ifOverridden​(Supplier<T> supplier,
                                         @NonNull
                                         Class<?> base,
                                         @NonNull
                                         Class<?> derived,
                                         @NonNull
                                         String methodName,
                                         @NonNull
                                         Class<?>... types)
        Calls the given supplier if the method defined on the base type with the given arguments is overridden in the given derived type.
        Parameters:
        supplier - The supplier to call if the method is indeed overridden.
        base - The base type.
        derived - The derived type.
        methodName - The name of the method.
        types - The types of the arguments for the method.
        Returns:
        true when derived provides the specified method other than as inherited from base.
        Throws:
        IllegalArgumentException - When derived does not derive from base, or when base does not contain the specified method.
        AbstractMethodError - If the derived class doesn't override the given method.
        Since:
        2.259
      • changeExtension

        @NonNull
        public static File changeExtension​(@NonNull
                                           File dst,
                                           @NonNull
                                           String ext)
        Returns a file name by changing its extension.
        Parameters:
        ext - For example, ".zip"
      • intern

        @Nullable
        public static String intern​(@CheckForNull
                                    String s)
        Null-safe String intern method.
        Returns:
        A canonical representation for the string object. Null for null input strings
      • isAbsoluteUri

        @Deprecated
        @RestrictedSince("1.651.2 / 2.3")
        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
        public static boolean isAbsoluteUri​(@NonNull
                                            String uri)
        Deprecated.
        Use isSafeToRedirectTo(java.lang.String) instead if your goal is to prevent open redirects
        Return true if the systemId denotes an absolute URI . The same algorithm can be seen in URI, but implementing this by ourselves allow it to be more lenient about escaping of URI.
      • isSafeToRedirectTo

        public static boolean isSafeToRedirectTo​(@NonNull
                                                 String uri)
        Return true iff the parameter does not denote an absolute URI and not a scheme-relative URI.
        Since:
        2.3 / 1.651.2
      • closeAndLogFailures

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
        public static void closeAndLogFailures​(@CheckForNull
                                               Closeable toClose,
                                               @NonNull
                                               Logger logger,
                                               @NonNull
                                               String closeableName,
                                               @NonNull
                                               String closeableOwner)
        Closes the item and logs error to the log in the case of error. Logging will be performed on the WARNING level.
        Parameters:
        toClose - Item to close. Nothing will happen if it is null
        logger - Logger, which receives the error
        closeableName - Name of the closeable item
        closeableOwner - String representation of the closeable holder
        Since:
        2.19, but TODO update once un-restricted
      • permissionsToMode

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
        public static int permissionsToMode​(Set<PosixFilePermission> permissions)
      • daysBetween

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
        public static long daysBetween​(@NonNull
                                       Date a,
                                       @NonNull
                                       Date b)
        Compute the number of calendar days elapsed since the given date. As it's only the calendar days difference that matter, "11.00pm" to "2.00am the day after" returns 1, even if there are only 3 hours between. As well as "10am" to "2pm" both on the same day, returns 0.
      • daysElapsedSince

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
        public static long daysElapsedSince​(@NonNull
                                            Date date)
        Returns:
        positive number of days between the given date and now
        See Also:
        daysBetween(Date, Date)
      • getNearestAncestorOfTypeOrThrow

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
        @NonNull
        public static <T> T getNearestAncestorOfTypeOrThrow​(@NonNull
                                                            org.kohsuke.stapler.StaplerRequest request,
                                                            @NonNull
                                                            Class<T> clazz)
        Find the specific ancestor, or throw an exception. Useful for an ancestor we know is inside the URL to ease readability