001: /*
002: * Path.java February 2001
003: *
004: * Copyright (C) 2001, Niall Gallagher <niallg@users.sf.net>
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation.
009: *
010: * This library is distributed in the hope that it will be useful,
011: * but WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
013: * GNU Lesser General Public License for more details.
014: *
015: * You should have received a copy of the GNU Lesser General
016: * Public License along with this library; if not, write to the
017: * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
018: * Boston, MA 02111-1307 USA
019: */
020:
021: package simple.util.net;
022:
023: /**
024: * The <code>Path</code> represents the path part of a URI. This provides
025: * the various components of the URI path to the user. The normalization
026: * of the path is the conversion of the path given into it's actual path by
027: * removing the references to the parent directorys and to the current dir.
028: * <p>
029: * If the path that this represents is <code>/usr/bin/../etc/./README</code>
030: * then the actual path, normalized, is <code>/usr/etc/README</code>. This
031: * will also provide a localization from the path. The localization is there
032: * if a second extension exists within the path, for example if the path was
033: * <code>/usr/bin/file.ext.ext</code>. The second extension will be parsed so
034: * that all the characters before the first underscore character, '_', will
035: * define the language and all the characters after the first underscore will
036: * define the country, for example <code>index.en_US.html</code> will have
037: * the language en and the country would be US. This should only support two
038: * character codes for both language and country.
039: *
040: * @author Niall Gallagher
041: *
042: * @see simple.util.parse.PathParser
043: */
044: public interface Path {
045:
046: /**
047: * This will return the language that this path has taken
048: * from the locale of the path. For example a file name of
049: * <code>file.en_US.extension</code> produces a language
050: * of <code>en</code>. This will return null if there was
051: * no language information within the path.
052: *
053: * @return returns the locale language this path contains
054: */
055: public String getLanguage();
056:
057: /**
058: * This will return the country that this path has taken
059: * from the locale of the path. For example a file name of
060: * <code>file.en_US.extension</code> produces a country
061: * of <code>US</code>. This will return null if there was
062: * no country information within the path.
063: *
064: * @return returns the locale country this path contains
065: */
066: public String getCountry();
067:
068: /**
069: * This will return the extension that the file name contains.
070: * For example a file name <code>file.en_US.extension</code>
071: * will produce an extension of <code>extension</code>. This
072: * will return null if the path contains no file extension.
073: *
074: * @return this will return the extension this path contains
075: */
076: public String getExtension();
077:
078: /**
079: * This will return the full name of the file without the path.
080: * As regargs the definition of the path in RFC 2396 the name
081: * would be considered the last path segment. So if the path
082: * was <code>/usr/README</code> the name is <code>README</code>.
083: * Also for directorys the name of the directory in the last
084: * path segment is returned. This returns the name without any
085: * of the path parameters. As RFC 2396 defines the path to have
086: * path parameters after the path segments.
087: *
088: * @return this will return the name of the file in the path
089: */
090: public String getName();
091:
092: /**
093: * This will return the normalized path. The normalized path is
094: * the path without any references to its parent or itself. So
095: * if the path to be parsed is <code>/usr/../etc/./</code> the
096: * path is <code>/etc/</code>. If the path that this represents
097: * is a path with an immediate back reference then this will
098: * return null. This is the path with all its information even
099: * the parameter information if it was defined in the path.
100: *
101: * @return this returns the normalize path without
102: * <code>../</code> or <code>./</code>
103: */
104: public String getPath();
105:
106: /**
107: * This method is used to break the path into individual parts
108: * called segments, see RFC 2396. This can be used as an easy
109: * way to compare paths and to examine the directory tree that
110: * the path points to. For example, if an path was broken from
111: * the string <code>/usr/bin/../etc</code> then the segments
112: * returned would be <code>usr</code> and <code>etc</code> as
113: * the path is normalized before the segments are extracted.
114: *
115: * @return return all the path segments within the directory
116: */
117: public String[] getSegments();
118:
119: /**
120: * This will return the highest directory that exists within
121: * the path. This is used to that files within the same path
122: * can be acquired. An example of that this would do given
123: * the path <code>/pub/./bin/README</code> would be to return
124: * the highest directory path <code>/pub/bin/</code>. The "/"
125: * character will allways be the last character in the path.
126: *
127: * @return this method will return the highest directory
128: */
129: public String getDirectory();
130:
131: /**
132: * This will return the path as it is relative to the issued
133: * path. This in effect will chop the start of this path if
134: * it's start matches the highest directory of the given path
135: * as of <code>getDirectory</code>. This is useful if paths
136: * that are relative to a specific location are required. To
137: * illustrate what this method will do the following example
138: * is provided. If this object represented the path string
139: * <code>/usr/share/rfc/rfc2396.txt</code> and the issued
140: * path was <code>/usr/share/text.txt</code> then this will
141: * return the path string <code>/rfc/rfc2396.txt</code>.
142: *
143: * @param path the path prefix to acquire a relative path
144: *
145: * @return returns a path relative to the one it is given
146: * otherwize this method will return null
147: */
148: public String getRelative(String path);
149:
150: /**
151: * This will return the normalized path. The normalized path is
152: * the path without any references to its parent or itself. So
153: * if the path to be parsed is <code>/usr/../etc/./</code> the
154: * path is <code>/etc/</code>. If the path that this represents
155: * is a path with an immediate back reference then this will
156: * return null. This is the path with all its information even
157: * the parameter information if it was defined in the path.
158: *
159: * @return this returns the normalize path without
160: * <code>../</code> or <code>./</code>
161: */
162: public String toString();
163: }
|