View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *      http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17  package org.apache.commons.vfs;
    18
    19  /***
    20   * Represents a file name.  File names are immutable, and work correctly as
    21   * keys in hash tables.
    22   *
    23   * @author <a href="mailto:adammurdoch@apache.org">Adam Murdoch</a>
    24   * @version $Revision: 480428 $ $Date: 2006-11-29 07:15:24 +0100 (Mi, 29 Nov 2006) $
    25   * @see FileObject
    26   */
    27  public interface FileName extends Comparable
    28  {
    29      /***
    30       * The separator character used in file paths.
    31       */
    32      public final char SEPARATOR_CHAR = '/';
    33
    34      /***
    35       * The separator used in file paths.
    36       */
    37      public final String SEPARATOR = "/";
    38
    39      /***
    40       * The absolute path of the root of a file system.
    41       */
    42      public final String ROOT_PATH = "/";
    43
    44      /***
    45       * Returns the base name of this file.  The base name is the last element
    46       * of the file name.  For example the base name of
    47       * <code>/somefolder/somefile</code> is <code>somefile</code>.
    48       * <p/>
    49       * <p>The root file of a file system has an empty base name.
    50       *
    51       * @return The base name.  Never returns null.
    52       */
    53      public String getBaseName();
    54
    55      /***
    56       * Returns the absolute path of this file, within its file system.  This
    57       * path is normalised, so that <code>.</code> and <code>..</code> elements
    58       * have been removed.  Also, the path only contains <code>/</code> as its
    59       * separator character.  The path always starts with <code>/</code>
    60       * <p/>
    61       * <p>The root of a file system has <code>/</code> as its absolute path.
    62       *
    63       * @return The path.  Never returns null.
    64       */
    65      public String getPath();
    66
    67      /***
    68       * Returns the absolute path of this file, within its file system.  This
    69       * path is normalised, so that <code>.</code> and <code>..</code> elements
    70       * have been removed.  Also, the path only contains <code>/</code> as its
    71       * separator character.  The path always starts with <code>/</code>
    72       * <p/>
    73       * <p>The root of a file system has <code>/</code> as its absolute path.
    74       * <p/>
    75       * In contrast to {@link #getPath()} the path is decoded i.e. all %nn stuff
    76       * replaced by its character.
    77       *
    78       * @return The path.  Never returns null.
    79       * @throws FileSystemException if the path is not correctly encoded
    80       */
    81      public String getPathDecoded() throws FileSystemException;
    82
    83      /***
    84       * Returns the extension of this file name.
    85       *
    86       * @return The extension.  Returns an empty string if the name has no
    87       *         extension.
    88       */
    89      public String getExtension();
    90
    91      /***
    92       * Returns the depth of this file name, within its file system.  The depth
    93       * of the root of a file system is 0.  The depth of any other file is
    94       * 1 + the depth of its parent.
    95       */
    96      public int getDepth();
    97
    98      /***
    99       * Returns the URI scheme of this file.
    100      */
    101     public String getScheme();
    102
    103     /***
    104      * Returns the absolute URI of this file.
    105      */
    106     public String getURI();
    107
    108     /***
    109      * Returns the root URI of the file system this file belongs to.
    110      */
    111     public String getRootURI();
    112
    113     /***
    114      * find the root of the filesystem
    115      */
    116     public FileName getRoot();
    117
    118     /***
    119      * Returns the file name of the parent of this file.  The root of a
    120      * file system has no parent.
    121      *
    122      * @return A {@link FileName} object representing the parent name.  Returns
    123      *         null for the root of a file system.
    124      */
    125     public FileName getParent();
    126
    127     /***
    128      * Resolves a name, relative to this file name.  Equivalent to calling
    129      * <code>resolveName( path, NameScope.FILE_SYSTEM )</code>.
    130      *
    131      * @param name The name to resolve.
    132      * @return A {@link FileName} object representing the resolved file name.
    133      * @throws FileSystemException If the name is invalid.
    134      */
    135     // FileName resolveName(String name) throws FileSystemException;
    136
    137     /***
    138      * Resolves a name, relative to this file name.  Refer to {@link NameScope}
    139      * for a description of how names are resolved.
    140      *
    141      * @param name  The name to resolve.
    142      * @param scope The scope to use when resolving the name.
    143      * @return A {@link FileName} object representing the resolved file name.
    144      * @throws FileSystemException If the name is invalid.
    145      */
    146     // FileName resolveName(String name, NameScope scope)
    147     //     throws FileSystemException;
    148
    149     /***
    150      * Converts a file name to a relative name, relative to this file name.
    151      *
    152      * @param name The name to convert to a relative path.
    153      * @return The relative name.
    154      * @throws FileSystemException On error.
    155      */
    156     public String getRelativeName(FileName name) throws FileSystemException;
    157
    158     /***
    159      * Determines if another file name is an ancestor of this file name.
    160      */
    161     public boolean isAncestor(FileName ancestor);
    162
    163     /***
    164      * Determines if another file name is a descendent of this file name.
    165      */
    166     public boolean isDescendent(FileName descendent);
    167
    168     /***
    169      * Determines if another file name is a descendent of this file name.
    170      */
    171     public boolean isDescendent(FileName descendent, NameScope nameScope);
    172
    173     /***
    174      * Returns the requested or current type of this name. <br />
    175      * <p/>
    176      * The "requested" type is the one determined during resolving the name. <br/>
    177      * In this case the name is a {@link FileType#FOLDER} if it ends with an "/" else
    178      * it will be a {@link FileType#FILE}<br/>
    179      * </p>
    180      * <p/>
    181      * Once attached it will be changed to reflect the real type of this resource.
    182      * </p>
    183      *
    184      * @return {@link FileType#FOLDER} or {@link FileType#FILE}
    185      */
    186     public FileType getType();
    187
    188     /***
    189      * returns a "friendly path", this is a path without a password.<br />
    190      * This path can not be used to resolve the path again
    191      */
    192     public String getFriendlyURI();
    193 }