    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *     https://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.configuration2.io;
    018
    019import java.io.File;
    020import java.net.MalformedURLException;
    021import java.net.URI;
    022import java.net.URL;
    023import java.util.Arrays;
    024import java.util.Map;
    025
    026import org.apache.commons.configuration2.ex.ConfigurationException;
    027import org.apache.commons.lang3.ObjectUtils;
    028import org.apache.commons.lang3.StringUtils;
    029import org.apache.commons.logging.Log;
    030import org.apache.commons.logging.LogFactory;
    031
    032/**
    033 * <p>
    034 * A utility class providing helper methods related to locating files.
    035 * </p>
    036 * <p>
    037 * The methods of this class are used behind the scenes when retrieving configuration files based on different criteria,
    038 * for example URLs, files, or more complex search strategies. They also implement functionality required by the default
    039 * {@link FileSystem} implementations. Most methods are intended to be used internally only by other classes in the
    040 * {@code io} package.
    041 * </p>
    042 *
    043 * @since 2.0
    044 */
    045public final class FileLocatorUtils {
    046
    047    /**
    048     * Constant for the default {@code FileSystem}. This file system is used by operations of this class if no specific file
    049     * system is provided. An instance of {@link DefaultFileSystem} is used.
    050     */
    051    public static final FileSystem DEFAULT_FILE_SYSTEM = new DefaultFileSystem();
    052
    053    /**
    054     * Constant for the default {@code FileLocationStrategy}. This strategy is used by the {@code locate()} method if the
    055     * passed in {@code FileLocator} does not define its own location strategy. The default location strategy is roughly
    056     * equivalent to the search algorithm used in version 1.x of <em>Commons Configuration</em> (there it was hard-coded
    057     * though). It behaves in the following way when passed a {@code FileLocator}:
    058     * <ul>
    059     * <li>If the {@code FileLocator} has a defined URL, this URL is used as the file's URL (without any further
    060     * checks).</li>
    061     * <li>Otherwise, base path and file name stored in the {@code FileLocator} are passed to the current
    062     * {@code FileSystem}'s {@code locateFromURL()} method. If this results in a URL, it is returned.</li>
    063     * <li>Otherwise, if the locator's file name is an absolute path to an existing file, the URL of this file is
    064     * returned.</li>
    065     * <li>Otherwise, the concatenation of base path and file name is constructed. If this path points to an existing file,
    066     * its URL is returned.</li>
    067     * <li>Otherwise, a sub directory of the current user's home directory as defined by the base path is searched for the
    068     * referenced file. If the file can be found there, its URL is returned.</li>
    069     * <li>Otherwise, the base path is ignored, and the file name is searched in the current user's home directory. If the
    070     * file can be found there, its URL is returned.</li>
    071     * <li>Otherwise, a resource with the name of the locator's file name is searched in the classpath. If it can be found,
    072     * its URL is returned.</li>
    073     * <li>Otherwise, the strategy gives up and returns <strong>null</strong> indicating that the file cannot be resolved.</li>
    074     * </ul>
    075     */
    076    public static final FileLocationStrategy DEFAULT_LOCATION_STRATEGY = initDefaultLocationStrategy();
    077
    078    /** Constant for the file URL protocol */
    079    private static final String FILE_SCHEME = "file:";
    080
    081    /** The logger. */
    082    private static final Log LOG = LogFactory.getLog(FileLocatorUtils.class);
    083
    084    /** Property key for the base path. */
    085    private static final String PROP_BASE_PATH = "basePath";
    086
    087    /** Property key for the encoding. */
    088    private static final String PROP_ENCODING = "encoding";
    089
    090    /** Property key for the file name. */
    091    private static final String PROP_FILE_NAME = "fileName";
    092
    093    /** Property key for the file system. */
    094    private static final String PROP_FILE_SYSTEM = "fileSystem";
    095
    096    /** Property key for the location strategy. */
    097    private static final String PROP_STRATEGY = "locationStrategy";
    098
    099    /** Property key for the source URL. */
    100    private static final String PROP_SOURCE_URL = "sourceURL";
    101
    102    /**
    103     * Extends a path by another component. The given extension is added to the already existing path adding a separator if
    104     * necessary.
    105     *
    106     * @param path the path to be extended
    107     * @param ext the extension of the path
    108     * @return the extended path
    109     */
    110    static String appendPath(final String path, final String ext) {
    111        final StringBuilder fName = new StringBuilder();
    112        fName.append(path);
    113
    114        // My best friend. Paranoia.
    115        if (!path.endsWith(File.separator)) {
    116            fName.append(File.separator);
    117        }
    118
    119        //
    120        // We have a relative path, and we have
    121        // two possible forms here. If we have the
    122        // "./" form then just strip that off first
    123        // before continuing.
    124        //
    125        if (ext.startsWith("." + File.separator)) {
    126            fName.append(ext.substring(2));
    127        } else {
    128            fName.append(ext);
    129        }
    130        return fName.toString();
    131    }
    132
    133    /**
    134     * Helper method for constructing a file object from a base path and a file name. This method is called if the base path
    135     * passed to {@code getURL()} does not seem to be a valid URL.
    136     *
    137     * @param basePath the base path
    138     * @param fileName the file name (must not be <strong>null</strong>)
    139     * @return the resulting file
    140     */
    141    static File constructFile(final String basePath, final String fileName) {
    142        final File file;
    143
    144        final File absolute = new File(fileName);
    145        if (StringUtils.isEmpty(basePath) || absolute.isAbsolute()) {
    146            file = absolute;
    147        } else {
    148            file = new File(appendPath(basePath, fileName));
    149        }
    150
    151        return file;
    152    }
    153
    154    /**
    155     * Tries to convert the specified file to a URL. If this causes an exception, result is <strong>null</strong>.
    156     *
    157     * @param file the file to be converted
    158     * @return the resulting URL or <strong>null</strong>
    159     */
    160    static URL convertFileToURL(final File file) {
    161        return convertURIToURL(file.toURI());
    162    }
    163
    164    /**
    165     * Tries to convert the specified URI to a URL. If this causes an exception, result is <strong>null</strong>.
    166     *
    167     * @param uri the URI to be converted
    168     * @return the resulting URL or <strong>null</strong>
    169     */
    170    static URL convertURIToURL(final URI uri) {
    171        try {
    172            return uri.toURL();
    173        } catch (final MalformedURLException e) {
    174            return null;
    175        }
    176    }
    177
    178    /**
    179     * Creates a fully initialized {@code FileLocator} based on the specified URL.
    180     *
    181     * @param src the source {@code FileLocator}
    182     * @param url the URL
    183     * @return the fully initialized {@code FileLocator}
    184     */
    185    private static FileLocator createFullyInitializedLocatorFromURL(final FileLocator src, final URL url) {
    186        final FileLocator.FileLocatorBuilder fileLocatorBuilder = fileLocator(src);
    187        if (src.getSourceURL() == null) {
    188            fileLocatorBuilder.sourceURL(url);
    189        }
    190        if (StringUtils.isBlank(src.getFileName())) {
    191            fileLocatorBuilder.fileName(getFileName(url));
    192        }
    193        if (StringUtils.isBlank(src.getBasePath())) {
    194            fileLocatorBuilder.basePath(getBasePath(url));
    195        }
    196        return fileLocatorBuilder.create();
    197    }
    198
    199    /**
    200     * Tries to convert the specified URL to a file object. If this fails, <strong>null</strong> is returned.
    201     *
    202     * @param url the URL
    203     * @return the resulting file object
    204     */
    205    public static File fileFromURL(final URL url) {
    206        return FileUtils.toFile(url);
    207    }
    208
    209    /**
    210     * Returns an uninitialized {@code FileLocatorBuilder} which can be used for the creation of a {@code FileLocator}
    211     * object. This method provides a convenient way to create file locators using a fluent API as in the following example:
    212     *
    213     * <pre>
    214     * FileLocator locator = FileLocatorUtils.fileLocator().basePath(myBasePath).fileName("test.xml").create();
    215     * </pre>
    216     *
    217     * @return a builder object for defining a {@code FileLocator}
    218     */
    219    public static FileLocator.FileLocatorBuilder fileLocator() {
    220        return fileLocator(null);
    221    }
    222
    223    /**
    224     * Returns a {@code FileLocatorBuilder} which is already initialized with the properties of the passed in
    225     * {@code FileLocator}. This builder can be used to create a {@code FileLocator} object which shares properties of the
    226     * original locator (for example the {@code FileSystem} or the encoding), but points to a different file. An example use case
    227     * is as follows:
    228     *
    229     * <pre>
    230     * FileLocator loc1 = ...
    231     * FileLocator loc2 = FileLocatorUtils.fileLocator(loc1)
    232     *     .setFileName("anotherTest.xml")
    233     *     .create();
    234     * </pre>
    235     *
    236     * @param src the source {@code FileLocator} (may be <strong>null</strong>)
    237     * @return an initialized builder object for defining a {@code FileLocator}
    238     */
    239    public static FileLocator.FileLocatorBuilder fileLocator(final FileLocator src) {
    240        return new FileLocator.FileLocatorBuilder(src);
    241    }
    242
    243    /**
    244     * Creates a new {@code FileLocator} object with the properties defined in the given map. The map must be conform to the
    245     * structure generated by the {@link #put(FileLocator, Map)} method; unexpected data can cause
    246     * {@code ClassCastException} exceptions. The map can be <strong>null</strong>, then an uninitialized {@code FileLocator} is
    247     * returned.
    248     *
    249     * @param map the map
    250     * @return the new {@code FileLocator}
    251     * @throws ClassCastException if the map contains invalid data
    252     */
    253    public static FileLocator fromMap(final Map<String, ?> map) {
    254        final FileLocator.FileLocatorBuilder builder = fileLocator();
    255        if (map != null) {
    256            builder.basePath((String) map.get(PROP_BASE_PATH)).encoding((String) map.get(PROP_ENCODING)).fileName((String) map.get(PROP_FILE_NAME))
    257                .fileSystem((FileSystem) map.get(PROP_FILE_SYSTEM)).locationStrategy((FileLocationStrategy) map.get(PROP_STRATEGY))
    258                .sourceURL((URL) map.get(PROP_SOURCE_URL));
    259        }
    260        return builder.create();
    261    }
    262
    263    /**
    264     * Returns a {@code FileLocator} object based on the passed in one whose location is fully defined. This method ensures
    265     * that all components of the {@code FileLocator} pointing to the file are set in a consistent way. In detail it behaves
    266     * as follows:
    267     * <ul>
    268     * <li>If the {@code FileLocator} has already all components set which define the file, it is returned unchanged.
    269     * <em>Note:</em> It is not checked whether all components are really consistent!</li>
    270     * <li>{@link #locate(FileLocator)} is called to determine a unique URL pointing to the referenced file. If this is
    271     * successful, a new {@code FileLocator} is created as a copy of the passed in one, but with all components pointing to
    272     * the file derived from this URL.</li>
    273     * <li>Otherwise, result is <strong>null</strong>.</li>
    274     * </ul>
    275     *
    276     * @param locator the {@code FileLocator} to be completed
    277     * @return a {@code FileLocator} with a fully initialized location if possible or <strong>null</strong>
    278     */
    279    public static FileLocator fullyInitializedLocator(final FileLocator locator) {
    280        if (isFullyInitialized(locator)) {
    281            // already fully initialized
    282            return locator;
    283        }
    284
    285        final URL url = locate(locator);
    286        return url != null ? createFullyInitializedLocatorFromURL(locator, url) : null;
    287    }
    288
    289    /**
    290     * Gets the path without the file name, for example https://xyz.net/foo/bar.xml results in https://xyz.net/foo/
    291     *
    292     * @param url the URL from which to extract the path
    293     * @return the path component of the passed in URL
    294     */
    295    static String getBasePath(final URL url) {
    296        if (url == null) {
    297            return null;
    298        }
    299
    300        String s = url.toString();
    301        if (s.startsWith(FILE_SCHEME) && !s.startsWith("file://")) {
    302            s = "file://" + s.substring(FILE_SCHEME.length());
    303        }
    304
    305        if (s.endsWith("/") || StringUtils.isEmpty(url.getPath())) {
    306            return s;
    307        }
    308        return s.substring(0, s.lastIndexOf("/") + 1);
    309    }
    310
    311    /**
    312     * Tries to find a resource with the given name in the classpath.
    313     *
    314     * @param resourceName the name of the resource
    315     * @return the URL to the found resource or <strong>null</strong> if the resource cannot be found
    316     */
    317    static URL getClasspathResource(final String resourceName) {
    318        URL url = null;
    319        // attempt to load from the context classpath
    320        final ClassLoader loader = Thread.currentThread().getContextClassLoader();
    321        if (loader != null) {
    322            url = loader.getResource(resourceName);
    323
    324            if (url != null) {
    325                LOG.debug("Loading configuration from the context classpath (" + resourceName + ")");
    326            }
    327        }
    328
    329        // attempt to load from the system classpath
    330        if (url == null) {
    331            url = ClassLoader.getSystemResource(resourceName);
    332
    333            if (url != null) {
    334                LOG.debug("Loading configuration from the system classpath (" + resourceName + ")");
    335            }
    336        }
    337        return url;
    338    }
    339
    340    /**
    341     * Tries to convert the specified base path and file name into a file object. This method is called for example by the save()
    342     * methods of file based configurations. The parameter strings can be relative files, absolute files and URLs as well.
    343     * This implementation checks first whether the passed in file name is absolute. If this is the case, it is returned.
    344     * Otherwise further checks are performed whether the base path and file name can be combined to a valid URL or a valid
    345     * file name. <em>Note:</em> The test if the passed in file name is absolute is performed using
    346     * {@code java.io.File.isAbsolute()}. If the file name starts with a slash, this method will return <strong>true</strong> on Unix,
    347     * but <strong>false</strong> on Windows. So to ensure correct behavior for relative file names on all platforms you should never
    348     * let relative paths start with a slash. E.g. in a configuration definition file do not use something like that:
    349     *
    350     * <pre>
    351     * &lt;properties fileName="/subdir/my.properties"/&gt;
    352     * </pre>
    353     *
    354     * Under Windows this path would be resolved relative to the configuration definition file. Under Unix this would be
    355     * treated as an absolute path name.
    356     *
    357     * @param basePath the base path
    358     * @param fileName the file name (must not be <strong>null</strong>)
    359     * @return the file object (<strong>null</strong> if no file can be obtained)
    360     */
    361    static File getFile(final String basePath, final String fileName) {
    362        // Check if the file name is absolute
    363        final File f = new File(fileName);
    364        if (f.isAbsolute()) {
    365            return f;
    366        }
    367
    368        // Check if URLs are involved
    369        URL url;
    370        try {
    371            url = new URL(new URL(basePath), fileName);
    372        } catch (final MalformedURLException mex1) {
    373            try {
    374                url = new URL(fileName);
    375            } catch (final MalformedURLException mex2) {
    376                url = null;
    377            }
    378        }
    379
    380        if (url != null) {
    381            return fileFromURL(url);
    382        }
    383
    384        return constructFile(basePath, fileName);
    385    }
    386
    387    /**
    388     * Extract the file name from the specified URL.
    389     *
    390     * @param url the URL from which to extract the file name
    391     * @return the extracted file name
    392     */
    393    static String getFileName(final URL url) {
    394        if (url == null) {
    395            return null;
    396        }
    397
    398        final String path = url.getPath();
    399
    400        if (path.endsWith("/") || StringUtils.isEmpty(path)) {
    401            return null;
    402        }
    403        return path.substring(path.lastIndexOf("/") + 1);
    404    }
    405
    406    /**
    407     * Obtains a non-<strong>null</strong> {@code FileSystem} object from the passed in {@code FileLocator}. If the passed in
    408     * {@code FileLocator} has a {@code FileSystem} object, it is returned. Otherwise, result is the default
    409     * {@code FileSystem}.
    410     *
    411     * @param locator the {@code FileLocator} (may be <strong>null</strong>)
    412     * @return the {@code FileSystem} to be used for this {@code FileLocator}
    413     */
    414    static FileSystem getFileSystem(final FileLocator locator) {
    415        return locator != null ? ObjectUtils.getIfNull(locator.getFileSystem(), DEFAULT_FILE_SYSTEM) : DEFAULT_FILE_SYSTEM;
    416    }
    417
    418    /**
    419     * Gets a non <strong>null</strong> {@code FileLocationStrategy} object from the passed in {@code FileLocator}. If the
    420     * {@code FileLocator} is not <strong>null</strong> and has a {@code FileLocationStrategy} defined, this strategy is returned.
    421     * Otherwise, result is the default {@code FileLocationStrategy}.
    422     *
    423     * @param locator the {@code FileLocator}
    424     * @return the {@code FileLocationStrategy} for this {@code FileLocator}
    425     */
    426    static FileLocationStrategy getLocationStrategy(final FileLocator locator) {
    427        return locator != null ? ObjectUtils.getIfNull(locator.getLocationStrategy(), DEFAULT_LOCATION_STRATEGY) : DEFAULT_LOCATION_STRATEGY;
    428    }
    429
    430    /**
    431     * Creates the default location strategy. This method creates a combined location strategy as described in the comment
    432     * of the {@link #DEFAULT_LOCATION_STRATEGY} member field.
    433     *
    434     * @return the default {@code FileLocationStrategy}
    435     */
    436    private static FileLocationStrategy initDefaultLocationStrategy() {
    437        // @formatter:off
    438        final FileLocationStrategy[] subStrategies = {
    439                ProvidedURLLocationStrategy.INSTANCE,
    440                FileSystemLocationStrategy.INSTANCE,
    441                AbsoluteNameLocationStrategy.INSTANCE,
    442                BasePathLocationStrategy.INSTANCE,
    443                new HomeDirectoryLocationStrategy(true),
    444                new HomeDirectoryLocationStrategy(false),
    445                ClasspathLocationStrategy.INSTANCE};
    446        // @formatter:on
    447        return new CombinedLocationStrategy(Arrays.asList(subStrategies));
    448    }
    449
    450    /**
    451     * Returns a flag whether all components of the given {@code FileLocator} describing the referenced file are defined. In
    452     * order to reference a file, it is not necessary that all components are filled in (for instance, the URL alone is
    453     * sufficient). For some use cases however, it might be of interest to have different methods for accessing the
    454     * referenced file. Also, depending on the filled out properties, there is a subtle difference how the file is accessed:
    455     * If only the file name is set (and optionally the base path), each time the file is accessed a {@code locate()}
    456     * operation has to be performed to uniquely identify the file. If however the URL is determined once based on the other
    457     * components and stored in a fully defined {@code FileLocator}, it can be used directly to identify the file. If the
    458     * passed in {@code FileLocator} is <strong>null</strong>, result is <strong>false</strong>.
    459     *
    460     * @param locator the {@code FileLocator} to be checked (may be <strong>null</strong>)
    461     * @return a flag whether all components describing the referenced file are initialized
    462     */
    463    public static boolean isFullyInitialized(final FileLocator locator) {
    464        if (locator == null) {
    465            return false;
    466        }
    467        return locator.getBasePath() != null && locator.getFileName() != null && locator.getSourceURL() != null;
    468    }
    469
    470    /**
    471     * Checks whether the specified {@code FileLocator} contains enough information to locate a file. This is the case if a
    472     * file name or a URL is defined. If the passed in {@code FileLocator} is <strong>null</strong>, result is <strong>false</strong>.
    473     *
    474     * @param locator the {@code FileLocator} to check
    475     * @return a flag whether a file location is defined by this {@code FileLocator}
    476     */
    477    public static boolean isLocationDefined(final FileLocator locator) {
    478        return locator != null && (locator.getFileName() != null || locator.getSourceURL() != null);
    479    }
    480
    481    /**
    482     * Locates the provided {@code FileLocator}, returning a URL for accessing the referenced file. This method uses a
    483     * {@link FileLocationStrategy} to locate the file the passed in {@code FileLocator} points to. If the
    484     * {@code FileLocator} contains itself a {@code FileLocationStrategy}, it is used. Otherwise, the default
    485     * {@code FileLocationStrategy} is applied. The strategy is passed the locator and a {@code FileSystem}. The resulting
    486     * URL is returned. If the {@code FileLocator} is <strong>null</strong>, result is <strong>null</strong>.
    487     *
    488     * @param locator the {@code FileLocator} to be resolved
    489     * @return the URL pointing to the referenced file or <strong>null</strong> if the {@code FileLocator} could not be resolved
    490     * @see #DEFAULT_LOCATION_STRATEGY
    491     */
    492    public static URL locate(final FileLocator locator) {
    493        if (locator == null) {
    494            return null;
    495        }
    496
    497        return getLocationStrategy(locator).locate(getFileSystem(locator), locator);
    498    }
    499
    500    /**
    501     * Tries to locate the file referenced by the passed in {@code FileLocator}. If this fails, an exception is thrown. This
    502     * method works like {@link #locate(FileLocator)}; however, in case of a failed location attempt an exception is thrown.
    503     *
    504     * @param locator the {@code FileLocator} to be resolved
    505     * @return the URL pointing to the referenced file
    506     * @throws ConfigurationException if the file cannot be resolved
    507     */
    508    public static URL locateOrThrow(final FileLocator locator) throws ConfigurationException {
    509        final URL url = locate(locator);
    510        if (url == null) {
    511            throw new ConfigurationException("Could not locate: %s", locator);
    512        }
    513        return url;
    514    }
    515
    516    /**
    517     * Stores the specified {@code FileLocator} in the given map. With the {@link #fromMap(Map)} method a new
    518     * {@code FileLocator} with the same properties as the original one can be created.
    519     *
    520     * @param locator the {@code FileLocator} to be stored
    521     * @param map the map in which to store the {@code FileLocator} (must not be <strong>null</strong>)
    522     * @throws IllegalArgumentException if the map is <strong>null</strong>
    523     */
    524    public static void put(final FileLocator locator, final Map<String, Object> map) {
    525        if (map == null) {
    526            throw new IllegalArgumentException("Map must not be null!");
    527        }
    528
    529        if (locator != null) {
    530            map.put(PROP_BASE_PATH, locator.getBasePath());
    531            map.put(PROP_ENCODING, locator.getEncoding());
    532            map.put(PROP_FILE_NAME, locator.getFileName());
    533            map.put(PROP_FILE_SYSTEM, locator.getFileSystem());
    534            map.put(PROP_SOURCE_URL, locator.getSourceURL());
    535            map.put(PROP_STRATEGY, locator.getLocationStrategy());
    536        }
    537    }
    538
    539    /**
    540     * Convert the specified file into an URL. This method is equivalent to file.toURI().toURL(). It was used to work around
    541     * a bug in the JDK preventing the transformation of a file into an URL if the file name contains a '#' character. See
    542     * the issue CONFIGURATION-300 for more details. Now that we switched to JDK 1.4 we can directly use
    543     * file.toURI().toURL().
    544     *
    545     * @param file the file to be converted into an URL
    546     * @return a URL
    547     * @throws MalformedURLException If the file protocol handler is not found (should not happen) or if an error occurred
    548     *         while constructing the URL
    549     */
    550    static URL toURL(final File file) throws MalformedURLException {
    551        return file.toURI().toURL();
    552    }
    553
    554    /**
    555     * Private constructor so that no instances can be created.
    556     */
    557    private FileLocatorUtils() {
    558    }
    559
    560}