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