/*-------------------------------------------------------------------------+
|                                                                          |
| Copyright 2005-2011 The ConQAT Project                                   |
|                                                                          |
| Licensed under the Apache License, Version 2.0 (the "License");          |
| you may not use this file except in compliance with the License.         |
| You may obtain a copy of the License at                                  |
|                                                                          |
|    http://www.apache.org/licenses/LICENSE-2.0                            |
|                                                                          |
| Unless required by applicable law or agreed to in writing, software      |
| distributed under the License is distributed on an "AS IS" BASIS,        |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and      |
| limitations under the License.                                           |
+-------------------------------------------------------------------------*/
package org.conqat.lib.commons.filesystem;

import java.io.BufferedInputStream;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.Closeable;
import java.io.EOFException;
import java.io.File;
import java.io.FileFilter;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.Reader;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.nio.ByteBuffer;
import java.nio.channels.FileChannel;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Enumeration;
import java.util.HashSet;
import java.util.IllegalFormatException;
import java.util.List;
import java.util.Properties;
import java.util.Set;
import java.util.jar.JarEntry;
import java.util.jar.JarFile;
import java.util.jar.JarOutputStream;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import java.util.zip.GZIPInputStream;
import java.util.zip.ZipEntry;
import java.util.zip.ZipInputStream;

import org.apache.commons.compress.archivers.zip.ZipArchiveEntry;
import org.conqat.lib.commons.assertion.CCSMAssert;
import org.conqat.lib.commons.collections.CaseInsensitiveStringSet;
import org.conqat.lib.commons.collections.CollectionUtils;
import org.conqat.lib.commons.logging.ILogger;
import org.conqat.lib.commons.resources.Resource;
import org.conqat.lib.commons.string.StringUtils;

/**
 * File system utilities.
 */
public class FileSystemUtils {

        /** Encoding for UTF-8. */
        public static final String UTF8_ENCODING = StandardCharsets.UTF_8.name();

        /** The path to the directory used by Java to store temporary files */
        public static final String TEMP_DIR_PATH = System.getProperty("java.io.tmpdir");

        /** Unix file path separator */
        public static final char UNIX_SEPARATOR = '/';

        /** Windows file path separator */
        public static final char WINDOWS_SEPARATOR = '\\';

        /**
         * String containing the unit letters for units in the metric system (K for
         * kilo, M for mega, ...). Ordered by their power value (the order is
         * important).
         */
        public static final String METRIC_SYSTEM_UNITS = "KMGTPEZY";

        /**
         * Pattern matching the start of the data-size unit in a data-size string (the
         * first non-space char not belonging to the numeric value).
         */
        private static final Pattern DATA_SIZE_UNIT_START_PATTERN = Pattern.compile("[^\\d\\s.,]");

