001: /*
002: * URI.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: import java.util.Enumeration;
024:
025: /**
026: * The <code>URI</code> interface is used to represent a generic
027: * uniform resource identifier . This interface allows each section
028: * of the uniform resource identifier to be represented. A generic
029: * uniform resource identifier syntax is represented in RFC 2616
030: * section 3.2.2 for the HTTP protocol, this allows similar URI's
031: * for example ftp, gopher, https, tftp. The syntax is
032: * <code><pre>
033: *
034: * URI = [scheme "://"] host [ ":" port ] [ path [ "?" query ]]
035: *
036: * </pre></code>
037: * This interface reprenents the host, port, path and query part
038: * of the uniform resource identifier. The parameters are also
039: * represented by the URI. The parameters in a URI consist of name
040: * and value pairs in the path segment of the URI.
041: * <p>
042: * This will normalize the path part of the uniform resource
043: * identifier. A normalized path is one that contains no back
044: * references like "./" and "../". The normalized path will not
045: * contain the path parameters.
046: * <p>
047: * The <code>setPath</code> method is used to reset the path this
048: * uniform resource identifier has, it also resets the parameters.
049: * The parameters are extracted from the new path given.
050: *
051: * @author Niall Gallagher
052: */
053: public interface URI {
054:
055: /**
056: * This allows the scheme of the URL given to be returned.
057: * If the URI does not contain a scheme then this will
058: * return null. The scheme of the URI is the part that
059: * specifies the type of protocol that the URI is used
060: * for, an example <code>gopher://domain/path</code> is
061: * a URI that is intended for the gopher protocol. The
062: * scheme is the string <code>gopher</code>.
063: *
064: * @return this returns the scheme tag for the URI if
065: * there is one specified for it
066: */
067: public String getScheme();
068:
069: /**
070: * This allows the scheme for the uri to be specified.
071: * If the URI does not contain a scheme then this will
072: * attach the scheme and the <code>://</code> identifier
073: * to ensure that the <code>URI.toString</code> will
074: * produce the correct syntax.
075: * <p>
076: * Caution must be taken to ensure that the port and
077: * the scheme are consistant. So if the original URI
078: * was <code>http://domain:80/path</code> and the scheme
079: * was changed to <code>ftp</code> the port number that
080: * remains is the standard HTTP port not the FTP port.
081: *
082: * @param scheme this specifies the protocol this URI
083: * is intended for
084: */
085: public void setScheme(String scheme);
086:
087: /**
088: * This is used to retrive the domain of this URI. The
089: * domain part in the URI is an optional part, an example
090: * <code>http://domain/path?querypart</code>. This will
091: * return the value of the domain part. If there is no
092: * domain part then this will return null otherwise the
093: * domain value found in the uniform resource identifier.
094: *
095: * @return the domain part of this uniform resource
096: * identifier this represents
097: */
098: public String getDomain();
099:
100: /**
101: * This will set the domain to whatever value is in the
102: * string parameter. If the string is null then this URI
103: * objects <code>toString</code> method will not contain
104: * the domain. The result of the <code>toString</code>
105: * method will be <code>/path/path?query<code>. If the
106: * path is non-null this URI will contain the path.
107: *
108: * @param domain this will be the new domain of this
109: * uniform resource identifier, if it is not null
110: */
111: public void setDomain(String domain);
112:
113: /**
114: * This is used to retrive the port of the uniform resource
115: * identifier. The port part in this is an optional part, an
116: * example <code>http://host:port/path?querypart</code>. This
117: * will return the value of the port. If there is no port then
118: * this will return <code>-1</code> because this represents
119: * an impossible uniform resource identifier port. The port
120: * is an optional part.
121: *
122: * @return this returns the port of the uniform resource
123: * identifier
124: */
125: public int getPort();
126:
127: /**
128: * This will set the port to whatever value it is given. If
129: * the value is 0 or less then the <code>toString</code> will
130: * will not contain the optional port. If port number is above
131: * 0 then the <code>toString</code> method will produce a URI
132: * like <code>http://host:123/path</code> but only if there is
133: * a valid domain.
134: *
135: * @param port the port value that this URI is to have
136: */
137: public void setPort(int port);
138:
139: /**
140: * This is used to retrive the path of this URI. The path part
141: * is the most fundemental part of the URI. This will return
142: * the value of the path. If there is no path part then this
143: * will return a Path implementation that represents the root
144: * path represented by <code>/</code>.
145: *
146: * @return the path that this URI contains, this value will not
147: * contain any back references such as "./" and "../" or any
148: * path parameters
149: */
150: public Path getPath();
151:
152: /**
153: * This will set the path to whatever value it is given. If the
154: * value is null then this <code>URI.toString</code> method will
155: * not contain the path, that is if path is null then it will be
156: * interpreted as <code>/</code>.
157: * <p>
158: * This will reset the parameters this URI has. If the value
159: * given to this method has embedded parameters these will form
160: * the parameters of this URI. The value given may not be the
161: * same value that the <code>getPath</code> produces. The path
162: * will have all back references and parameters stripped.
163: *
164: * @param path the path that this URI is to be set with
165: */
166: public void setPath(String path);
167:
168: /**
169: * This will set the path to whatever value it is given. If the
170: * value is null then this <code>URI.toString</code> method will
171: * not contain the path, that is if path is null then it will be
172: * interpreted as <code>/</code>.
173: * <p>
174: * This will reset the parameters this URI has. If the value
175: * given to this method has embedded parameters these will form
176: * the parameters of this URI. The value given may not be the
177: * same value that the <code>getPath</code> produces. The path
178: * will have all back references and parameters stripped.
179: *
180: * @param path the path that this URI is to be set with
181: */
182: public void setPath(Path path);
183:
184: /**
185: * This is used to retrive the query of this URI. The query part
186: * in the URI is an optional part. This will return the value
187: * of the query part. If there is no query part then this will
188: * return an empty <code>Parameters</code> object. The query is
189: * an optional member of a URI and comes after the path part, it
190: * is preceeded by a question mark, <code>?</code> character.
191: * For example the following URI contains <code>query<code> for
192: * its query part, <code>http://host:port/path?query</code>.
193: * <p>
194: * This returns a <code>simple.util.net.Parameters</code> object
195: * that can be used to interact directly with the query values.
196: * The <code>Parameters</code> object is a read-only interface
197: * to the query parameters, and so will not affect the URI.
198: *
199: * @return a <code>Parameters</code> object for the query part
200: */
201: public Parameters getQuery();
202:
203: /**
204: * This will set the query to whatever value it is given. If the
205: * value is null then this <code>URI.toString</code> method will
206: * not contain the query. If the query was <code>abc<code> then
207: * the <code>toString</code> method would produca a string like
208: * <code>http://host:port/path?abc</code>. If the query is null
209: * this URI would have no query part.
210: *
211: * @param query the query that this uniform resource identifier
212: * is to be set to if it is non-null
213: */
214: public void setQuery(String query);
215:
216: /**
217: * This will set the query to whatever value it is given. If the
218: * value is null then this <code>URI.toString</code> method will
219: * not contain the query. If the <code>Parameters.toString<code>
220: * returns null then the query will be empty. This is basically
221: * the <code>setQuery(String)</code> method with the string value
222: * from the issued <code>Parameters.toString</code> method.
223: *
224: * @param query a <code>Parameters</code> object that contains
225: * the name value parameters for the query
226: */
227: public void setQuery(Parameters query);
228:
229: /**
230: * This extracts the parameter names from the uniform resource
231: * identifier represented by this object. The parameters that a
232: * uniform resource identifier contains are embedded in the path
233: * part of the URI. If the path contains no parameters then this
234: * will return an empty <code>Enumeration</code>.
235: * <p>
236: * This will produce unique name and value parameters. Thus if the
237: * URI contains several path segments with similar parameter names
238: * this will return the deepest parameter. For example if the URI
239: * represented was <code>http://domain/path1;x=y/path2;x=z</code>
240: * the value for the parameter named <code>x</code> would be
241: * <code>z</code>.
242: *
243: * @return this will return the parameter names found in the URI
244: */
245: public Enumeration getParameterNames();
246:
247: /**
248: * This will return the value of the parameter with the given name.
249: * The parameters stored by this URI will bve unique so this will
250: * produce the parameter found deepest within the path segment, see
251: * <code>getParameterNames</code>. This will return null if the
252: * parameter does not exist. The <code>setPath</code> method will
253: * reset the parameters the URI contains.
254: *
255: * @param name this is the name of the parameter to be retrived
256: *
257: * @return this will return the parameter value or null if the
258: * parameter does not exist
259: */
260: public String getParameter(String name);
261:
262: /**
263: * This is used to convert this URI object into a <code>String</code>
264: * object. This will only convert the parts of the URI that exist, so
265: * the URI may not contain the domain or the query part and it will
266: * not contain the path parameters. If the URI contains all these
267: * parts then it will return somthing like
268: * <pre>
269: * scheme://host:port/path/path?querypart
270: * </pre>
271: * <p>
272: * It can return <code>/path/path?querypart</code> style relative
273: * URI's. If any of the parts are set to null then that part will be
274: * missing, for example if <code>setDomain</code> method is invoked
275: * with a null parameter then the domain and port will be missing
276: * from the resulting URI. If the path part is set to null using the
277: * <code>setPath</code> then the path will be <code>/</code>. An
278: * example URI with the path part of null would be
279: * <pre>
280: * scheme://host:port/?querypart
281: * </pre>
282: *
283: * @return the URI with only the path part and the non-null optional
284: * parts of the uniform resource identifier
285: */
286: public String toString();
287: }
|