| /* |
| * 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.vfs2; |
| |
| /** |
| * Represents a file name. File names are immutable, and work correctly as |
| * keys in hash tables. |
| * |
| * @see FileObject |
| */ |
| public interface FileName extends Comparable<FileName> |
| { |
| /** |
| * The separator character used in file paths. |
| */ |
| char SEPARATOR_CHAR = '/'; |
| |
| /** |
| * The separator used in file paths. |
| */ |
| String SEPARATOR = "/"; |
| |
| /** |
| * The absolute path of the root of a file system. |
| */ |
| String ROOT_PATH = "/"; |
| |
| /** |
| * Returns the base name of this file. The base name is the last element |
| * of the file name. For example the base name of |
| * {@code /somefolder/somefile} is {@code somefile}. |
| * <p> |
| * The root file of a file system has an empty base name. |
| * </p> |
| * |
| * @return The base name. Never returns null. |
| */ |
| String getBaseName(); |
| |
| /** |
| * Returns the absolute path of this file, within its file system. This |
| * path is normalized, so that {@code .} and {@code ..} elements |
| * have been removed. Also, the path only contains {@code /} as its |
| * separator character. The path always starts with {@code /} |
| * <p> |
| * The root of a file system has {@code /} as its absolute path. |
| * </p> |
| * |
| * @return The path. Never returns null. |
| */ |
| String getPath(); |
| |
| /** |
| * Returns the absolute path of this file, within its file system. This |
| * path is normalized, so that {@code .} and {@code ..} elements |
| * have been removed. Also, the path only contains {@code /} as its |
| * separator character. The path always starts with {@code /} |
| * <p> |
| * The root of a file system has {@code /} as its absolute path. |
| * </p> |
| * <p> |
| * In contrast to {@link #getPath()} the path is decoded i.e. all %nn stuff |
| * replaced by its character. |
| * </p> |
| * |
| * @return The path. Never returns null. |
| * @throws FileSystemException if the path is not correctly encoded |
| */ |
| String getPathDecoded() throws FileSystemException; |
| |
| /** |
| * Returns the extension of this file name. |
| * |
| * @return The extension. Returns an empty string if the name has no |
| * extension. |
| */ |
| String getExtension(); |
| |
| /** |
| * Returns the depth of this file name, within its file system. The depth |
| * of the root of a file system is 0. The depth of any other file is |
| * 1 + the depth of its parent. |
| * |
| * @return The depth of this file name. |
| */ |
| int getDepth(); |
| |
| /** |
| * Returns the URI scheme of this file. |
| * |
| * @return The URI scheme of this file. |
| */ |
| String getScheme(); |
| |
| /** |
| * Returns the absolute URI of this file. |
| * |
| * @return the absolute URI of this file. |
| */ |
| String getURI(); |
| |
| /** |
| * Returns the root URI of the file system this file belongs to. |
| * |
| * @return the root URI. |
| */ |
| String getRootURI(); |
| |
| /** |
| * Finds the root of the file system. |
| * |
| * @return the file system root. |
| */ |
| FileName getRoot(); |
| |
| /** |
| * Returns the file name of the parent of this file. The root of a |
| * file system has no parent. |
| * |
| * @return A {@link FileName} object representing the parent name. Returns |
| * null for the root of a file system. |
| */ |
| FileName getParent(); |
| |
| /** |
| * Resolves a name, relative to this file name. Equivalent to calling |
| * {@code resolveName( path, NameScope.FILE_SYSTEM )}. |
| * |
| * @param name The name to resolve. |
| * @return A {@link FileName} object representing the resolved file name. |
| * @throws FileSystemException If the name is invalid. |
| */ |
| // FileName resolveName(String name) throws FileSystemException; |
| |
| /** |
| * Resolves a name, relative to this file name. Refer to {@link NameScope} |
| * for a description of how names are resolved. |
| * |
| * @param name The name to resolve. |
| * @param scope The scope to use when resolving the name. |
| * @return A {@link FileName} object representing the resolved file name. |
| * @throws FileSystemException If the name is invalid. |
| */ |
| // FileName resolveName(String name, NameScope scope) |
| // throws FileSystemException; |
| |
| /** |
| * Converts a file name to a relative name, relative to this file name. |
| * |
| * @param name The name to convert to a relative path. |
| * @return The relative name. |
| * @throws FileSystemException On error. |
| */ |
| String getRelativeName(FileName name) throws FileSystemException; |
| |
| /** |
| * Determines if another file name is an ancestor of this file name. |
| * |
| * @param ancestor The FileName to check. |
| * @return true if another file name is an ancestor of this file name. |
| */ |
| boolean isAncestor(FileName ancestor); |
| |
| /** |
| * Determines if another file name is a descendent of this file name. |
| * |
| * @param descendent the FileName to check. |
| * @return true if the other FileName is a descendent of this file name. |
| */ |
| boolean isDescendent(FileName descendent); |
| |
| /** |
| * Determines if another file name is a descendent of this file name. |
| * |
| * @param descendent the FileName to check. |
| * @param nameScope the NameScope of the FileName. |
| * @return true if the other FileName is a descendent of this file name. |
| */ |
| boolean isDescendent(FileName descendent, NameScope nameScope); |
| |
| /** |
| * Checks if this file name is a name for a regular file. |
| * |
| * @return true if this file name is a name for a regular file. |
| * @throws FileSystemException if an error occurs. |
| * @see #getType() |
| * @see FileType#FILE |
| * @since 2.1 |
| */ |
| boolean isFile() throws FileSystemException; |
| |
| /** |
| * Returns the requested or current type of this name. |
| * <p> |
| * The "requested" type is the one determined during resolving the name. |
| * In this case the name is a {@link FileType#FOLDER} if it ends with an "/" else |
| * it will be a {@link FileType#FILE}. |
| * <p> |
| * Once attached it will be changed to reflect the real type of this resource. |
| * |
| * @return {@link FileType#FOLDER} or {@link FileType#FILE} |
| */ |
| FileType getType(); |
| |
| /** |
| * Returns a "friendly path", this is a path without a password. |
| * <p> |
| * This path can not be used to resolve the path again. |
| * |
| * @return the friendly URI as a String. |
| */ |
| String getFriendlyURI(); |
| } |