/*
 * 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.commons.configuration2.io;

import java.net.URL;

import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.builder.EqualsBuilder;
import org.apache.commons.lang3.builder.HashCodeBuilder;
import org.apache.commons.lang3.builder.ToStringBuilder;


A class describing the location of a file.


An instance of this class provides information for locating and accessing a
file. The file location can be defined


as a URL; this identifies a file in a unique way
as a combination of base path and file name; if this variant is used,
there may be an additional location step required in order to identify the
referenced file (for instance, the file name may be interpreted as the name
of a resource to be loaded from class path).

 In addition, other properties are available which are also needed for loading or saving a file, like the underlying FileSystem. The encoding to be used when accessing the represented data is also part of the data contained in an instance; if no encoding is set explicitly, the platform's default encoding is used. 
 Instances of this class are immutable and thus can be safely shared between arbitrary components. FileHandler also uses an instance to reference the associated file. Instances are created using a builder. FileLocatorUtils offers convenience methods for obtaining such a builder. 
Since:
2.0/**
 * <p>
 * A class describing the location of a file.
 * </p>
 * <p>
 * An instance of this class provides information for locating and accessing a
 * file. The file location can be defined
 * </p>
 * <ul>
 * <li>as a URL; this identifies a file in a unique way</li>
 * <li>as a combination of base path and file name; if this variant is used,
 * there may be an additional location step required in order to identify the
 * referenced file (for instance, the file name may be interpreted as the name
 * of a resource to be loaded from class path).</li>
 * </ul>
 * <p>
 * In addition, other properties are available which are also needed for loading
 * or saving a file, like the underlying {@link FileSystem}. The encoding to be
 * used when accessing the represented data is also part of the data contained
 * in an instance; if no encoding is set explicitly, the platform's default
 * encoding is used.
 * <p>
 * Instances of this class are immutable and thus can be safely shared between
 * arbitrary components. {@link FileHandler} also uses an instance to reference
 * the associated file. Instances are created using a <em>builder</em>.
 * {@link FileLocatorUtils} offers convenience methods for obtaining such a
 * builder.
 * </p>
 *
 * @since 2.0
 */
