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