/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.apache.jackrabbit.core.fs;

import java.io.ByteArrayOutputStream;
import java.util.BitSet;


/**
 * Utility class for handling paths in a file system.
 */
public final class FileSystemPathUtil {

    /**
     * Array of lowercase hexadecimal characters used in creating hex escapes.
     */
    private static final char[] HEX_TABLE = "0123456789abcdef".toCharArray();

    /**
     * The escape character used to mark hex escape sequences.
     */
    private static final char ESCAPE_CHAR = '%';

    /**
     * The list of characters that are not encoded by the <code>escapeName(String)</code>
     * and <code>unescape(String)</code> methods. They contains the characters
     * which can safely be used in file names:
     */
    public static final BitSet SAFE_NAMECHARS;

    /**
     * The list of characters that are not encoded by the <code>escapePath(String)</code>
     * and <code>unescape(String)</code> methods. They contains the characters
     * which can safely be used in file paths:
     */
    public static final BitSet SAFE_PATHCHARS;

    static {
        // build list of valid name characters
        SAFE_NAMECHARS = new BitSet(256);
        int i;
        for (i = 'a'; i <= 'z'; i++) {
            SAFE_NAMECHARS.set(i);
        }
        for (i = 'A'; i <= 'Z'; i++) {
            SAFE_NAMECHARS.set(i);
        }
        for (i = '0'; i <= '9'; i++) {
            SAFE_NAMECHARS.set(i);
        }
        SAFE_NAMECHARS.set('-');
        SAFE_NAMECHARS.set('_');
        SAFE_NAMECHARS.set('.');

        // build list of valid path characters (includes name characters)
        SAFE_PATHCHARS = (BitSet) SAFE_NAMECHARS.clone();
        SAFE_PATHCHARS.set(FileSystem.SEPARATOR_CHAR);
    }

    /**
     * private constructor
     */
    private FileSystemPathUtil() {
    }

    /**
     * Escapes the given string using URL encoding for all bytes not included
     * in the given set of safe characters.
     *
     * @param s the string to escape
     * @param safeChars set of safe characters (bytes)
     * @return escaped string
     */
    private static String escape(String s, BitSet safeChars) {
        byte[] bytes = s.getBytes();
        StringBuilder out = new StringBuilder(bytes.length);
        for (int i = 0; i < bytes.length; i++) {
            int c = bytes[i] & 0xff;
            if (safeChars.get(c) && c != ESCAPE_CHAR) {
                out.append((char) c);
            } else {
                out.append(ESCAPE_CHAR);
                out.append(HEX_TABLE[(c >> 4) & 0x0f]);
                out.append(HEX_TABLE[(c) & 0x0f]);
            }
        }
        return out.toString();
    }

    /**
     * Encodes the specified <code>path</code>. Same as
     * <code>{@link #escapeName(String)}</code> except that the separator
     * character <b><code>/</code></b> is regarded as a legal path character
     * that needs no escaping.
     *
     * @param path the path to encode.
     * @return the escaped path
     */
    public static String escapePath(String path) {
        return escape(path, SAFE_PATHCHARS);
    }

    /**
     * Encodes the specified <code>name</code>. Same as
     * <code>{@link #escapePath(String)}</code> except that the separator character
     * <b><code>/</code></b> is regarded as an illegal character that needs
     * escaping.
     *
     * @param name the name to encode.
     * @return the escaped name
     */
    public static String escapeName(String name) {
        return escape(name, SAFE_NAMECHARS);
    }

    /**
     * Decodes the specified path/name.
     *
     * @param pathOrName the escaped path/name
     * @return the unescaped path/name
     */
    public static String unescape(String pathOrName) {
        ByteArrayOutputStream out = new ByteArrayOutputStream(pathOrName.length());
        for (int i = 0; i < pathOrName.length(); i++) {
            char c = pathOrName.charAt(i);
            if (c == ESCAPE_CHAR) {
                try {
                    out.write(Integer.parseInt(pathOrName.substring(i + 1, i + 3), 16));
                } catch (NumberFormatException e) {
                    IllegalArgumentException iae = new IllegalArgumentException("Failed to unescape escape sequence");
                    iae.initCause(e);
                    throw iae;
                }
                i += 2;
            } else {
                out.write(c);
            }
        }
        return new String(out.toByteArray());
    }

    /**
     * Tests whether the specified path represents the root path, i.e. "/".
     *
     * @param path path to test
     * @return true if the specified path represents the root path; false otherwise.
     */
    public static boolean denotesRoot(String path) {
        return path.equals(FileSystem.SEPARATOR);
    }

    /**
     * Checks if <code>path</code> is a valid path.
     *
     * @param path the path to be checked
     * @throws FileSystemException If <code>path</code> is not a valid path
     */
    public static void checkFormat(String path) throws FileSystemException {
        if (path == null) {
            throw new FileSystemException("null path");
        }

        // path must be absolute, i.e. starting with '/'
        if (!path.startsWith(FileSystem.SEPARATOR)) {
            throw new FileSystemException("not an absolute path: " + path);
        }

        // trailing '/' is not allowed (except for root path)
        if (path.endsWith(FileSystem.SEPARATOR) && path.length() > 1) {
            throw new FileSystemException("malformed path: " + path);
        }

        String[] names = path.split(FileSystem.SEPARATOR);
        for (int i = 1; i < names.length; i++) {
            // name must not be empty
            if (names[i].length() == 0) {
                throw new FileSystemException("empty name: " + path);
            }
            // leading/trailing whitespace is not allowed
            String trimmed = names[i].trim();
            if (!trimmed.equals(names[i])) {
                throw new FileSystemException("illegal leading or trailing whitespace in name: " + path);
            }
        }
    }

    /**
     * Returns the parent directory of the specified <code>path</code>.
     *
     * @param path a file system path denoting a directory or a file.
     * @return the parent directory.
     */
    public static String getParentDir(String path) {
        int pos = path.lastIndexOf(FileSystem.SEPARATOR_CHAR);
        if (pos > 0) {
            return path.substring(0, pos);
        }
        return FileSystem.SEPARATOR;
    }

    /**
     * Returns the name of the specified <code>path</code>.
     *
     * @param path a file system path denoting a directory or a file.
     * @return the name.
     */
    public static String getName(String path) {
        int pos = path.lastIndexOf(FileSystem.SEPARATOR_CHAR);
        if (pos != -1) {
            return path.substring(pos + 1);
        }
        return path;
    }

}