        /**
         * The names of path segments that are reserved in certain operating systems and
         * hence may not be used.
         *
         * @see "https://answers.microsoft.com/en-us/windows/forum/windows_7-files/why-cant-i-create-a-folder-with-name/23c86662-4988-4c7d-9c2d-3e33d4413de3"
         */
        private static final Set<String> RESERVED_PATH_SEGMENT_NAMES = new CaseInsensitiveStringSet(
                        Arrays.asList("CON", "PRN", "AUX", "CLOCK$", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7",
                                        "COM8", "COM9", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9"));

        /**
         * Copy an input stream to an output stream. This does <em>not</em> close the
         * streams.
         *
         * @param input
         *            input stream
         * @param output
         *            output stream
         * @return number of bytes copied
         * @throws IOException
         *             if an IO exception occurs.
         */
        public static int copy(InputStream input, OutputStream output) throws IOException {
                byte[] buffer = new byte[1024];
                int size = 0;
                int len;
                while ((len = input.read(buffer)) > 0) {
                        output.write(buffer, 0, len);
                        size += len;
                }
                return size;
        }

        /** Copy a file. This creates all necessary directories. */
        @SuppressWarnings("resource")
        public static void copyFile(File sourceFile, File targetFile) throws IOException {

                if (sourceFile.getAbsoluteFile().equals(targetFile.getAbsoluteFile())) {
                        throw new IOException("Can not copy file onto itself: " + sourceFile);
                }

                ensureParentDirectoryExists(targetFile);

                FileChannel sourceChannel = null;
                FileChannel targetChannel = null;
                try {
                        sourceChannel = new FileInputStream(sourceFile).getChannel();
                        targetChannel = new FileOutputStream(targetFile).getChannel();
                        sourceChannel.transferTo(0, sourceChannel.size(), targetChannel);
                } finally {
                        close(sourceChannel);
                        close(targetChannel);
                }
        }

        /** Copy a file. This creates all necessary directories. */
        public static void copyFile(String sourceFilename, String targetFilename) throws IOException {
                copyFile(new File(sourceFilename), new File(targetFilename));
        }

        /**
         * Copy all files specified by a file filter from one directory to another. This
         * automatically creates all necessary directories.
         *
         * @param fileFilter
         *            filter to specify file types. If all files should be copied, use
         *            {@link FileOnlyFilter}.
         * @return number of files copied
         */
        public static int copyFiles(File sourceDirectory, File targetDirectory, FileFilter fileFilter) throws IOException {
                List<File> files = FileSystemUtils.listFilesRecursively(sourceDirectory, fileFilter);

                int fileCount = 0;
                for (File sourceFile : files) {
                        if (sourceFile.isFile()) {
                                String path = sourceFile.getAbsolutePath();
                                int index = sourceDirectory.getAbsolutePath().length();
                                String newPath = path.substring(index);
                                File targetFile = new File(targetDirectory, newPath);
                                copyFile(sourceFile, targetFile);
                                fileCount++;
                        }
                }
                return fileCount;
        }

        /**
         * Create jar file from all files in a directory.
         *
         * @param filter
         *            filter to specify file types. If all files should be copied, use
         *            {@link FileOnlyFilter}.
         * @return number of files added to the jar file
         */
        public static int createJARFile(File jarFile, File sourceDirectory, FileFilter filter) throws IOException {
                JarOutputStream out = null;
                int fileCount = 0;

                try {
                        out = new JarOutputStream(new FileOutputStream(jarFile));

                        for (File file : FileSystemUtils.listFilesRecursively(sourceDirectory, filter)) {
                                if (!file.isFile()) {
                                        continue;
                                }

                                FileInputStream in = null;
                                fileCount += 1;
                                try {
                                        // works for forward slashes only
                                        String entryName = normalizeSeparators(
                                                        file.getAbsolutePath().substring(sourceDirectory.getAbsolutePath().length() + 1));
                                        out.putNextEntry(new ZipEntry(entryName));

                                        in = new FileInputStream(file);
                                        copy(in, out);
                                        out.closeEntry();
                                } finally {
                                        close(in);
                                }
                        }
                } finally {
                        close(out);
                }

                return fileCount;
        }

        /**
         * Returns a string describing the relative path to the given directory. If
         * there is no relative path, as the directories do not share a common parent,
         * the absolute path is returned.
         *
         * @param path
         *            the path to convert to a relative path (must describe an existing
         *            directory)
         * @param relativeTo
         *            the anchor (must describe an existing directory)
         * @return a relative path
         * @throws IOException
         *             if creation of canonical pathes fails.
         */
        public static String createRelativePath(File path, File relativeTo) throws IOException {
                CCSMAssert.isNotNull(path, "Path must not be null!");
                CCSMAssert.isNotNull(relativeTo, "relativeTo must not be null!");

                if (!path.isDirectory() || !relativeTo.isDirectory()) {
                        throw new IllegalArgumentException("Both arguments must be existing directories!");
                }
                path = path.getCanonicalFile();
                relativeTo = relativeTo.getCanonicalFile();

                Set<File> parents = new HashSet<>();
                File f = path;
                while (f != null) {
                        parents.add(f);
                        f = f.getParentFile();
                }

                File root = relativeTo;
                while (root != null && !parents.contains(root)) {
                        root = root.getParentFile();
                }

                if (root == null) {
                        // no common root, so use full path
                        return path.getAbsolutePath();
                }

                String result = "";
                while (!path.equals(root)) {
                        result = path.getName() + "/" + result;
                        path = path.getParentFile();
                }
                while (!relativeTo.equals(root)) {
                        result = "../" + result;
                        relativeTo = relativeTo.getParentFile();
                }

                return result;
        }

        /**
         * Recursively delete directories and files. This method ignores the return
         * value of delete(), i.e. if anything fails, some files might still exist.
         */
        public static void deleteRecursively(File directory) {

                if (directory == null) {
                        throw new IllegalArgumentException("Directory may not be null.");
                }
                File[] filesInDirectory = directory.listFiles();
                if (filesInDirectory == null) {
                        throw new IllegalArgumentException(directory.getAbsolutePath() + " is not a valid directory.");
                }

                for (File entry : filesInDirectory) {
                        if (entry.isDirectory()) {
                                deleteRecursively(entry);
                        }
                        entry.delete();
                }
                directory.delete();
        }

        /**
         * Deletes the given file and throws an exception if this fails.
         *
         * @see File#delete()
         */
        public static void deleteFile(File file) throws IOException {
                if (file.exists() && !file.delete()) {
                        throw new IOException("Could not delete " + file);
                }
        }

        /**
         * Renames the given file and throws an exception if this fails.
         *
         * @see File#renameTo(File)
         */
        public static void renameFileTo(File file, File dest) throws IOException {
                if (!file.renameTo(dest)) {
                        throw new IOException("Could not rename " + file + " to " + dest);
                }
        }

        /**
         * Creates a directory and throws an exception if this fails.
         *
         * @see File#mkdir()
         */
        public static void mkdir(File dir) throws IOException {
                if (!dir.mkdir()) {
                        throw new IOException("Could not create directory " + dir);
                }
        }

        /**
         * Creates a directory and all required parent directories. Throws an exception
         * if this fails.
         *
         * @see File#mkdirs()
         */
        public static void mkdirs(File dir) throws IOException {
                if (dir.exists() && dir.isDirectory()) {
                        // mkdirs will return false if the directory already exists, but in
                        // that case we don't want to throw an exception
                        return;
                }
                if (!dir.mkdirs()) {
                        throw new IOException("Could not create directory " + dir);
                }
        }

        /**
         * Checks if a directory exists. If not it creates the directory and all
         * necessary parent directories.
         *
         * @throws IOException
         *             if directories couldn't be created.
         */
        public static void ensureDirectoryExists(File directory) throws IOException {
                if (!directory.exists() && !directory.mkdirs()) {
                        throw new IOException("Couldn't create directory: " + directory);
                }
        }

        /**
         * Checks if the parent directory of a file exists. If not it creates the
         * directory and all necessary parent directories.
         *
         * @throws IOException
         *             if directories couldn't be created.
         */
        public static void ensureParentDirectoryExists(File file) throws IOException {
                ensureDirectoryExists(file.getCanonicalFile().getParentFile());
        }

        /**
         * Returns a list of all files and directories contained in the given directory
         * and all subdirectories. The given directory itself is not included in the
         * result.
         * <p>
         * This method knows nothing about (symbolic and hard) links, so care should be
         * taken when traversing directories containing recursive links.
         *
         * @param directory
         *            the directory to start the search from.
         * @return the list of files found (the order is determined by the file system).
         */
        public static List<File> listFilesRecursively(File directory) {
                return listFilesRecursively(directory, null);
        }

        /**
         * Returns a list of all files and directories contained in the given directory
         * and all subdirectories matching the filter provided. The given directory
         * itself is not included in the result.
         * <p>
         * The file filter may or may not exclude directories.
         * <p>
         * This method knows nothing about (symbolic and hard) links, so care should be
         * taken when traversing directories containing recursive links.
         *
         * @param directory
         *            the directory to start the search from. If this is null or the
         *            directory does not exist, an empty list is returned.
         * @param filter
         *            the filter used to determine whether the result should be
         *            included. If the filter is null, all files and directories are
         *            included.
         * @return the list of files found (the order is determined by the file system).
         */
        public static List<File> listFilesRecursively(File directory, FileFilter filter) {
                if (directory == null || !directory.isDirectory()) {
                        return CollectionUtils.emptyList();
                }
                List<File> result = new ArrayList<>();
                listFilesRecursively(directory, result, filter);
                return result;
        }

        /**
         * @see #listFilesInSameLocationForURL(URL, boolean)
         */
        public static List<String> listFilesInSameLocationForURL(URL baseUrl) throws IOException {
                return listFilesInSameLocationForURL(baseUrl, false);
        }

        /**
         * Lists the names of all simple files (i.e. no directories) next to an URL. For
         * example for a file, this would return the names of all files in the same
         * directory (including the file itself). Currently, this supports both file and
         * jar URLs. The intended use-case is to list a set of files in a package via
         * the class loader.
         */
        public static List<String> listFilesInSameLocationForURL(URL baseUrl, boolean includeSubfolders)
                        throws IOException {

                String protocol = baseUrl.getProtocol();

                if ("file".equals(protocol)) {
                        return listFilesForFileURL(baseUrl, includeSubfolders);
                }

                if ("jar".equals(protocol)) {
                        return listFilesForJarURL(baseUrl, includeSubfolders);
                }

                throw new IOException("Unsupported protocol: " + protocol);
        }

        /**
         * Returns the parent path within the jar for a class file url. E.g. for the URL
         * "jar:file:/path/to/file.jar!/sub/folder/File.class" the method returns
         * "sub/folder/". If the url does already point to a directory it returns the
         * path of this directory.
         */
        private static String getJarUrlParentDirectoryPrefix(URL baseUrl) {
                // in JAR URLs we can rely on the separator being a slash
                String parentPath = StringUtils.getLastPart(baseUrl.getPath(), '!');
                parentPath = StringUtils.stripPrefix(parentPath, "/");
                if (parentPath.endsWith(".class")) {
                        parentPath = StringUtils.stripSuffix(parentPath, StringUtils.getLastPart(parentPath, UNIX_SEPARATOR));
                } else {
                        parentPath = StringUtils.ensureEndsWith(parentPath, String.valueOf(UNIX_SEPARATOR));
                }
                return parentPath;
        }

        /**
         * Lists the names of files for a JAR URL. If the recursive flag is set, all
         * files within the same jar directory hierarchy will be listed, otherwise only
         * the ones in the same directory.
         */
        private static List<String> listFilesForJarURL(URL baseUrl, boolean recursive) throws IOException {
                try (JarFile jarFile = new JarFile(FileSystemUtils.extractJarFileFromJarURL(baseUrl))) {
                        String parentPath = getJarUrlParentDirectoryPrefix(baseUrl);
                        return jarFile.stream().filter(entry -> shouldBeContainedInResult(entry, parentPath, recursive))
                                        .map(entry -> StringUtils.stripPrefix(entry.getName(), parentPath)).collect(Collectors.toList());
                }
        }

        /**
         * Returns whether the jar entry should be returned when searching for files
         * contained in the given path.
         */
        private static boolean shouldBeContainedInResult(JarEntry entry, String path, boolean recursive) {
                if (entry.isDirectory()) {
                        return false;
                }
                String simpleName = StringUtils.getLastPart(entry.getName(), UNIX_SEPARATOR);
                String entryPath = StringUtils.stripSuffix(entry.getName(), simpleName);

                return !recursive && entryPath.equals(path) || (recursive && entryPath.startsWith(path));
        }

        /**
         * Lists the names of files (not including directories) within the given file
         * URL. This will only include subfolder (recursively) if the includeSubfolders
         * flag is set.
         *
         * @return a list of relative, separator-normalized file paths without slash
         *         prefix, e.g. ['foo.java', 'subfolder/bar.java']
         */
        private static List<String> listFilesForFileURL(URL baseUrl, boolean includeSubfolders) throws IOException {
                try {
                        File directory = new File(baseUrl.toURI());
                        if (!directory.isDirectory()) {
                                directory = directory.getParentFile();
                        }
                        if (!directory.isDirectory()) {
                                throw new IOException("Parent directory does not exist or is not readable for " + baseUrl);
                        }

                        if (includeSubfolders) {
                                File finalDirectory = directory;
                                return CollectionUtils.filterAndMap(listFilesRecursively(directory), File::isFile, file -> {
                                        String relativeFilePath = StringUtils.stripPrefix(file.getAbsolutePath(),
                                                        finalDirectory.getAbsolutePath());
                                        relativeFilePath = FileSystemUtils.normalizeSeparators(relativeFilePath);
                                        return StringUtils.stripPrefix(relativeFilePath, String.valueOf(UNIX_SEPARATOR));
                                });
                        }

                        List<String> names = new ArrayList<>();
                        for (File file : directory.listFiles()) {
                                if (file.isFile()) {
                                        names.add(file.getName());
                                }
                        }
                        return names;
                } catch (URISyntaxException e) {
                        throw new IOException("Could not convert URL to valid file: " + baseUrl, e);
                }
        }

        /**
         * Extract all top-level classes in the given JAR and returns a list of their
         * fully qualified class names. Inner classes are ignored.
         */
        public static List<String> listTopLevelClassesInJarFile(File jarFile) throws IOException {
                List<String> result = new ArrayList<>();
                PathBasedContentProviderBase provider = PathBasedContentProviderBase.createProvider(jarFile);
                Collection<String> paths = provider.getPaths();
                for (String path : paths) {
                        if (path.endsWith(ClassPathUtils.CLASS_FILE_SUFFIX) && !path.contains("$")) {
                                String fqn = StringUtils.removeLastPart(path, '.');
                                fqn = fqn.replace(UNIX_SEPARATOR, '.');
                                result.add(fqn);
                        }
                }
                return result;
        }

        /**
         * Returns the extension of the file.
         *
         * @return File extension, i.e. "java" for "FileSystemUtils.java", or
         *         <code>null</code>, if the file has no extension (i.e. if a filename
         *         contains no '.'), returns the empty string if the '.' is the
         *         filename's last character.
         */
        public static String getFileExtension(File file) {
                return getFileExtension(file.getName());
        }

        /** Returns the extension of the file at the given path. */
        public static String getFileExtension(String path) {
                int posLastDot = path.lastIndexOf('.');
                if (posLastDot < 0) {
                        return null;
                }
                return path.substring(posLastDot + 1);
        }

        /**
         * Returns the name of the given file without extension. Example:
         * '/home/joe/data.dat' -> 'data'.
         */
        public static String getFilenameWithoutExtension(File file) {
                return getFilenameWithoutExtension(file.getName());
        }

        /**
         * Returns the name of the given file without extension. Example: 'data.dat' ->
         * 'data'.
         */
        public static String getFilenameWithoutExtension(String fileName) {
                return StringUtils.removeLastPart(fileName, '.');
        }

        /**
         * Returns the last path segment (i.e. file name or folder name) of a file path.
         */
        public static String getLastPathSegment(String filePath) {
                String[] split = getPathSegments(filePath);
                return split[split.length - 1];
        }

        /** Returns the segments of a path. */
        public static String[] getPathSegments(String filePath) {
                return FileSystemUtils.normalizeSeparators(filePath).split(String.valueOf(UNIX_SEPARATOR));
        }

        /**
         * Constructs a file from a base file by appending several path elements.
         * Insertion of separators is performed automatically as needed. This is similar
         * to the constructor {@link File#File(File, String)} but allows to define
         * multiple child levels.
         *
         * @param pathElements
         *            list of elements. If this is empty, the parent is returned.
         * @return the new file.
         */
        public static File newFile(File parentFile, String... pathElements) {
                if (pathElements.length == 0) {
                        return parentFile;
                }

                File child = new File(parentFile, pathElements[0]);

                String[] remainingElements = new String[pathElements.length - 1];
                System.arraycopy(pathElements, 1, remainingElements, 0, pathElements.length - 1);
                return newFile(child, remainingElements);
        }

        /**
         * Read file content into a string using the default encoding for the platform.
         * If the file starts with a UTF byte order mark (BOM), the encoding is ignored
         * and the correct encoding based on this BOM is used for reading the file.
         *
         * @see EByteOrderMark
         */
        public static String readFile(File file) throws IOException {
                return readFile(file, Charset.defaultCharset());
        }

        /**
         * Read file content into a string using UTF-8 encoding. If the file starts with
         * a UTF byte order mark (BOM), the encoding is ignored and the correct encoding
         * based on this BOM is used for reading the file.
         *
         * @see EByteOrderMark
         */
        public static String readFileUTF8(File file) throws IOException {
                return readFile(file, StandardCharsets.UTF_8);
        }

        /**
         * Read file content into a string using UTF-8 encoding and normalize the line
         * breaks. If the file starts with a UTF byte order mark (BOM), the encoding is
         * ignored and the correct encoding based on this BOM is used for reading the
         * file.
         *
         * @see EByteOrderMark
         * @see StringUtils#normalizeLineSeparatorsPlatformSpecific(String)
         */
        public static String readFileUTF8WithLineBreakNormalization(File file) throws IOException {
                return StringUtils.normalizeLineSeparatorsPlatformSpecific(readFile(file, StandardCharsets.UTF_8));
        }

        /**
         * Read file content into a string using the given encoding. If the file starts
         * with a UTF byte order mark (BOM), the encoding is ignored and the correct
         * encoding based on this BOM is used for reading the file.
         *
         * @see EByteOrderMark
         */
        public static String readFile(File file, Charset encoding) throws IOException {
                byte[] buffer = readFileBinary(file);
                return StringUtils.bytesToString(buffer, encoding);
        }

        /**
         * Read file content into a list of lines (strings) using the given encoding.
         * This uses automatic BOM handling, just as {@link #readFile(File)}.
         */
        public static List<String> readLines(File file, Charset encoding) throws IOException {
                return StringUtils.splitLinesAsList(readFile(file, encoding));
        }

        /**
         * Read file content into a list of lines (strings) using UTF-8 encoding. This
         * uses automatic BOM handling, just as {@link #readFile(File)}.
         */
        public static List<String> readLinesUTF8(String filePath) throws IOException {
                return readLinesUTF8(new File(filePath));
        }

        /**
         * Read file content into a list of lines (strings) using UTF-8 encoding. This
         * uses automatic BOM handling, just as {@link #readFile(File)}.
         */
        public static List<String> readLinesUTF8(File file) throws IOException {
                return readLines(file, StandardCharsets.UTF_8);
        }

        /** Read file content into a byte array. */
        public static byte[] readFileBinary(String filePath) throws IOException {
                return readFileBinary(new File(filePath));
        }

        /** Read file content into a byte array. */
        public static byte[] readFileBinary(File file) throws IOException {
                FileInputStream in = new FileInputStream(file);

                byte[] buffer = new byte[(int) file.length()];
                ByteBuffer byteBuffer = ByteBuffer.wrap(buffer);

                FileChannel channel = in.getChannel();
                try {
                        int readSum = 0;
                        while (readSum < buffer.length) {
                                int read = channel.read(byteBuffer);
                                if (read < 0) {
                                        throw new IOException("Reached EOF before entire file could be read!");
                                }
                                readSum += read;
                        }
                } finally {
                        close(channel);
                        close(in);
                }

                return buffer;
        }

        /** Extract a JAR file to a directory. */
        public static void unjar(File jarFile, File targetDirectory) throws IOException {
                unzip(jarFile, targetDirectory);
        }

        /**
         * Extract a ZIP file to a directory.
         */
        public static void unzip(File zipFile, File targetDirectory) throws IOException {
                unzip(zipFile, targetDirectory, null, null);
        }

        /**
         * Extract the entries of ZIP file to a directory.
         *
         * @param prefix
         *            Sets a prefix for the the entry names (paths) which should be
         *            extracted. Only entries which starts with the given prefix are
         *            extracted. If prefix is <code>null</code> or empty all entries are
         *            extracted. The prefix will be stripped form the extracted entries.
         * @param charset
         *            defines the {@link Charset} of the ZIP file. If <code>null</code>,
         *            the standard of {@link ZipFile} is used (which is UTF-8).
         * @return list of the extracted paths
         */
        public static List<String> unzip(File zipFile, File targetDirectory, String prefix, Charset charset)
                        throws IOException {
                ZipFile zip = null;
                try {
                        if (charset == null) {
                                zip = new ZipFile(zipFile);
                        } else {
                                zip = new ZipFile(zipFile, charset);
                        }
                        return unzip(zip, targetDirectory, prefix);
                } finally {
                        close(zip);
                }
        }

        /**
         * Extract entries of a ZipFile to a directory when the ZipFile is created
         * externally. Note that this does not close the ZipFile, so the caller has to
         * take care of this.
         */
        public static List<String> unzip(ZipFile zip, File targetDirectory, String prefix) throws IOException {
                Enumeration<? extends ZipArchiveEntry> entries = zip.getEntries();
                List<String> extractedPaths = new ArrayList<>();

                while (entries.hasMoreElements()) {
                        ZipArchiveEntry entry = entries.nextElement();
                        if (entry.isDirectory()) {
                                continue;
                        }
                        String fileName = entry.getName();
                        if (!StringUtils.isEmpty(prefix)) {
                                if (!fileName.startsWith(prefix)) {
                                        continue;
                                }
                                fileName = StringUtils.stripPrefix(fileName, prefix);
                        }

                        try (InputStream entryStream = zip.getInputStream(entry)) {
                                File file = new File(targetDirectory, fileName);
                                ensureParentDirectoryExists(file);

                                try (FileOutputStream outputStream = new FileOutputStream(file)) {
                                        copy(entryStream, outputStream);
                                }
                        }
                        extractedPaths.add(fileName);
                }
                return extractedPaths;
        }

        /**
         * Extract entries of a zip file input stream to a directory. The input stream
         * is automatically closed by this method.
         */
        public static List<String> unzip(InputStream inputStream, File targetDirectory) throws IOException {
                List<String> extractedPaths = new ArrayList<>();
                try (ZipInputStream zipStream = new ZipInputStream(inputStream)) {
                        while (true) {
                                ZipEntry entry = zipStream.getNextEntry();
                                if (entry == null) {
                                        break;
                                } else if (entry.isDirectory()) {
                                        continue;
                                }
                                String fileName = entry.getName();

                                File file = new File(targetDirectory, fileName);
                                ensureParentDirectoryExists(file);

                                try (OutputStream targetStream = new FileOutputStream(file)) {
                                        copy(zipStream, targetStream);
                                }
                                extractedPaths.add(fileName);
                        }
                }
                return extractedPaths;
        }

        /**
         * Write string to a file with the default encoding. This ensures all
         * directories exist.
         */
        public static void writeFile(File file, String content) throws IOException {
                writeFile(file, content, Charset.defaultCharset().name());
        }

        /**
         * Writes the given collection of String as lines into the specified file. This
         * method uses \n as a line separator.
         */
        public static void writeLines(File file, Collection<String> lines) throws IOException {
                writeFile(file, StringUtils.concat(lines, "\n"));
        }

        /**
         * Write string to a file with UTF8 encoding. This ensures all directories
         * exist.
         */
        public static void writeFileUTF8(File file, String content) throws IOException {
                writeFile(file, content, UTF8_ENCODING);
        }

        /** Write string to a file. This ensures all directories exist. */
        public static void writeFile(File file, String content, String encoding) throws IOException {
                ensureParentDirectoryExists(file);
                OutputStreamWriter writer = null;
                try {
                        writer = new OutputStreamWriter(new FileOutputStream(file), encoding);
                        writer.write(content);
                } finally {
                        FileSystemUtils.close(writer);
                }
        }

        /**
         * Write string to a file using a UTF encoding. The file will be prefixed with a
         * byte-order mark. This ensures all directories exist.
         */
        public static void writeFileWithBOM(File file, String content, EByteOrderMark bom) throws IOException {
                ensureParentDirectoryExists(file);
                FileOutputStream out = null;
                OutputStreamWriter writer = null;
                try {
                        out = new FileOutputStream(file);
                        out.write(bom.getBOM());

                        writer = new OutputStreamWriter(out, bom.getEncoding());
                        writer.write(content);
                        writer.flush();
                } finally {
                        FileSystemUtils.close(out);
                        FileSystemUtils.close(writer);
                }
        }

        /**
         * Writes the given bytes to the given file. Directories are created as needed.
         * The file is closed after writing.
         */
        public static void writeFileBinary(File file, byte[] bytes) throws IOException {
                ensureParentDirectoryExists(file);
                FileOutputStream out = null;
                try {
                        out = new FileOutputStream(file);
                        out.write(bytes);
                } finally {
                        FileSystemUtils.close(out);
                }
        }

        /**
         * Finds all files and directories contained in the given directory and all
         * subdirectories matching the filter provided and put them into the result
         * collection. The given directory itself is not included in the result.
         * <p>
         * This method knows nothing about (symbolic and hard) links, so care should be
         * taken when traversing directories containing recursive links.
         *
         * @param directory
         *            the directory to start the search from.
         * @param result
         *            the collection to add to all files found.
         * @param filter
         *            the filter used to determine whether the result should be
         *            included. If the filter is null, all files and directories are
         *            included.
         */
        private static void listFilesRecursively(File directory, Collection<File> result, FileFilter filter) {
                for (File file : directory.listFiles()) {
                        if (file.isDirectory()) {
                                listFilesRecursively(file, result, filter);
                        }
                        if (filter == null || filter.accept(file)) {
                                result.add(file);
                        }
                }
        }

        /**
         * Loads template file with a <a href=
         * "http://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax" >
         * Format string</a>, formats it and writes result to file.
         *
         * @param templateFile
         *            the template file with the format string
         * @param outFile
         *            the target file, parent directories are created automatically.
         * @param arguments
         *            the formatting arguments.
         * @throws IOException
         *             if an IO exception occurs or the template file defines an illegal
         *             format.
         */
        public static void mergeTemplate(File templateFile, File outFile, Object... arguments) throws IOException {
                String template = readFile(templateFile);
                String output;
                try {
                        output = String.format(template, arguments);
                } catch (IllegalFormatException e) {
                        throw new IOException("Illegal format: " + e.getMessage(), e);
                }
                writeFile(outFile, output);
        }

        /**
         * Loads template file with a <a href=
         * "http://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax" >
         * Format string</a>, formats it and provides result as stream. No streams are
         * closed by this method.
         *
         * @param inStream
         *            stream that provides the template format string
         * @param arguments
         *            the formatting arguments.
         * @throws IOException
         *             if an IOException occurs or the template file defines an illegal
         *             format.
         */
        public static InputStream mergeTemplate(InputStream inStream, Object... arguments) throws IOException {
                String template = readStream(inStream);
                String output;
                try {
                        output = String.format(template, arguments);
                } catch (IllegalFormatException e) {
                        throw new IOException("Illegal format: " + e.getMessage(), e);
                }
                return new ByteArrayInputStream(output.getBytes());
        }

        /** Read input stream into string. */
        public static String readStream(InputStream input) throws IOException {
                return readStream(input, Charset.defaultCharset());
        }

        /** Read input stream into string. */
        public static String readStreamUTF8(InputStream input) throws IOException {
                return readStream(input, StandardCharsets.UTF_8);
        }

        /**
         * Read input stream into string. This method is BOM aware, i.e. deals with the
         * UTF-BOM.
         */
        public static String readStream(InputStream input, Charset encoding) throws IOException {
                StringBuilder out = new StringBuilder();
                Reader r = streamReader(input, encoding);
                char[] b = new char[4096];

                int n;
                while ((n = r.read(b)) != -1) {
                        out.append(b, 0, n);
                }
                return out.toString();
        }

        /** Read input stream into raw byte array. */
        public static byte[] readStreamBinary(InputStream input) throws IOException {
                ByteArrayOutputStream out = new ByteArrayOutputStream();
                copy(input, out);
                return out.toByteArray();
        }

        /**
         * Returns a reader that wraps the given input stream. This method handles the
         * BOM transparently. As the normal reader constructors can not deal with this,
         * direct construction of readers is discouraged.
         */
        public static Reader streamReader(InputStream in, Charset encoding) throws IOException {
                // we need marking to read the BOM mark
                if (!in.markSupported()) {
                        in = new BufferedInputStream(in);
                }

                in.mark(EByteOrderMark.MAX_BOM_LENGTH);
                byte[] prefix = new byte[EByteOrderMark.MAX_BOM_LENGTH];

                EByteOrderMark bom = null;
                try {
                        safeRead(in, prefix);
                        bom = EByteOrderMark.determineBOM(prefix).orElse(null);
                } catch (IOException e) {
                        // just use provided encoding; keep BOM as null
                }

                in.reset();

                if (bom != null) {
                        encoding = bom.getEncoding();

                        // consume BOM
                        for (int i = 0; i < bom.getBOMLength(); ++i) {
                                in.read();
                        }
                }

                return new InputStreamReader(in, encoding);
        }

        /** Reads properties from a properties file. */
        public static Properties readProperties(File propertiesFile) throws IOException {
                return readProperties(() -> new FileInputStream(propertiesFile));
        }

        /** Reads properties from a properties resource. */
        public static Properties readProperties(Resource resource) throws IOException {
                return readProperties(resource::getAsStream);
        }

        /** Reads properties from a properties stream. */
        public static Properties readProperties(
                        CollectionUtils.SupplierWithException<? extends InputStream, IOException> streamSupplier)
                        throws IOException {
                try (InputStream stream = streamSupplier.get()) {
                        Properties props = new Properties();
                        props.load(stream);
                        return props;
                }
        }

        /**
         * Determines the root directory from a collection of files. The root directory
         * is the lowest common ancestor directory of the files in the directory tree.
         * <p>
         * This method does not require the input files to exist.
         *
         * @param files
         *            Collection of files for which root directory gets determined. This
         *            collection is required to contain at least 2 files. If it does
         *            not, an AssertionError is thrown.
         *
         * @throws AssertionError
         *             If less than two different files are provided whereas fully
         *             qualified canonical names are used for comparison.
         *
         * @throws IOException
         *             Since canonical paths are used for determination of the common
         *             root, and {@link File#getCanonicalPath()} can throw
         *             {@link IOException}s.
         *
         * @return Root directory, or null, if the files do not have a common root
         *         directory.
         */
        public static File commonRoot(Iterable<? extends File> files) throws IOException {
                // determine longest common prefix on canonical absolute paths
                Set<String> absolutePaths = new HashSet<>();
                for (File file : files) {
                        absolutePaths.add(file.getCanonicalPath());
                }

                CCSMAssert.isTrue(absolutePaths.size() >= 2, "Expected are at least 2 files");

                String longestCommonPrefix = StringUtils.longestCommonPrefix(absolutePaths);

                // trim to name of root directory (remove possible equal filename
                // prefixes.)
                int lastSeparator = longestCommonPrefix.lastIndexOf(File.separator);
                if (lastSeparator > -1) {
                        longestCommonPrefix = longestCommonPrefix.substring(0, lastSeparator);
                }

                if (StringUtils.isEmpty(longestCommonPrefix)) {
                        return null;
                }

                return new File(longestCommonPrefix);
        }

        /**
         * Transparently creates a stream for decompression if the provided stream is
         * compressed. Otherwise the stream is just handed through. Currently the
         * following compression methods are supported:
         * <ul>
         * <li>GZIP via {@link GZIPInputStream}</li>
         * </ul>
         */
        public static InputStream autoDecompressStream(InputStream in) throws IOException {
                if (!in.markSupported()) {
                        in = new BufferedInputStream(in);
                }
                in.mark(2);
                // check first two bytes for GZIP header
                boolean isGZIP = (in.read() & 0xff | (in.read() & 0xff) << 8) == GZIPInputStream.GZIP_MAGIC;
                in.reset();
                if (isGZIP) {
                        return new GZIPInputStream(in);
                }
                return in;
        }

        /**
         * Closes the given ZIP file quietly, i.e. ignoring a potential IOException.
         * Additionally it is <code>null</code> safe.
         */
        public static void close(ZipFile zipFile) {
                if (zipFile == null) {
                        return;
                }
                try {
                        zipFile.close();
                } catch (IOException e) {
                        // ignore
                }
        }

        /**
         * Convenience method for calling {@link #close(Closeable, ILogger)} with a
         * <code>null</code>-logger.
         */
        public static void close(Closeable closeable) {
                close(closeable, null);
        }

        /**
         * This method can be used to simplify the typical <code>finally</code> -block
         * of code dealing with streams and readers/writers. It checks if the provided
         * closeable is <code>null</code>. If not it closes it. An exception thrown
         * during the close operation is logged with the provided logger with level
         * <i>warn</i>. If the provided logger is <code>null</code>, no logging is
         * performed. If no logging is required, method {@link #close(Closeable)} may
         * also be used.
         */
        public static void close(Closeable closeable, ILogger logger) {
                if (closeable == null) {
                        return;
                }

                try {
                        closeable.close();
                } catch (IOException e) {
                        if (logger != null) {
                                logger.warn("Trouble closing: " + e.getMessage());
                        }
                }
        }

        /**
         * Compares files based on the lexical order of their fully qualified names.
         * Files must not null.
         */
        public static void sort(List<File> files) {
                files.sort(new FilenameComparator());
        }

        /**
         * Replace platform dependent separator char with forward slashes to create
         * system-independent paths.
         */
        public static String normalizeSeparators(String path) {
                return path.replace(File.separatorChar, UNIX_SEPARATOR);
        }

        /**
         * Returns the JAR file for an URL with protocol 'jar'. If the protocol is not
         * 'jar' an assertion error will be caused! An assertion error is also thrown if
         * URL does not point to a file.
         */
        public static File extractJarFileFromJarURL(URL url) {
                CCSMAssert.isTrue("jar".equals(url.getProtocol()), "May only be used with 'jar' URLs!");

                String path = url.getPath();
                CCSMAssert.isTrue(path.startsWith("file:"), "May only be used for URLs pointing to files");

                // the exclamation mark is the separator between jar file and path
                // within the file
                int index = path.indexOf('!');
                CCSMAssert.isTrue(index >= 0, "Unknown format for jar URLs");
                path = path.substring(0, index);

                return fromURL(path);
        }

        /**
         * Often file URLs are created the wrong way, i.e. without proper escaping
         * characters invalid in URLs. Unfortunately, the URL class allows this and the
         * Eclipse framework does it. See
         * http://weblogs.java.net/blog/2007/04/25/how-convert-javaneturl-javaiofile for
         * details.
         *
         * This method attempts to fix this problem and create a file from it.
         *
         * @throws AssertionError
         *             if cleaning up fails.
         */
        private static File fromURL(String url) {

                // We cannot simply encode the URL this also encodes slashes and other
                // stuff. As a result, the file constructor throws an exception. As a
                // simple heuristic, we only fix the spaces.
                // The other route to go would be manually stripping of "file:" and
                // simply creating a file. However, this does not work if the URL was
                // created properly and contains URL escapes.

                url = url.replace(StringUtils.SPACE, "%20");
                try {
                        return new File(new URI(url));
                } catch (URISyntaxException e) {
                        throw new AssertionError("The assumption is that this method is capable of "
                                        + "working with non-standard-compliant URLs, too. " + "Apparently it is not. Invalid URL: " + url
                                        + ". Ex: " + e.getMessage(), e);
                }
        }

        /**
         * Returns whether a filename represents an absolute path.
         *
         * This method returns the same result, independent on which operating system it
         * gets executed. In contrast, the behavior of {@link File#isAbsolute()} is
         * operating system specific.
         */
        public static boolean isAbsolutePath(String filename) {
                // Unix and MacOS: absolute path starts with slash or user home
                if (filename.startsWith("/") || filename.startsWith("~")) {
                        return true;
                }
                // Windows and OS/2: absolute path start with letter and colon
                if (filename.length() > 2 && Character.isLetter(filename.charAt(0)) && filename.charAt(1) == ':') {
                        return true;
                }
                // UNC paths (aka network shares): start with double backslash
                if (filename.startsWith("\\\\")) {
                        return true;
                }

                return false;
        }

        /**
         * Reads bytes of data from the input stream into an array of bytes until the
         * array is full. This method blocks until input data is available, end of file
         * is detected, or an exception is thrown.
         *
         * The reason for this method is that {@link InputStream#read(byte[])} may read
         * less than the requested number of bytes, while this method ensures the data
         * is complete.
         *
         * @param in
         *            the stream to read from.
         * @param data
         *            the stream to read from.
         * @throws IOException
         *             if reading the underlying stream causes an exception.
         * @throws EOFException
         *             if the end of file was reached before the requested data was
         *             read.
         */
        public static void safeRead(InputStream in, byte[] data) throws IOException, EOFException {
                safeRead(in, data, 0, data.length);
        }

        /**
         * Reads <code>length</code> bytes of data from the input stream into an array
         * of bytes and stores it at position <code>offset</code>. This method blocks
         * until input data is available, end of file is detected, or an exception is
         * thrown.
         *
         * The reason for this method is that {@link InputStream#read(byte[], int, int)}
         * may read less than the requested number of bytes, while this method ensures
         * the data is complete.
         *
         * @param in
         *            the stream to read from.
         * @param data
         *            the stream to read from.
         * @param offset
         *            the offset in the array where the first read byte is stored.
         * @param length
         *            the length of data read.
         * @throws IOException
         *             if reading the underlying stream causes an exception.
         * @throws EOFException
         *             if the end of file was reached before the requested data was
         *             read.
         */
        public static void safeRead(InputStream in, byte[] data, int offset, int length) throws IOException, EOFException {
                while (length > 0) {
                        int read = in.read(data, offset, length);
                        if (read < 0) {
                                throw new EOFException("Reached end of file before completing read.");
                        }
                        offset += read;
                        length -= read;
                }
        }

        /** Obtains the system's temporary directory */
        public static File getTmpDir() {
                return new File(TEMP_DIR_PATH);
        }

        /** Obtains the current user's home directory */
        public static File getUserHomeDir() {
                return new File(System.getProperty("user.home"));
        }

        /**
         * Obtains the current working directory. This is usually the directory in which
         * the current Java process was started.
         */
        public static File getWorkspaceDir() {
                if (Boolean.getBoolean("com.teamscale.dev-mode") || isJUnitTest()) {
                        return getTmpDir();
                }
                return new File(System.getProperty("user.dir"));
        }

        private static boolean isJUnitTest() {
                StackTraceElement[] stackTrace = Thread.currentThread().getStackTrace();
                for (StackTraceElement element : stackTrace) {
                        if (element.getClassName().startsWith("org.junit.")) {
                                return true;
                        }
                }
                return false;
        }

        /** Checks whether two files have the same content. */
        public static boolean contentsEqual(File file1, File file2) throws IOException {
                byte[] content1 = readFileBinary(file1);
                byte[] content2 = readFileBinary(file2);
                return Arrays.equals(content1, content2);
        }

        /**
         * Opens an {@link InputStream} for the entry with the given name in the given
         * JAR file
         */
        public static InputStream openJarFileEntry(JarFile jarFile, String entryName) throws IOException {
                JarEntry entry = jarFile.getJarEntry(entryName);
                if (entry == null) {
                        throw new IOException("No entry '" + entryName + "' found in JAR file '" + jarFile + "'");
                }
                return jarFile.getInputStream(entry);
        }

        /**
         * Returns whether the given file is non-null, a plain file and is readable.
         */
        public static boolean isReadableFile(File... files) {
                for (File file : files) {
                        if (file == null || !file.exists() || !file.isFile() || !file.canRead()) {
                                return false;
                        }
                }
                return true;
        }

        /**
         * Concatenates all path parts into a single path with normalized separators.
         */
        public static String concatenatePaths(String firstParent, String... paths) {
                return FileSystemUtils.normalizeSeparators(Paths.get(firstParent, paths).toString());
        }

        /**
         * Removes the given path if it is an empty directory and recursively parent
         * directories if the only child was deleted.
         *
         * If the given path points to file which does not exist, the parent directory
         * of that file is deleted.
         *
         * @throws IOException
         *             if an I/O error during deletion occurs.
         */
        public static void recursivelyRemoveDirectoryIfEmpty(File path) throws IOException {
                String[] children = path.list();
                if (children == null) {
                        // path either points to a plain file or to a non-existent
                        // path. In the first case, nothing should be done otherwise
                        // deletion should continue with the parent path.
                        if (path.exists()) {
                                return;
                        }
                } else if (children.length == 0) {
                        deleteFile(path);
                } else {
                        return;
                }
                recursivelyRemoveDirectoryIfEmpty(path.getParentFile());
        }

        /**
         * Returns a file that does not exist in the same directory of the given file.
         * It either returns the passed file (if not exiting) or appends a number
         * between the filename and the extension to ensure uniqueness, e.g.
         * path/to/file_1.ext if path/to/file.ext is passed but this file already
         * exists. The number is incremented until the file does not exist.
         */
        public static File getNonExistingFile(File file) {
                if (!file.exists()) {
                        return file;
                }

                String extensionlessName = getFilenameWithoutExtension(file);
                int suffix = 0;
                String extension = FileSystemUtils.getFileExtension(file);

                do {
                        file = new File(file.getParentFile(), extensionlessName + "_" + ++suffix + "." + extension);
                } while (file.exists());

                return file;
        }

        /**
         * Converts the given human readable data size to the corresponding number of
         * bytes. For example "1 KB" is converted to 1024. Also supports Si units ("1
         * KiB" is converted to 1000).
         *
         * Commas are ignored and can be used as thousands separator. A dot is the
         * decimal separator. ("1.2KiB" is converted to 1200).
         *
         * Method implementation based on stackoverflow
         * https://stackoverflow.com/a/45860167
         */
        public static long parseDataSize(String dataSize) {
                String dataSizeWithoutComma = dataSize.replaceAll(",", "");
                int unitBeginIndex = StringUtils.indexOfMatch(dataSizeWithoutComma, DATA_SIZE_UNIT_START_PATTERN);
                if (unitBeginIndex == -1) {
                        return Long.parseLong(dataSizeWithoutComma);
                }
                double rawDataSize = Double.parseDouble(dataSizeWithoutComma.substring(0, unitBeginIndex));
                String unitString = dataSizeWithoutComma.substring(unitBeginIndex);
                int unitChar = unitString.charAt(0);
                int power = METRIC_SYSTEM_UNITS.indexOf(unitChar) + 1;
                boolean isSi = unitBeginIndex != -1 && unitString.length() >= 2 && unitString.charAt(1) == 'i';

                int factor = 1024;
                if (isSi) {
                        factor = 1000;
                        if (StringUtils.stripSuffix(unitString, "B").length() != 2) {
                                throw new NumberFormatException("Malformed data size: " + dataSizeWithoutComma);
                        }
                } else if (power == 0) {
                        if (StringUtils.stripSuffix(unitString, "B").length() != 0) {
                                throw new NumberFormatException("Malformed data size: " + dataSizeWithoutComma);
                        }
                } else {
                        if (StringUtils.stripSuffix(unitString, "B").length() != 1) {
                                throw new NumberFormatException("Malformed data size: " + dataSizeWithoutComma);
                        }
                }
                return (long) (rawDataSize * Math.pow(factor, power));
        }

        /** Determines the last modified timestamp in a platform agnostic way. */
        public static long getLastModifiedTimestamp(File file) throws IOException {
                return Files.getLastModifiedTime(Paths.get(file.toURI())).toMillis();
        }

        /**
         * Returns a safe filename that can be used for downloads. Replaces everything
         * that is not a letter or number with "-"
         */
        public static String toSafeFilename(String name) {
                name = name.replaceAll("\\W+", "-");
                name = name.replaceAll("[-_]+", "-");
                return name;
        }

        /**
         * Returns a new file with all file path segments that are reserved (windows)
         * path names escaped.
         */
        public static File escapeReservedFileNames(File file) {
                String[] parts = file.getPath().split(Pattern.quote(File.separator));
                for (int i = 0; i < parts.length; ++i) {
                        if (RESERVED_PATH_SEGMENT_NAMES.contains(parts[i])) {
                                parts[i] = "_" + parts[i];
                        }
                }
                return new File(StringUtils.concat(parts, File.separator));
        }

        /**
         * Reads a file using UTF-8 encoding and normalizes line breaks (replacing
         * "\n\r" and "\r" with "\n"). This generates an OS-independent view on a file.
         * To ensure OS-independent test results, this method should be used in all
         * tests to read files.
         */
        public static String readFileSystemIndependent(File file) throws IOException {
                return StringUtils.normalizeLineSeparatorsPlatformIndependent(readFileUTF8(file));

        }

        /**
         * Replaces the file name of the given path with the given new extension.
         * Returns the newFileName if the file denoted by the uniform path does not
         * contain a '/'. This method assumes that folders are separated by '/' (uniform
         * paths).
         *
         * Examples:
         * <ul>
         * <li><code>replaceFilePathFilenameWith("xx", "yy")</code> returns
         * <code>"yy"</code></li>
         * <li><code>replaceFilePathFilenameWith("xx/zz", "yy")</code> returns *
         * <code>"xx/yy"</code></li>
         * <li><code>replaceFilePathFilenameWith("xx/zz/", "yy")</code> returns *
         * <code>"xx/zz/yy"</code></li>
         * <li><code>replaceFilePathFilenameWith("", "yy")</code> returns *
         * <code>"yy"</code></li>
         * </ul>
         */
        public static String replaceFilePathFilenameWith(String uniformPath, String newFileName) {
                int folderSepIndex = uniformPath.lastIndexOf('/');

                if (uniformPath.endsWith("/")) {
                        return uniformPath + newFileName;
                } else if (folderSepIndex == -1) {
                        return newFileName;
                }
                return uniformPath.substring(0, folderSepIndex) + "/" + newFileName;
        }
}