public final class FileLocator
{
    
The file name. /** The file name. */
    private final String fileName;

    
The base path. /** The base path. */
    private final String basePath;

    
The source URL. /** The source URL. */
    private final URL sourceURL;

    
The encoding. /** The encoding. */
    private final String encoding;

    
The file system. /** The file system. */
    private final FileSystem fileSystem;

    
The file location strategy. /** The file location strategy. */
    private final FileLocationStrategy locationStrategy;

    
Creates a new instance of FileLocatorImpl and initializes it from the given builder instance 
Params:
builder – the builder/**
     * Creates a new instance of {@code FileLocatorImpl} and initializes it from
     * the given builder instance
     *
     * @param builder the builder
     */
    public FileLocator(final FileLocatorBuilder builder)
    {
        fileName = builder.fileName;
        basePath = builder.basePath;
        sourceURL = builder.sourceURL;
        encoding = builder.encoding;
        fileSystem = builder.fileSystem;
        locationStrategy = builder.locationStrategy;
    }

    
Returns the file name stored in this locator or null if it is
undefined.
Returns:
the file name/**
     * Returns the file name stored in this locator or <b>null</b> if it is
     * undefined.
     *
     * @return the file name
     */
    public String getFileName()
    {
        return fileName;
    }

    
Returns the base path stored in this locator or null if it is
undefined.
Returns:
the base path/**
     * Returns the base path stored in this locator or <b>null</b> if it is
     * undefined.
     *
     * @return the base path
     */
    public String getBasePath()
    {
        return basePath;
    }

    
Returns the URL pointing to the referenced source file or null if
it is undefined.
Returns:
the source URL/**
     * Returns the URL pointing to the referenced source file or <b>null</b> if
     * it is undefined.
     *
     * @return the source URL
     */
    public URL getSourceURL()
    {
        return sourceURL;
    }

    
Returns the encoding stored in this locator or null if it is
undefined.
Returns:
the encoding/**
     * Returns the encoding stored in this locator or <b>null</b> if it is
     * undefined.
     *
     * @return the encoding
     */
    public String getEncoding()
    {
        return encoding;
    }

    
Returns the FileSystem to be used for accessing the file referenced by this locator or null if it is undefined.
Returns:
the FileSystem/**
     * Returns the {@code FileSystem} to be used for accessing the file
     * referenced by this locator or <b>null</b> if it is undefined.
     *
     * @return the {@code FileSystem}
     */
    public FileSystem getFileSystem()
    {
        return fileSystem;
    }

    
Returns the FileLocationStrategy to be used for locating the referenced file. If no specific FileLocationStrategy has been set, result is null. This means that the default strategy should
be used.
Returns:
the FileLocationStrategy to be used/**
     * Returns the {@code FileLocationStrategy} to be used for locating the
     * referenced file. If no specific {@code FileLocationStrategy} has been
     * set, result is <b>null</b>. This means that the default strategy should
     * be used.
     *
     * @return the {@code FileLocationStrategy} to be used
     */
    public FileLocationStrategy getLocationStrategy()
    {
        return locationStrategy;
    }

    
Returns a hash code for this object.
Returns:
a hash code for this object/**
     * Returns a hash code for this object.
     *
     * @return a hash code for this object
     */
    @Override
    public int hashCode()
    {
        return new HashCodeBuilder().append(getFileName())
                .append(getBasePath()).append(sourceURLAsString())
                .append(getEncoding()).append(getFileSystem())
                .append(getLocationStrategy()).toHashCode();
    }

    
Compares this object with another one. Two instances of FileLocatorImpl are considered equal if all of their properties are equal. 
Params:
obj – the object to compare to
Returns:
a flag whether these objects are equal/**
     * Compares this object with another one. Two instances of
     * {@code FileLocatorImpl} are considered equal if all of their properties
     * are equal.
     *
     * @param obj the object to compare to
     * @return a flag whether these objects are equal
     */
    @Override
    public boolean equals(final Object obj)
    {
        if (this == obj)
        {
            return true;
        }
        if (!(obj instanceof FileLocator))
        {
            return false;
        }

        final FileLocator c = (FileLocator) obj;
        return new EqualsBuilder().append(getFileName(), c.getFileName())
                .append(getBasePath(), c.getBasePath())
                .append(sourceURLAsString(), c.sourceURLAsString())
                .append(getEncoding(), c.getEncoding())
                .append(getFileSystem(), c.getFileSystem())
                .append(getLocationStrategy(), c.getLocationStrategy())
                .isEquals();
    }

    
Returns a string representation of this object. This string contains the
values of all properties.
Returns:
a string for this object/**
     * Returns a string representation of this object. This string contains the
     * values of all properties.
     *
     * @return a string for this object
     */
    @Override
    public String toString()
    {
        return new ToStringBuilder(this).append("fileName", getFileName())
                .append("basePath", getBasePath())
                .append("sourceURL", sourceURLAsString())
                .append("encoding", getEncoding())
                .append("fileSystem", getFileSystem())
                .append("locationStrategy", getLocationStrategy()).toString();
    }

    
Returns the source URL as a string. Result is never null. Comparisons are
done on this string to avoid blocking network calls.
Returns:
the source URL as a string (not null)/**
     * Returns the source URL as a string. Result is never null. Comparisons are
     * done on this string to avoid blocking network calls.
     *
     * @return the source URL as a string (not null)
     */
    private String sourceURLAsString()
    {
        return sourceURL != null ? sourceURL.toExternalForm()
                : StringUtils.EMPTY;
    }

    
A typical builder implementation for creating FileLocator objects. An instance of this class is returned by the fileLocator() method of {link FileLocatorUtils}. It can be used to define the various components of the FileLocator object. By calling create() the new immutable FileLocator instance is created. /**
     * A typical <em>builder</em> implementation for creating
     * {@code FileLocator} objects. An instance of this class is returned by the
     * {@code fileLocator()} method of {link FileLocatorUtils}. It can be used
     * to define the various components of the {@code FileLocator} object. By
     * calling {@code create()} the new immutable {@code FileLocator} instance
     * is created.
     */
    public static final class FileLocatorBuilder
    {
        
The file name. /** The file name. */
        private String fileName;

        
The base path. /** The base path. */
        private String basePath;

        
The source URL. /** The source URL. */
        private URL sourceURL;

        
The encoding. /** The encoding. */
        private String encoding;

        
The file system. /** The file system. */
        private FileSystem fileSystem;

        
The location strategy. /** The location strategy. */
        private FileLocationStrategy locationStrategy;

        
Creates a new instance of FileLocatorBuilder and initializes the builder's properties from the passed in FileLocator object. 
Params:
src – the source FileLocator (may be null)/**
         * Creates a new instance of {@code FileLocatorBuilder} and initializes
         * the builder's properties from the passed in {@code FileLocator}
         * object.
         *
         * @param src the source {@code FileLocator} (may be <b>null</b>)
         */
        FileLocatorBuilder(final FileLocator src)
        {
            if (src != null)
            {
                initBuilder(src);
            }
        }

        
Specifies the encoding of the new FileLocator. 
Params:
enc – the encoding
Returns:
a reference to this builder for method chaining/**
         * Specifies the encoding of the new {@code FileLocator}.
         *
         * @param enc the encoding
         * @return a reference to this builder for method chaining
         */
        public FileLocatorBuilder encoding(final String enc)
        {
            encoding = enc;
            return this;
        }

        
Specifies the FileSystem of the new FileLocator. 
Params:
fs – the FileSystem
Returns:
a reference to this builder for method chaining/**
         * Specifies the {@code FileSystem} of the new {@code FileLocator}.
         *
         * @param fs the {@code FileSystem}
         * @return a reference to this builder for method chaining
         */
        public FileLocatorBuilder fileSystem(final FileSystem fs)
        {
            fileSystem = fs;
            return this;
        }

        
Specifies the base path of the new FileLocator. 
Params:
path – the base path
Returns:
a reference to this builder for method chaining/**
         * Specifies the base path of the new {@code FileLocator}.
         *
         * @param path the base path
         * @return a reference to this builder for method chaining
         */
        public FileLocatorBuilder basePath(final String path)
        {
            basePath = path;
            return this;
        }

        
Specifies the file name of the new FileLocator. 
Params:
name – the file name
Returns:
a reference to this builder for method chaining/**
         * Specifies the file name of the new {@code FileLocator}.
         *
         * @param name the file name
         * @return a reference to this builder for method chaining
         */
        public FileLocatorBuilder fileName(final String name)
        {
            fileName = name;
            return this;
        }

        
Specifies the source URL of the new FileLocator. 
Params:
url – the source URL
Returns:
a reference to this builder for method chaining/**
         * Specifies the source URL of the new {@code FileLocator}.
         *
         * @param url the source URL
         * @return a reference to this builder for method chaining
         */
        public FileLocatorBuilder sourceURL(final URL url)
        {
            sourceURL = url;
            return this;
        }

        
Specifies the FileLocationStrategy to be used when the referenced file is to be located. 
Params:
strategy – the FileLocationStrategy
Returns:
a reference to this builder for method chaining/**
         * Specifies the {@code FileLocationStrategy} to be used when the
         * referenced file is to be located.
         *
         * @param strategy the {@code FileLocationStrategy}
         * @return a reference to this builder for method chaining
         */
        public FileLocatorBuilder locationStrategy(final FileLocationStrategy strategy)
        {
            locationStrategy = strategy;
            return this;
        }

        
Creates a new immutable FileLocatorImpl object based on the properties set so far for this builder. 
Returns:
the newly created FileLocator object/**
         * Creates a new immutable {@code FileLocatorImpl} object based on the
         * properties set so far for this builder.
         *
         * @return the newly created {@code FileLocator} object
         */
        public FileLocator create()
        {
            return new FileLocator(this);
        }

        
Initializes the properties of this builder from the passed in locator
object.
Params:
src – the source FileLocator/**
         * Initializes the properties of this builder from the passed in locator
         * object.
         *
         * @param src the source {@code FileLocator}
         */
        private void initBuilder(final FileLocator src)
        {
            basePath = src.getBasePath();
            fileName = src.getFileName();
            sourceURL = src.getSourceURL();
            encoding = src.getEncoding();
            fileSystem = src.getFileSystem();
            locationStrategy = src.getLocationStrategy();
        }
    }
}