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