    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.io.InputStream;
    021import java.io.OutputStream;
    022import java.net.MalformedURLException;
    023import java.net.URL;
    024
    025import org.apache.commons.configuration2.ex.ConfigurationException;
    026
    027/**
    028 * Abstract layer to allow various types of file systems.
    029 *
    030 * @since 1.7
    031 */
    032public abstract class FileSystem {
    033    /** Constant for the default logger. */
    034    private static final ConfigurationLogger DEFAULT_LOG = ConfigurationLogger.newDummyLogger();
    035
    036    /** The Logger. */
    037    private volatile ConfigurationLogger log;
    038
    039    /** FileSystem options provider. */
    040    private volatile FileOptionsProvider optionsProvider;
    041
    042    /**
    043     * Constructs a new instance.
    044     */
    045    public FileSystem() {
    046        // empty
    047    }
    048
    049    /**
    050     * Gets the base path of the given path, for example a directory for a file.
    051     *
    052     * @param path the source path.
    053     * @return the base path.
    054     */
    055    public abstract String getBasePath(String path);
    056
    057    /**
    058     * Gets the file name of the given path.
    059     *
    060     * @param path the source path.
    061     * @return the file name.
    062     */
    063    public abstract String getFileName(String path);
    064
    065    /**
    066     * Gets the FileSystem options provider.
    067     *
    068     * @return the FileSystem options provider.
    069     */
    070    public FileOptionsProvider getFileOptionsProvider() {
    071        return this.optionsProvider;
    072    }
    073
    074    /**
    075     * Gets an input stream for a URL.
    076     *
    077     * @param url the source URL.
    078     * @return an input stream.
    079     * @throws ConfigurationException if an problem occurs getting the input stream.
    080     */
    081    public abstract InputStream getInputStream(URL url) throws ConfigurationException;
    082
    083    /**
    084     * Not abstract for binary compatibility.
    085     *
    086     * @param url TODO
    087     * @param urlConnectionOptions Ignored.
    088     * @return TODO
    089     * @throws ConfigurationException TODO
    090     * @since 2.8.0
    091     */
    092    public InputStream getInputStream(final URL url, final URLConnectionOptions urlConnectionOptions) throws ConfigurationException {
    093        return getInputStream(url);
    094    }
    095
    096    /**
    097     * Gets the logger used by this FileSystem.
    098     *
    099     * @return the logger
    100     */
    101    public ConfigurationLogger getLogger() {
    102        final ConfigurationLogger result = log;
    103        return result != null ? result : DEFAULT_LOG;
    104    }
    105
    106    /**
    107     * Gets an output stream for a File.
    108     *
    109     * @param file the source File.
    110     * @return an output stream.
    111     * @throws ConfigurationException if an problem occurs getting the output stream.
    112     */
    113    public abstract OutputStream getOutputStream(File file) throws ConfigurationException;
    114
    115    /**
    116     * Gets an output stream for a URL.
    117     *
    118     * @param url the source URL.
    119     * @return an output stream.
    120     * @throws ConfigurationException if an problem occurs getting the output stream.
    121     */
    122    public abstract OutputStream getOutputStream(URL url) throws ConfigurationException;
    123
    124    /**
    125     * Gets a path string for the given input where some values may be null.
    126     * <p>
    127     * The implementation decides on which argument take precedence.
    128     * </p>
    129     *
    130     * @param file A file.
    131     * @param url A URL.
    132     * @param basePath A base path string.
    133     * @param fileName A file name.
    134     * @return A path string.
    135     */
    136    public abstract String getPath(File file, URL url, String basePath, String fileName);
    137
    138    /**
    139     * Gets a URL for a base path and file name.
    140     *
    141     * @param basePath The base path.
    142     * @param fileName The file name.
    143     * @return a URL.
    144     * @throws MalformedURLException if a problem occurs creating the URL.
    145     */
    146    public abstract URL getURL(String basePath, String fileName) throws MalformedURLException;
    147
    148    /**
    149     * Locates a URL for a base path and file name.
    150     *
    151     * @param basePath The base path.
    152     * @param fileName The file name.
    153     * @return a URL.
    154     */
    155    public abstract URL locateFromURL(String basePath, String fileName);
    156
    157    /**
    158     * Sets the FileOptionsProvider
    159     *
    160     * @param provider The FileOptionsProvider
    161     */
    162    public void setFileOptionsProvider(final FileOptionsProvider provider) {
    163        this.optionsProvider = provider;
    164    }
    165
    166    /**
    167     * Sets the logger to be used by this FileSystem. This method makes it possible for clients to exactly control
    168     * logging behavior. Per default a logger is set that will ignore all log messages. Derived classes that want to enable
    169     * logging should call this method during their initialization with the logger to be used. Passing in a <strong>null</strong>
    170     * argument disables logging.
    171     *
    172     * @param log the new logger
    173     */
    174    public void setLogger(final ConfigurationLogger log) {
    175        this.log = log;
    176    }
    177}