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.vfs2; 018 019/** 020 * Represents a file name. File names are immutable, and work correctly as keys in hash tables. 021 * 022 * @see FileObject 023 */ 024public interface FileName extends Comparable<FileName> { 025 /** 026 * The separator character used in file paths. 027 */ 028 char SEPARATOR_CHAR = '/'; 029 030 /** 031 * The separator used in file paths. 032 */ 033 String SEPARATOR = "/"; 034 035 /** 036 * The absolute path of the root of a file system. 037 */ 038 String ROOT_PATH = "/"; 039 040 /** 041 * Returns the base name of this file. The base name is the last element of the file name. For example the base name 042 * of {@code /somefolder/somefile} is {@code somefile}. 043 * <p> 044 * The root file of a file system has an empty base name. 045 * </p> 046 * 047 * @return The base name. Never returns null. 048 */ 049 String getBaseName(); 050 051 /** 052 * Returns the absolute path of this file, within its file system. This path is normalized, so that {@code .} and 053 * {@code ..} elements have been removed. Also, the path only contains {@code /} as its separator character. The 054 * path always starts with {@code /} 055 * <p> 056 * The root of a file system has {@code /} as its absolute path. 057 * </p> 058 * 059 * @return The path. Never returns null. 060 */ 061 String getPath(); 062 063 /** 064 * Returns the absolute path of this file, within its file system. This path is normalized, so that {@code .} and 065 * {@code ..} elements have been removed. Also, the path only contains {@code /} as its separator character. The 066 * path always starts with {@code /} 067 * <p> 068 * The root of a file system has {@code /} as its absolute path. 069 * </p> 070 * <p> 071 * In contrast to {@link #getPath()} the path is decoded i.e. all %nn stuff replaced by its character. 072 * </p> 073 * 074 * @return The path. Never returns null. 075 * @throws FileSystemException if the path is not correctly encoded 076 */ 077 String getPathDecoded() throws FileSystemException; 078 079 /** 080 * Returns the extension of this file name. 081 * 082 * @return The extension. Returns an empty string if the name has no extension. 083 */ 084 String getExtension(); 085 086 /** 087 * Returns the depth of this file name, within its file system. The depth of the root of a file system is 0. The 088 * depth of any other file is 1 + the depth of its parent. 089 * 090 * @return The depth of this file name. 091 */ 092 int getDepth(); 093 094 /** 095 * Returns the URI scheme of this file. 096 * 097 * @return The URI scheme of this file. 098 */ 099 String getScheme(); 100 101 /** 102 * Returns the absolute URI of this file. 103 * 104 * @return the absolute URI of this file. 105 */ 106 String getURI(); 107 108 /** 109 * Returns the root URI of the file system this file belongs to. 110 * 111 * @return the root URI. 112 */ 113 String getRootURI(); 114 115 /** 116 * Finds the root of the file system. 117 * 118 * @return the file system root. 119 */ 120 FileName getRoot(); 121 122 /** 123 * Returns the file name of the parent of this file. The root of a file system has no parent. 124 * 125 * @return A {@link FileName} object representing the parent name. Returns null for the root of a file system. 126 */ 127 FileName getParent(); 128 129 /** 130 * Resolves a name, relative to this file name. Equivalent to calling 131 * {@code resolveName( path, NameScope.FILE_SYSTEM )}. 132 * 133 * @param name The name to resolve. 134 * @return A {@link FileName} object representing the resolved file name. 135 * @throws FileSystemException If the name is invalid. 136 */ 137 // FileName resolveName(String name) throws FileSystemException; 138 139 /** 140 * Resolves a name, relative to this file name. Refer to {@link NameScope} for a description of how names are 141 * resolved. 142 * 143 * @param name The name to resolve. 144 * @param scope The scope to use when resolving the name. 145 * @return A {@link FileName} object representing the resolved file name. 146 * @throws FileSystemException If the name is invalid. 147 */ 148 // FileName resolveName(String name, NameScope scope) 149 // throws FileSystemException; 150 151 /** 152 * Converts a file name to a relative name, relative to this file name. 153 * 154 * @param name The name to convert to a relative path. 155 * @return The relative name. 156 * @throws FileSystemException On error. 157 */ 158 String getRelativeName(FileName name) throws FileSystemException; 159 160 /** 161 * Determines if another file name is an ancestor of this file name. 162 * 163 * @param ancestor The FileName to check. 164 * @return true if another file name is an ancestor of this file name. 165 */ 166 boolean isAncestor(FileName ancestor); 167 168 /** 169 * Determines if another file name is a descendent of this file name. 170 * 171 * @param descendent the FileName to check. 172 * @return true if the other FileName is a descendent of this file name. 173 */ 174 boolean isDescendent(FileName descendent); 175 176 /** 177 * Determines if another file name is a descendent of this file name. 178 * 179 * @param descendent the FileName to check. 180 * @param nameScope the NameScope of the FileName. 181 * @return true if the other FileName is a descendent of this file name. 182 */ 183 boolean isDescendent(FileName descendent, NameScope nameScope); 184 185 /** 186 * Checks if this file name is a name for a regular file. 187 * 188 * @return true if this file name is a name for a regular file. 189 * @throws FileSystemException if an error occurs. 190 * @see #getType() 191 * @see FileType#FILE 192 * @since 2.1 193 */ 194 boolean isFile() throws FileSystemException; 195 196 /** 197 * Returns the requested or current type of this name. 198 * <p> 199 * The "requested" type is the one determined during resolving the name. In this case the name is a 200 * {@link FileType#FOLDER} if it ends with an "/" else it will be a {@link FileType#FILE}. 201 * <p> 202 * Once attached it will be changed to reflect the real type of this resource. 203 * 204 * @return {@link FileType#FOLDER} or {@link FileType#FILE} 205 */ 206 FileType getType(); 207 208 /** 209 * Returns a "friendly path", this is a path without a password. 210 * <p> 211 * This path can not be used to resolve the path again. 212 * 213 * @return the friendly URI as a String. 214 */ 215 String getFriendlyURI(); 216}