try to fix some minor dropdown bugs
[potlatch2.git] / com / adobe / net / URI.as
1 /*\r
2   Copyright (c) 2008, Adobe Systems Incorporated\r
3   All rights reserved.\r
4 \r
5   Redistribution and use in source and binary forms, with or without \r
6   modification, are permitted provided that the following conditions are\r
7   met:\r
8 \r
9   * Redistributions of source code must retain the above copyright notice, \r
10     this list of conditions and the following disclaimer.\r
11   \r
12   * Redistributions in binary form must reproduce the above copyright\r
13     notice, this list of conditions and the following disclaimer in the \r
14     documentation and/or other materials provided with the distribution.\r
15   \r
16   * Neither the name of Adobe Systems Incorporated nor the names of its \r
17     contributors may be used to endorse or promote products derived from \r
18     this software without specific prior written permission.\r
19 \r
20   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS\r
21   IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,\r
22   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR\r
23   PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR \r
24   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,\r
25   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,\r
26   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR\r
27   PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF\r
28   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING\r
29   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\r
30   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
31 */\r
32 \r
33 package com.adobe.net\r
34 {\r
35         import flash.utils.ByteArray;\r
36         \r
37         /**\r
38          * This class implements functions and utilities for working with URI's\r
39          * (Universal Resource Identifiers).  For technical description of the\r
40          * URI syntax, please see RFC 3986 at http://www.ietf.org/rfc/rfc3986.txt\r
41          * or do a web search for "rfc 3986".\r
42          * \r
43          * <p>The most important aspect of URI's to understand is that URI's\r
44          * and URL's are not strings.  URI's are complex data structures that\r
45          * encapsulate many pieces of information.  The string version of a\r
46          * URI is the serialized representation of that data structure.  This\r
47          * string serialization is used to provide a human readable\r
48          * representation and a means to transport the data over the network\r
49          * where it can then be parsed back into its' component parts.</p>\r
50          * \r
51          * <p>URI's fall into one of three categories:\r
52          * <ul>\r
53          *  <li>&lt;scheme&gt;:&lt;scheme-specific-part&gt;#&lt;fragment&gt;            (non-hierarchical)</li>\r
54          *  <li>&lt;scheme&gt;:<authority&gt;&lt;path&gt;?&lt;query&gt;#&lt;fragment&gt;        (hierarchical)</li>\r
55          *  <li>&lt;path&gt;?&lt;query&gt;#&lt;fragment&gt;                                             (relative hierarchical)</li>\r
56          * </ul></p>\r
57          * \r
58          * <p>The query and fragment parts are optional.</p>\r
59          * \r
60          * <p>This class supports both non-hierarchical and hierarchical URI's</p>\r
61          * \r
62          * <p>This class is intended to be used "as-is" for the vast majority\r
63          * of common URI's.  However, if your application requires a custom\r
64          * URI syntax (e.g. custom query syntax or special handling of\r
65          * non-hierarchical URI's), this class can be fully subclassed.  If you\r
66          * intended to subclass URI, please see the source code for complete\r
67          * documation on protected members and protected fuctions.</p>\r
68          * \r
69          * @langversion ActionScript 3.0\r
70          * @playerversion Flash 9.0 \r
71          */\r
72         public class URI\r
73         {       \r
74                 // Here we define which characters must be escaped for each\r
75                 // URI part.  The characters that must be escaped for each\r
76                 // part differ depending on what would cause ambiguous parsing.\r
77                 // RFC 3986 sec. 2.4 states that characters should only be\r
78                 // encoded when they would conflict with subcomponent delimiters.\r
79                 // We don't want to over-do the escaping.  We only want to escape\r
80                 // the minimum needed to prevent parsing problems.\r
81                 \r
82                 // space and % must be escaped in all cases.  '%' is the delimiter\r
83                 // for escaped characters.\r
84                 public static const URImustEscape:String =      " %";\r
85                 \r
86                 // Baseline of what characters must be escaped\r
87                 public static const URIbaselineEscape:String = URImustEscape + ":?#/@";\r
88                 \r
89                 // Characters that must be escaped in the part part.\r
90                 public static const URIpathEscape:String = URImustEscape + "?#";\r
91                 \r
92                 // Characters that must be escaped in the query part, if setting\r
93                 // the query as a whole string.  If the query is set by\r
94                 // name/value, URIqueryPartEscape is used instead.\r
95                 public static const URIqueryEscape:String = URImustEscape + "#";\r
96                 \r
97                 // This is what each name/value pair must escape "&=" as well\r
98                 // so they don't conflict with the "param=value&param2=value2"\r
99                 // syntax.\r
100                 public static const URIqueryPartEscape:String = URImustEscape + "#&=";\r
101                 \r
102                 // Non-hierarchical URI's can have query and fragment parts, but\r
103                 // we also want to prevent '/' otherwise it might end up looking\r
104                 // like a hierarchical URI to the parser.\r
105                 public static const URInonHierEscape:String =   URImustEscape + "?#/";\r
106                 \r
107                 // Baseline uninitialized setting for the URI scheme.\r
108                 public static const UNKNOWN_SCHEME:String = "unknown";\r
109                 \r
110                 // The following bitmaps are used for performance enhanced\r
111                 // character escaping.\r
112                 \r
113                 // Baseline characters that need to be escaped.  Many parts use\r
114                 // this.\r
115                 protected static const URIbaselineExcludedBitmap:URIEncodingBitmap =\r
116                         new URIEncodingBitmap(URIbaselineEscape);\r
117                 \r
118                 // Scheme escaping bitmap\r
119                 protected static const URIschemeExcludedBitmap:URIEncodingBitmap = \r
120                         URIbaselineExcludedBitmap;\r
121                 \r
122                 // User/pass escaping bitmap\r
123                 protected static const URIuserpassExcludedBitmap:URIEncodingBitmap =\r
124                         URIbaselineExcludedBitmap;\r
125                 \r
126                 // Authority escaping bitmap\r
127                 protected static const URIauthorityExcludedBitmap:URIEncodingBitmap =\r
128                         URIbaselineExcludedBitmap;\r
129                         \r
130                 // Port escaping bitmap\r
131                 protected static const URIportExludedBitmap:URIEncodingBitmap = \r
132                         URIbaselineExcludedBitmap;\r
133                 \r
134                 // Path escaping bitmap\r
135                 protected static const URIpathExcludedBitmap:URIEncodingBitmap =\r
136                         new URIEncodingBitmap(URIpathEscape);\r
137                         \r
138                 // Query (whole) escaping bitmap\r
139                 protected static const URIqueryExcludedBitmap:URIEncodingBitmap =\r
140                         new URIEncodingBitmap(URIqueryEscape);\r
141                         \r
142                 // Query (individual parts) escaping bitmap\r
143                 protected static const URIqueryPartExcludedBitmap:URIEncodingBitmap =\r
144                         new URIEncodingBitmap(URIqueryPartEscape);\r
145                         \r
146                 // Fragments are the last part in the URI.  They only need to\r
147                 // escape space, '#', and '%'.  Turns out that is what query\r
148                 // uses too.\r
149                 protected static const URIfragmentExcludedBitmap:URIEncodingBitmap =\r
150                         URIqueryExcludedBitmap;\r
151                         \r
152                 // Characters that need to be escaped in the non-hierarchical part\r
153                 protected static const URInonHierexcludedBitmap:URIEncodingBitmap =\r
154                         new URIEncodingBitmap(URInonHierEscape);\r
155                         \r
156                 // Values used by getRelation()\r
157                 public static const NOT_RELATED:int = 0;\r
158                 public static const CHILD:int = 1;\r
159                 public static const EQUAL:int = 2;\r
160                 public static const PARENT:int = 3;\r
161 \r
162                 //-------------------------------------------------------------------\r
163                 // protected class members\r
164                 //-------------------------------------------------------------------\r
165                 protected var _valid:Boolean = false;\r
166                 protected var _relative:Boolean = false;\r
167                 protected var _scheme:String = "";\r
168                 protected var _authority:String = "";\r
169                 protected var _username:String = "";\r
170                 protected var _password:String = "";\r
171                 protected var _port:String = "";\r
172                 protected var _path:String = "";\r
173                 protected var _query:String = "";\r
174                 protected var _fragment:String = "";\r
175                 protected var _nonHierarchical:String = "";\r
176                 protected static var _resolver:IURIResolver = null;\r
177 \r
178 \r
179                 /**\r
180                  *  URI Constructor.  If no string is given, this will initialize\r
181                  *  this URI object to a blank URI.\r
182                  */\r
183                 public function URI(uri:String = null) : void   \r
184                 {\r
185                         if (uri == null)\r
186                                 initialize();\r
187                         else\r
188                                 constructURI(uri);\r
189                 }\r
190 \r
191                 \r
192                 /**\r
193                  * @private\r
194                  * Method that loads the URI from the given string.\r
195                  */\r
196                 protected function constructURI(uri:String) : Boolean\r
197                 {\r
198                         if (!parseURI(uri))\r
199                                 _valid = false;\r
200                                 \r
201                         return isValid();\r
202                 }\r
203                 \r
204                 \r
205                 /**\r
206                  * @private Private initializiation.\r
207                  */\r
208                 protected function initialize() : void\r
209                 {\r
210                         _valid = false;\r
211                         _relative = false;\r
212                 \r
213                         _scheme = UNKNOWN_SCHEME;\r
214                         _authority = "";\r
215                         _username = "";\r
216                         _password = "";\r
217                         _port = "";\r
218                         _path = "";\r
219                         _query = "";\r
220                         _fragment = "";\r
221                 \r
222                         _nonHierarchical = "";\r
223                 }       \r
224                 \r
225                 /**\r
226                  * @private Accessor to explicitly set/get the hierarchical\r
227                  * state of the URI.\r
228                  */\r
229                 protected function set hierState(state:Boolean) : void\r
230                 {\r
231                         if (state)\r
232                         {\r
233                                 // Clear the non-hierarchical data\r
234                                 _nonHierarchical = "";\r
235                 \r
236                                 // Also set the state vars while we are at it\r
237                                 if (_scheme == "" || _scheme == UNKNOWN_SCHEME)\r
238                                         _relative = true;\r
239                                 else\r
240                                         _relative = false;\r
241                 \r
242                                 if (_authority.length == 0 && _path.length == 0)\r
243                                         _valid = false;\r
244                                 else\r
245                                         _valid = true;\r
246                         }\r
247                         else\r
248                         {\r
249                                 // Clear the hierarchical data\r
250                                 _authority = "";\r
251                                 _username = "";\r
252                                 _password = "";\r
253                                 _port = "";\r
254                                 _path = "";\r
255                 \r
256                                 _relative = false;\r
257                 \r
258                                 if (_scheme == "" || _scheme == UNKNOWN_SCHEME)\r
259                                         _valid = false;\r
260                                 else\r
261                                         _valid = true;\r
262                         }\r
263                 }\r
264                 protected function get hierState() : Boolean\r
265                 {\r
266                         return (_nonHierarchical.length == 0);\r
267                 }\r
268                 \r
269                 \r
270                 /**\r
271                  * @private Functions that performs some basic consistency validation.\r
272                  */\r
273                 protected function validateURI() : Boolean\r
274                 {\r
275                         // Check the scheme\r
276                         if (isAbsolute())\r
277                         {\r
278                                 if (_scheme.length <= 1 || _scheme == UNKNOWN_SCHEME)\r
279                                 {\r
280                                         // we probably parsed a C:\ type path or no scheme\r
281                                         return false;\r
282                                 }\r
283                                 else if (verifyAlpha(_scheme) == false)\r
284                                         return false;  // Scheme contains bad characters\r
285                         }\r
286                         \r
287                         if (hierState)\r
288                         {\r
289                                 if (_path.search('\\') != -1)\r
290                                         return false;  // local path\r
291                                 else if (isRelative() == false && _scheme == UNKNOWN_SCHEME)\r
292                                         return false;  // It's an absolute URI, but it has a bad scheme\r
293                         }\r
294                         else\r
295                         {\r
296                                 if (_nonHierarchical.search('\\') != -1)\r
297                                         return false;  // some kind of local path\r
298                         }\r
299                 \r
300                         // Looks like it's ok.\r
301                         return true;\r
302                 }\r
303                 \r
304                 \r
305                 /**\r
306                  * @private\r
307                  *\r
308                  * Given a URI in string format, parse that sucker into its basic\r
309                  * components and assign them to this object.  A URI is of the form:\r
310                  *    <scheme>:<authority><path>?<query>#<fragment>\r
311                  *\r
312                  * For simplicity, we parse the URI in the following order:\r
313                  *              \r
314                  *              1. Fragment (anchors)\r
315                  *              2. Query        (CGI stuff)\r
316                  *              3. Scheme       ("http")\r
317                  *              4. Authority (host name)\r
318                  *              5. Username/Password (if any)\r
319                  *              6. Port         (server port if any)\r
320                  *              7. Path         (/homepages/mypage.html)\r
321                  *\r
322                  * The reason for this order is to minimize any parsing ambiguities.\r
323                  * Fragments and queries can contain almost anything (they are parts\r
324                  * that can contain custom data with their own syntax).  Parsing\r
325                  * them out first removes a large chance of parsing errors.  This\r
326                  * method expects well formed URI's, but performing the parse in\r
327                  * this order makes us a little more tolerant of user error.\r
328                  * \r
329                  * REGEXP\r
330                  * Why doesn't this use regular expressions to parse the URI?  We\r
331                  * have found that in a real world scenario, URI's are not always\r
332                  * well formed.  Sometimes characters that should have been escaped\r
333                  * are not, and those situations would break a regexp pattern.  This\r
334                  * function attempts to be smart about what it is parsing based on\r
335                  * location of characters relative to eachother.  This function has\r
336                  * been proven through real-world use to parse the vast majority\r
337                  * of URI's correctly.\r
338                  *\r
339                  * NOTE\r
340                  * It is assumed that the string in URI form is escaped.  This function\r
341                  * does not escape anything.  If you constructed the URI string by\r
342                  * hand, and used this to parse in the URI and still need it escaped,\r
343                  * call forceEscape() on your URI object.\r
344                  *\r
345                  * Parsing Assumptions\r
346                  * This routine assumes that the URI being passed is well formed.\r
347                  * Passing things like local paths, malformed URI's, and the such\r
348                  * will result in parsing errors.  This function can handle\r
349                  *       - absolute hierarchical (e.g. "http://something.com/index.html),\r
350                  *   - relative hierarchical (e.g. "../images/flower.gif"), or\r
351                  *   - non-hierarchical URIs (e.g. "mailto:jsmith@fungoo.com").\r
352                  * \r
353                  * Anything else will probably result in a parsing error, or a bogus\r
354                  * URI object.\r
355                  * \r
356                  * Note that non-hierarchical URIs *MUST* have a scheme, otherwise\r
357                  * they will be mistaken for relative URI's.\r
358                  * \r
359                  * If you are not sure what is being passed to you (like manually\r
360                  * entered text from UI), you can construct a blank URI object and\r
361                  * call unknownToURI() passing in the unknown string.\r
362                  * \r
363                  * @return      true if successful, false if there was some kind of\r
364                  * parsing error\r
365                  */\r
366                 protected function parseURI(uri:String) : Boolean\r
367                 {\r
368                         var baseURI:String = uri;\r
369                         var index:int, index2:int;\r
370                 \r
371                         // Make sure this object is clean before we start.  If it was used\r
372                         // before and we are now parsing a new URI, we don't want any stale\r
373                         // info lying around.\r
374                         initialize();\r
375                 \r
376                         // Remove any fragments (anchors) from the URI\r
377                         index = baseURI.indexOf("#");\r
378                         if (index != -1)\r
379                         {\r
380                                 // Store the fragment piece if any\r
381                                 if (baseURI.length > (index + 1)) // +1 is to skip the '#'\r
382                                         _fragment = baseURI.substr(index + 1, baseURI.length - (index + 1)); \r
383                 \r
384                                 // Trim off the fragment\r
385                                 baseURI = baseURI.substr(0, index);\r
386                         }\r
387                 \r
388                         // We need to strip off any CGI parameters (eg '?param=bob')\r
389                         index = baseURI.indexOf("?");\r
390                         if (index != -1)\r
391                         {\r
392                                 if (baseURI.length > (index + 1))\r
393                                         _query = baseURI.substr(index + 1, baseURI.length - (index + 1)); // +1 is to skip the '?'\r
394                 \r
395                                 // Trim off the query\r
396                                 baseURI = baseURI.substr(0, index);\r
397                         }\r
398                 \r
399                         // Now try to find the scheme part\r
400                         index = baseURI.search(':');\r
401                         index2 = baseURI.search('/');\r
402                 \r
403                         var containsColon:Boolean = (index != -1);\r
404                         var containsSlash:Boolean = (index2 != -1);\r
405                 \r
406                         // This value is indeterminate if "containsColon" is false.\r
407                         // (if there is no colon, does the slash come before or\r
408                         // after said non-existing colon?)\r
409                         var colonBeforeSlash:Boolean = (!containsSlash || index < index2);\r
410                 \r
411                         // If it has a colon and it's before the first slash, we will treat\r
412                         // it as a scheme.  If a slash is before a colon, there must be a\r
413                         // stray colon in a path or something.  In which case, the colon is\r
414                         // not the separator for the scheme.  Technically, we could consider\r
415                         // this an error, but since this is not an ambiguous state (we know\r
416                         // 100% that this has no scheme), we will keep going.\r
417                         if (containsColon && colonBeforeSlash)\r
418                         {\r
419                                 // We found a scheme\r
420                                 _scheme = baseURI.substr(0, index);\r
421                                 \r
422                                 // Normalize the scheme\r
423                                 _scheme = _scheme.toLowerCase();\r
424                 \r
425                                 baseURI = baseURI.substr(index + 1);\r
426                 \r
427                                 if (baseURI.substr(0, 2) == "//")\r
428                                 {\r
429                                         // This is a hierarchical URI\r
430                                         _nonHierarchical = "";\r
431                 \r
432                                         // Trim off the "//"\r
433                                         baseURI = baseURI.substr(2, baseURI.length - 2);\r
434                                 }\r
435                                 else\r
436                                 {\r
437                                         // This is a non-hierarchical URI like "mailto:bob@mail.com"\r
438                                         _nonHierarchical = baseURI;\r
439                 \r
440                                         if ((_valid = validateURI()) == false)\r
441                                                 initialize();  // Bad URI.  Clear it.\r
442                 \r
443                                         // No more parsing to do for this case\r
444                                         return isValid();\r
445                                 }\r
446                         }\r
447                         else\r
448                         {\r
449                                 // No scheme.  We will consider this a relative URI\r
450                                 _scheme = "";\r
451                                 _relative = true;\r
452                                 _nonHierarchical = "";\r
453                         }\r
454                 \r
455                         // Ok, what we have left is everything after the <scheme>://\r
456                 \r
457                         // Now that we have stripped off any query and fragment parts, we\r
458                         // need to split the authority from the path\r
459                 \r
460                         if (isRelative())\r
461                         {\r
462                                 // Don't bother looking for the authority.  It's a relative URI\r
463                                 _authority = "";\r
464                                 _port = "";\r
465                                 _path = baseURI;\r
466                         }\r
467                         else\r
468                         {\r
469                                 // Check for malformed UNC style file://///server/type/path/\r
470                                 // By the time we get here, we have already trimmed the "file://"\r
471                                 // so baseURI will be ///server/type/path.  If baseURI only\r
472                                 // has one slash, we leave it alone because that is valid (that\r
473                                 // is the case of "file:///path/to/file.txt" where there is no\r
474                                 // server - implicit "localhost").\r
475                                 if (baseURI.substr(0, 2) == "//")\r
476                                 {\r
477                                         // Trim all leading slashes\r
478                                         while(baseURI.charAt(0) == "/")\r
479                                                 baseURI = baseURI.substr(1, baseURI.length - 1);\r
480                                 }\r
481                 \r
482                                 index = baseURI.search('/');\r
483                                 if (index == -1)\r
484                                 {\r
485                                         // No path.  We must have passed something like "http://something.com"\r
486                                         _authority = baseURI;\r
487                                         _path = "";\r
488                                 }\r
489                                 else\r
490                                 {\r
491                                         _authority = baseURI.substr(0, index);\r
492                                         _path = baseURI.substr(index, baseURI.length - index);\r
493                                 }\r
494                 \r
495                                 // Check to see if the URI has any username or password information.\r
496                                 // For example:  ftp://username:password@server.com\r
497                                 index = _authority.search('@');\r
498                                 if (index != -1)\r
499                                 {\r
500                                         // We have a username and possibly a password\r
501                                         _username = _authority.substr(0, index);\r
502                 \r
503                                         // Remove the username/password from the authority\r
504                                         _authority = _authority.substr(index + 1);  // Skip the '@'\r
505                 \r
506                                         // Now check to see if the username also has a password\r
507                                         index = _username.search(':');\r
508                                         if (index != -1)\r
509                                         {\r
510                                                 _password = _username.substring(index + 1, _username.length);\r
511                                                 _username = _username.substr(0, index);\r
512                                         }\r
513                                         else\r
514                                                 _password = "";\r
515                                 }\r
516                                 else\r
517                                 {\r
518                                         _username = "";\r
519                                         _password = "";\r
520                                 }\r
521                 \r
522                                 // Lastly, check to see if the authorty has a port number.\r
523                                 // This is parsed after the username/password to avoid conflicting\r
524                                 // with the ':' in the 'username:password' if one exists.\r
525                                 index = _authority.search(':');\r
526                                 if (index != -1)\r
527                                 {\r
528                                         _port = _authority.substring(index + 1, _authority.length);  // skip the ':'\r
529                                         _authority = _authority.substr(0, index);\r
530                                 }\r
531                                 else\r
532                                 {\r
533                                         _port = "";\r
534                                 }\r
535                                 \r
536                                 // Lastly, normalize the authority.  Domain names\r
537                                 // are case insensitive.\r
538                                 _authority = _authority.toLowerCase();\r
539                         }\r
540                 \r
541                         if ((_valid = validateURI()) == false)\r
542                                 initialize();  // Bad URI.  Clear it\r
543                 \r
544                         return isValid();\r
545                 }\r
546                 \r
547                 \r
548                 /********************************************************************\r
549                  * Copy function.\r
550                  */\r
551                 public function copyURI(uri:URI) : void\r
552                 {\r
553                         this._scheme = uri._scheme;\r
554                         this._authority = uri._authority;\r
555                         this._username = uri._username;\r
556                         this._password = uri._password;\r
557                         this._port = uri._port;\r
558                         this._path = uri._path;\r
559                         this._query = uri._query;\r
560                         this._fragment = uri._fragment;\r
561                         this._nonHierarchical = uri._nonHierarchical;\r
562                 \r
563                         this._valid = uri._valid;\r
564                         this._relative = uri._relative;\r
565                 }\r
566                 \r
567                 \r
568                 /**\r
569                  * @private\r
570                  * Checks if the given string only contains a-z or A-Z.\r
571                  */\r
572                 protected function verifyAlpha(str:String) : Boolean\r
573                 {\r
574                         var pattern:RegExp = /[^a-z]/;\r
575                         var index:int;\r
576                         \r
577                         str = str.toLowerCase();\r
578                         index = str.search(pattern);\r
579                         \r
580                         if (index == -1)\r
581                                 return true;\r
582                         else\r
583                                 return false;\r
584                 }\r
585                 \r
586                 /**\r
587                  * Is this a valid URI?\r
588                  * \r
589                  * @return true if this object represents a valid URI, false\r
590                  * otherwise.\r
591                  */\r
592                 public function isValid() : Boolean\r
593                 { \r
594                         return this._valid;\r
595                 }\r
596                 \r
597                 \r
598                 /**\r
599                  * Is this URI an absolute URI?  An absolute URI is a complete, fully\r
600                  * qualified reference to a resource.  e.g. http://site.com/index.htm\r
601                  * Non-hierarchical URI's are always absolute.\r
602                  */\r
603                 public function isAbsolute() : Boolean\r
604                 { \r
605                         return !this._relative;\r
606                 }\r
607                 \r
608                 \r
609                 /**\r
610                  * Is this URI a relative URI?  Relative URI's do not have a scheme\r
611                  * and only contain a relative path with optional anchor and query\r
612                  * parts.  e.g. "../reports/index.htm".  Non-hierarchical URI's\r
613                  * will never be relative.\r
614                  */\r
615                 public function isRelative() : Boolean\r
616                 { \r
617                         return this._relative;\r
618                 }\r
619                 \r
620                 \r
621                 /**\r
622                  * Does this URI point to a resource that is a directory/folder?\r
623                  * The URI specification dictates that any path that ends in a slash\r
624                  * is a directory.  This is needed to be able to perform correct path\r
625                  * logic when combining relative URI's with absolute URI's to\r
626                  * obtain the correct absolute URI to a resource.\r
627                  * \r
628                  * @see URI.chdir\r
629                  * \r
630                  * @return true if this URI represents a directory resource, false\r
631                  * if this URI represents a file resource.\r
632                  */\r
633                 public function isDirectory() : Boolean\r
634                 {\r
635                         if (_path.length == 0)\r
636                                 return false;\r
637                 \r
638                         return (_path.charAt(path.length - 1) == '/');\r
639                 }\r
640                 \r
641                 \r
642                 /**\r
643                  * Is this URI a hierarchical URI? URI's can be  \r
644                  */\r
645                 public function isHierarchical() : Boolean\r
646                 { \r
647                         return hierState;\r
648                 }\r
649                                 \r
650                 \r
651                 /**\r
652                  * The scheme of the URI.\r
653                  */\r
654                 public function get scheme() : String\r
655                 { \r
656                         return URI.unescapeChars(_scheme);\r
657                 }\r
658                 public function set scheme(schemeStr:String) : void\r
659                 {\r
660                         // Normalize the scheme\r
661                         var normalized:String = schemeStr.toLowerCase();\r
662                         _scheme = URI.fastEscapeChars(normalized, URI.URIschemeExcludedBitmap);\r
663                 }\r
664                 \r
665                 \r
666                 /**\r
667                  * The authority (host) of the URI.  Only valid for\r
668                  * hierarchical URI's.  If the URI is relative, this will\r
669                  * be an empty string. When setting this value, the string\r
670                  * given is assumed to be unescaped.  When retrieving this\r
671                  * value, the resulting string is unescaped.\r
672                  */\r
673                 public function get authority() : String\r
674                 { \r
675                         return URI.unescapeChars(_authority);\r
676                 }\r
677                 public function set authority(authorityStr:String) : void\r
678                 {\r
679                         // Normalize the authority\r
680                         authorityStr = authorityStr.toLowerCase();\r
681                         \r
682                         _authority = URI.fastEscapeChars(authorityStr,\r
683                                 URI.URIauthorityExcludedBitmap);\r
684                         \r
685                         // Only hierarchical URI's can have an authority, make\r
686                         // sure this URI is of the proper format.\r
687                         this.hierState = true;\r
688                 }\r
689                 \r
690                 \r
691                 /**\r
692                  * The username of the URI.  Only valid for hierarchical\r
693                  * URI's.  If the URI is relative, this will be an empty\r
694                  * string.\r
695                  * \r
696                  * <p>The URI specification allows for authentication\r
697                  * credentials to be embedded in the URI as such:</p>\r
698                  * \r
699                  * <p>http://user:passwd&#64;host/path/to/file.htm</p>\r
700                  * \r
701                  * <p>When setting this value, the string\r
702                  * given is assumed to be unescaped.  When retrieving this\r
703                  * value, the resulting string is unescaped.</p>\r
704                  */\r
705                 public function get username() : String\r
706                 {\r
707                         return URI.unescapeChars(_username);\r
708                 }\r
709                 public function set username(usernameStr:String) : void\r
710                 {\r
711                         _username = URI.fastEscapeChars(usernameStr, URI.URIuserpassExcludedBitmap);\r
712                         \r
713                         // Only hierarchical URI's can have a username.\r
714                         this.hierState = true;\r
715                 }\r
716                 \r
717                 \r
718                 /**\r
719                  * The password of the URI.  Similar to username.\r
720                  * @see URI.username\r
721                  */\r
722                 public function get password() : String\r
723                 {\r
724                         return URI.unescapeChars(_password);\r
725                 }\r
726                 public function set password(passwordStr:String) : void\r
727                 {\r
728                         _password = URI.fastEscapeChars(passwordStr,\r
729                                 URI.URIuserpassExcludedBitmap);\r
730                         \r
731                         // Only hierarchical URI's can have a password.\r
732                         this.hierState = true;\r
733                 }\r
734                 \r
735                 \r
736                 /**\r
737                  * The host port number.  Only valid for hierarchical URI's.  If\r
738                  * the URI is relative, this will be an empty string. URI's can\r
739                  * contain the port number of the remote host:\r
740                  * \r
741                  * <p>http://site.com:8080/index.htm</p>\r
742                  */\r
743                 public function get port() : String\r
744                 { \r
745                         return URI.unescapeChars(_port);\r
746                 }\r
747                 public function set port(portStr:String) : void\r
748                 {\r
749                         _port = URI.escapeChars(portStr);\r
750                         \r
751                         // Only hierarchical URI's can have a port.\r
752                         this.hierState = true;\r
753                 }\r
754                 \r
755                 \r
756                 /**\r
757                  * The path portion of the URI.  Only valid for hierarchical\r
758                  * URI's.  When setting this value, the string\r
759                  * given is assumed to be unescaped.  When retrieving this\r
760                  * value, the resulting string is unescaped.\r
761                  * \r
762                  * <p>The path portion can be in one of two formats. 1) an absolute\r
763                  * path, or 2) a relative path.  An absolute path starts with a\r
764                  * slash ('/'), a relative path does not.</p>\r
765                  * \r
766                  * <p>An absolute path may look like:</p>\r
767                  * <listing>/full/path/to/my/file.htm</listing>\r
768                  * \r
769                  * <p>A relative path may look like:</p>\r
770                  * <listing>\r
771                  * path/to/my/file.htm\r
772                  * ../images/logo.gif\r
773                  * ../../reports/index.htm\r
774                  * </listing>\r
775                  * \r
776                  * <p>Paths can be absolute or relative.  Note that this not the same as\r
777                  * an absolute or relative URI.  An absolute URI can only have absolute\r
778                  * paths.  For example:</p>\r
779                  * \r
780                  * <listing>http:/site.com/path/to/file.htm</listing>\r
781                  * \r
782                  * <p>This absolute URI has an absolute path of "/path/to/file.htm".</p>\r
783                  * \r
784                  * <p>Relative URI's can have either absolute paths or relative paths.\r
785                  * All of the following relative URI's are valid:</p>\r
786                  * \r
787                  * <listing>\r
788                  * /absolute/path/to/file.htm\r
789                  * path/to/file.htm\r
790                  * ../path/to/file.htm\r
791                  * </listing>\r
792                  */\r
793                 public function get path() : String\r
794                 { \r
795                         return URI.unescapeChars(_path);\r
796                 }\r
797                 public function set path(pathStr:String) : void\r
798                 {       \r
799                         this._path = URI.fastEscapeChars(pathStr, URI.URIpathExcludedBitmap);\r
800                 \r
801                         if (this._scheme == UNKNOWN_SCHEME)\r
802                         {\r
803                                 // We set the path.  This is a valid URI now.\r
804                                 this._scheme = "";\r
805                         }\r
806                 \r
807                         // Only hierarchical URI's can have a path.\r
808                         hierState = true;\r
809                 }\r
810                 \r
811                 \r
812                 /**\r
813                  * The query (CGI) portion of the URI.  This part is valid for\r
814                  * both hierarchical and non-hierarchical URI's.\r
815                  * \r
816                  * <p>This accessor should only be used if a custom query syntax\r
817                  * is used.  This URI class supports the common "param=value"\r
818                  * style query syntax via the get/setQueryValue() and\r
819                  * get/setQueryByMap() functions.  Those functions should be used\r
820                  * instead if the common syntax is being used.\r
821                  * \r
822                  * <p>The URI RFC does not specify any particular\r
823                  * syntax for the query part of a URI.  It is intended to allow\r
824                  * any format that can be agreed upon by the two communicating hosts.\r
825                  * However, most systems have standardized on the typical CGI\r
826                  * format:</p>\r
827                  * \r
828                  * <listing>http://site.com/script.php?param1=value1&param2=value2</listing>\r
829                  * \r
830                  * <p>This class has specific support for this query syntax</p>\r
831                  * \r
832                  * <p>This common query format is an array of name/value\r
833                  * pairs with its own syntax that is different from the overall URI\r
834                  * syntax.  The query has its own escaping logic.  For a query part\r
835                  * to be properly escaped and unescaped, it must be split into its\r
836                  * component parts.  This accessor escapes/unescapes the entire query\r
837                  * part without regard for it's component parts.  This has the\r
838                  * possibliity of leaving the query string in an ambiguious state in\r
839                  * regards to its syntax.  If the contents of the query part are\r
840                  * important, it is recommended that get/setQueryValue() or\r
841                  * get/setQueryByMap() are used instead.</p>\r
842                  * \r
843                  * If a different query syntax is being used, a subclass of URI\r
844                  * can be created to handle that specific syntax.\r
845                  *  \r
846                  * @see URI.getQueryValue, URI.getQueryByMap\r
847                  */\r
848                 public function get query() : String\r
849                 { \r
850                         return URI.unescapeChars(_query);\r
851                 }\r
852                 public function set query(queryStr:String) : void\r
853                 {\r
854                         _query = URI.fastEscapeChars(queryStr, URI.URIqueryExcludedBitmap);\r
855                         \r
856                         // both hierarchical and non-hierarchical URI's can\r
857                         // have a query.  Do not set the hierState.\r
858                 }\r
859                 \r
860                 /**\r
861                  * Accessor to the raw query data.  If you are using a custom query\r
862                  * syntax, this accessor can be used to get and set the query part\r
863                  * directly with no escaping/unescaping.  This should ONLY be used\r
864                  * if your application logic is handling custom query logic and\r
865                  * handling the proper escaping of the query part.\r
866                  */\r
867                 public function get queryRaw() : String\r
868                 {\r
869                         return _query;\r
870                 }\r
871                 public function set queryRaw(queryStr:String) : void\r
872                 {\r
873                         _query = queryStr;\r
874                 }\r
875 \r
876 \r
877                 /**\r
878                  * The fragment (anchor) portion of the URI.  This is valid for\r
879                  * both hierarchical and non-hierarchical URI's.\r
880                  */\r
881                 public function get fragment() : String\r
882                 { \r
883                         return URI.unescapeChars(_fragment);\r
884                 }\r
885                 public function set fragment(fragmentStr:String) : void\r
886                 {\r
887                         _fragment = URI.fastEscapeChars(fragmentStr, URIfragmentExcludedBitmap);\r
888 \r
889                         // both hierarchical and non-hierarchical URI's can\r
890                         // have a fragment.  Do not set the hierState.\r
891                 }\r
892                 \r
893                 \r
894                 /**\r
895                  * The non-hierarchical part of the URI.  For example, if\r
896                  * this URI object represents "mailto:somebody@company.com",\r
897                  * this will contain "somebody@company.com".  This is valid only\r
898                  * for non-hierarchical URI's.  \r
899                  */\r
900                 public function get nonHierarchical() : String\r
901                 { \r
902                         return URI.unescapeChars(_nonHierarchical);\r
903                 }\r
904                 public function set nonHierarchical(nonHier:String) : void\r
905                 {\r
906                         _nonHierarchical = URI.fastEscapeChars(nonHier, URInonHierexcludedBitmap);\r
907                         \r
908                         // This is a non-hierarchical URI.\r
909                         this.hierState = false;\r
910                 }\r
911                 \r
912                 \r
913                 /**\r
914                  * Quick shorthand accessor to set the parts of this URI.\r
915                  * The given parts are assumed to be in unescaped form.  If\r
916                  * the URI is non-hierarchical (e.g. mailto:) you will need\r
917                  * to call SetScheme() and SetNonHierarchical().\r
918                  */\r
919                 public function setParts(schemeStr:String, authorityStr:String,\r
920                                 portStr:String, pathStr:String, queryStr:String,\r
921                                 fragmentStr:String) : void\r
922                 {\r
923                         this.scheme = schemeStr;\r
924                         this.authority = authorityStr;\r
925                         this.port = portStr;\r
926                         this.path = pathStr;\r
927                         this.query = queryStr;\r
928                         this.fragment = fragmentStr;\r
929 \r
930                         hierState = true;\r
931                 }\r
932                 \r
933                 \r
934                 /**\r
935                  * URI escapes the given character string.  This is similar in function\r
936                  * to the global encodeURIComponent() function in ActionScript, but is\r
937                  * slightly different in regards to which characters get escaped.  This\r
938                  * escapes the characters specified in the URIbaselineExluded set (see class\r
939                  * static members).  This is needed for this class to work properly.\r
940                  * \r
941                  * <p>If a different set of characters need to be used for the escaping,\r
942                  * you may use fastEscapeChars() and specify a custom URIEncodingBitmap\r
943                  * that contains the characters your application needs escaped.</p>\r
944                  * \r
945                  * <p>Never pass a full URI to this function.  A URI can only be properly\r
946                  * escaped/unescaped when split into its component parts (see RFC 3986\r
947                  * section 2.4).  This is due to the fact that the URI component separators\r
948                  * could be characters that would normally need to be escaped.</p>\r
949                  * \r
950                  * @param unescaped character string to be escaped.\r
951                  * \r
952                  * @return      escaped character string\r
953                  * \r
954                  * @see encodeURIComponent\r
955                  * @see fastEscapeChars\r
956                  */\r
957                 static public function escapeChars(unescaped:String) : String\r
958                 {\r
959                         // This uses the excluded set by default.\r
960                         return fastEscapeChars(unescaped, URI.URIbaselineExcludedBitmap);\r
961                 }\r
962                 \r
963 \r
964                 /**\r
965                  * Unescape any URI escaped characters in the given character\r
966                  * string.\r
967                  * \r
968                  * <p>Never pass a full URI to this function.  A URI can only be properly\r
969                  * escaped/unescaped when split into its component parts (see RFC 3986\r
970                  * section 2.4).  This is due to the fact that the URI component separators\r
971                  * could be characters that would normally need to be escaped.</p>\r
972                  * \r
973                  * @param escaped the escaped string to be unescaped.\r
974                  * \r
975                  * @return      unescaped string.\r
976                  */\r
977                 static public function unescapeChars(escaped:String /*, onlyHighASCII:Boolean = false*/) : String\r
978                 {\r
979                         // We can just use the default AS function.  It seems to\r
980                         // decode everything correctly\r
981                         var unescaped:String;\r
982                         unescaped = decodeURIComponent(escaped);\r
983                         return unescaped;\r
984                 }\r
985                 \r
986                 /**\r
987                  * Performance focused function that escapes the given character\r
988                  * string using the given URIEncodingBitmap as the rule for what\r
989                  * characters need to be escaped.  This function is used by this\r
990                  * class and can be used externally to this class to perform\r
991                  * escaping on custom character sets.\r
992                  * \r
993                  * <p>Never pass a full URI to this function.  A URI can only be properly\r
994                  * escaped/unescaped when split into its component parts (see RFC 3986\r
995                  * section 2.4).  This is due to the fact that the URI component separators\r
996                  * could be characters that would normally need to be escaped.</p>\r
997                  * \r
998                  * @param unescaped             the unescaped string to be escaped\r
999                  * @param bitmap                the set of characters that need to be escaped\r
1000                  * \r
1001                  * @return      the escaped string.\r
1002                  */\r
1003                 static public function fastEscapeChars(unescaped:String, bitmap:URIEncodingBitmap) : String\r
1004                 {\r
1005                         var escaped:String = "";\r
1006                         var c:String;\r
1007                         var x:int, i:int;\r
1008                         \r
1009                         for (i = 0; i < unescaped.length; i++)\r
1010                         {\r
1011                                 c = unescaped.charAt(i);\r
1012                                 \r
1013                                 x = bitmap.ShouldEscape(c);\r
1014                                 if (x)\r
1015                                 {\r
1016                                         c = x.toString(16);\r
1017                                         if (c.length == 1)\r
1018                                                 c = "0" + c;\r
1019                                                 \r
1020                                         c = "%" + c;\r
1021                                         c = c.toUpperCase();\r
1022                                 }\r
1023                                 \r
1024                                 escaped += c;\r
1025                         }\r
1026                         \r
1027                         return escaped;\r
1028                 }\r
1029 \r
1030                 \r
1031                 /**\r
1032                  * Is this URI of a particular scheme type?  For example,\r
1033                  * passing "http" to a URI object that represents the URI\r
1034                  * "http://site.com/" would return true.\r
1035                  * \r
1036                  * @param scheme        scheme to check for\r
1037                  * \r
1038                  * @return true if this URI object is of the given type, false\r
1039                  * otherwise.\r
1040                  */\r
1041                 public function isOfType(scheme:String) : Boolean\r
1042                 {\r
1043                         // Schemes are never case sensitive.  Ignore case.\r
1044                         scheme = scheme.toLowerCase();\r
1045                         return (this._scheme == scheme);\r
1046                 }\r
1047 \r
1048 \r
1049                 /**\r
1050                  * Get the value for the specified named in the query part.  This\r
1051                  * assumes the query part of the URI is in the common\r
1052                  * "name1=value1&name2=value2" syntax.  Do not call this function\r
1053                  * if you are using a custom query syntax.\r
1054                  * \r
1055                  * @param name  name of the query value to get.\r
1056                  * \r
1057                  * @return the value of the query name, empty string if the\r
1058                  * query name does not exist.\r
1059                  */\r
1060                 public function getQueryValue(name:String) : String\r
1061                 {\r
1062                         var map:Object;\r
1063                         var item:String;\r
1064                         var value:String;\r
1065                 \r
1066                         map = getQueryByMap();\r
1067                 \r
1068                         for (item in map)\r
1069                         {\r
1070                                 if (item == name)\r
1071                                 {\r
1072                                         value = map[item];\r
1073                                         return value;\r
1074                                 }\r
1075                         }\r
1076                 \r
1077                         // Didn't find the specified key\r
1078                         return new String("");\r
1079                 }\r
1080                 \r
1081 \r
1082                 /**\r
1083                  * Set the given value on the given query name.  If the given name\r
1084                  * does not exist, it will automatically add this name/value pair\r
1085                  * to the query.  If null is passed as the value, it will remove\r
1086                  * the given item from the query.\r
1087                  * \r
1088                  * <p>This automatically escapes any characters that may conflict with\r
1089                  * the query syntax so that they are "safe" within the query.  The\r
1090                  * strings passed are assumed to be literal unescaped name and value.</p>\r
1091                  * \r
1092                  * @param name  name of the query value to set\r
1093                  * @param value value of the query item to set.  If null, this will\r
1094                  * force the removal of this item from the query.\r
1095                  */\r
1096                 public function setQueryValue(name:String, value:String) : void\r
1097                 {\r
1098                         var map:Object;\r
1099 \r
1100                         map = getQueryByMap();\r
1101                 \r
1102                         // If the key doesn't exist yet, this will create a new pair in\r
1103                         // the map.  If it does exist, this will overwrite the previous\r
1104                         // value, which is what we want.\r
1105                         map[name] = value;\r
1106                 \r
1107                         setQueryByMap(map);\r
1108                 }\r
1109 \r
1110                 \r
1111                 /**\r
1112                  * Get the query of the URI in an Object class that allows for easy\r
1113                  * access to the query data via Object accessors.  For example:\r
1114                  * \r
1115                  * <listing>\r
1116                  * var query:Object = uri.getQueryByMap();\r
1117                  * var value:String = query["param"];    // get a value\r
1118                  * query["param2"] = "foo";   // set a new value\r
1119                  * </listing>\r
1120                  * \r
1121                  * @return Object that contains the name/value pairs of the query.\r
1122                  * \r
1123                  * @see #setQueryByMap\r
1124                  * @see #getQueryValue\r
1125                  * @see #setQueryValue\r
1126                  */\r
1127                 public function getQueryByMap() : Object\r
1128                 {\r
1129                         var queryStr:String;\r
1130                         var pair:String;\r
1131                         var pairs:Array;\r
1132                         var item:Array;\r
1133                         var name:String, value:String;\r
1134                         var index:int;\r
1135                         var map:Object = new Object();\r
1136                 \r
1137                 \r
1138                         // We need the raw query string, no unescaping.\r
1139                         queryStr = this._query;\r
1140                         \r
1141                         pairs = queryStr.split('&');\r
1142                         for each (pair in pairs)\r
1143                         {\r
1144                                 if (pair.length == 0)\r
1145                                   continue;\r
1146                                   \r
1147                                 item = pair.split('=');\r
1148                                 \r
1149                                 if (item.length > 0)\r
1150                                         name = item[0];\r
1151                                 else\r
1152                                         continue;  // empty array\r
1153                                 \r
1154                                 if (item.length > 1)\r
1155                                         value = item[1];\r
1156                                 else\r
1157                                         value = "";\r
1158                                         \r
1159                                 name = queryPartUnescape(name);\r
1160                                 value = queryPartUnescape(value);\r
1161                                 \r
1162                                 map[name] = value;\r
1163                         }\r
1164         \r
1165                         return map;\r
1166                 }\r
1167                 \r
1168 \r
1169                 /**\r
1170                  * Set the query part of this URI using the given object as the\r
1171                  * content source.  Any member of the object that has a value of\r
1172                  * null will not be in the resulting query.\r
1173                  * \r
1174                  * @param map   object that contains the name/value pairs as\r
1175                  *    members of that object.\r
1176                  * \r
1177                  * @see #getQueryByMap\r
1178                  * @see #getQueryValue\r
1179                  * @see #setQueryValue\r
1180                  */\r
1181                 public function setQueryByMap(map:Object) : void\r
1182                 {\r
1183                         var item:String;\r
1184                         var name:String, value:String;\r
1185                         var queryStr:String = "";\r
1186                         var tmpPair:String;\r
1187                         var foo:String;\r
1188                 \r
1189                         for (item in map)\r
1190                         {\r
1191                                 name = item;\r
1192                                 value = map[item];\r
1193                 \r
1194                                 if (value == null)\r
1195                                         value = "";\r
1196                                 \r
1197                                 // Need to escape the name/value pair so that they\r
1198                                 // don't conflict with the query syntax (specifically\r
1199                                 // '=', '&', and <whitespace>).\r
1200                                 name = queryPartEscape(name);\r
1201                                 value = queryPartEscape(value);\r
1202                                 \r
1203                                 tmpPair = name;\r
1204                                 \r
1205                                 if (value.length > 0)\r
1206                                 {\r
1207                                         tmpPair += "=";\r
1208                                         tmpPair += value;\r
1209                                 }\r
1210 \r
1211                                 if (queryStr.length != 0)\r
1212                                         queryStr += '&';  // Add the separator\r
1213                 \r
1214                                 queryStr += tmpPair;\r
1215                         }\r
1216                 \r
1217                         // We don't want to escape.  We already escaped the\r
1218                         // individual name/value pairs.  If we escaped the\r
1219                         // query string again by assigning it to "query",\r
1220                         // we would have double escaping.\r
1221                         _query = queryStr;\r
1222                 }\r
1223                 \r
1224                 \r
1225                 /**\r
1226                  * Similar to Escape(), except this also escapes characters that\r
1227                  * would conflict with the name/value pair query syntax.  This is\r
1228                  * intended to be called on each individual "name" and "value"\r
1229                  * in the query making sure that nothing in the name or value\r
1230                  * strings contain characters that would conflict with the query\r
1231                  * syntax (e.g. '=' and '&').\r
1232                  * \r
1233                  * @param unescaped             unescaped string that is to be escaped.\r
1234                  * \r
1235                  * @return escaped string.\r
1236                  * \r
1237                  * @see #queryUnescape\r
1238                  */\r
1239                 static public function queryPartEscape(unescaped:String) : String\r
1240                 {\r
1241                         var escaped:String = unescaped;\r
1242                         escaped = URI.fastEscapeChars(unescaped, URI.URIqueryPartExcludedBitmap);\r
1243                         return escaped;\r
1244                 }\r
1245                 \r
1246 \r
1247                 /**\r
1248                  * Unescape the individual name/value string pairs.\r
1249                  * \r
1250                  * @param escaped       escaped string to be unescaped\r
1251                  * \r
1252                  * @return unescaped string\r
1253                  * \r
1254                  * @see #queryEscape\r
1255                  */\r
1256                 static public function queryPartUnescape(escaped:String) : String\r
1257                 {\r
1258                         var unescaped:String = escaped;\r
1259                         unescaped = unescapeChars(unescaped);\r
1260                         return unescaped;\r
1261                 }\r
1262                 \r
1263                 /**\r
1264                  * Output this URI as a string.  The resulting string is properly\r
1265                  * escaped and well formed for machine processing.\r
1266                  */\r
1267                 public function toString() : String\r
1268                 {\r
1269                         if (this == null)\r
1270                                 return "";\r
1271                         else\r
1272                                 return toStringInternal(false);\r
1273                 }\r
1274                 \r
1275                 /**\r
1276                  * Output the URI as a string that is easily readable by a human.\r
1277                  * This outputs the URI with all escape sequences unescaped to\r
1278                  * their character representation.  This makes the URI easier for\r
1279                  * a human to read, but the URI could be completely invalid\r
1280                  * because some unescaped characters may now cause ambiguous parsing.\r
1281                  * This function should only be used if you want to display a URI to\r
1282                  * a user.  This function should never be used outside that specific\r
1283                  * case.\r
1284                  * \r
1285                  * @return the URI in string format with all escape sequences\r
1286                  * unescaped.\r
1287                  * \r
1288                  * @see #toString\r
1289                  */\r
1290                 public function toDisplayString() : String\r
1291                 {\r
1292                         return toStringInternal(true);\r
1293                 }\r
1294                 \r
1295                 \r
1296                 /**\r
1297                  * @private\r
1298                  * \r
1299                  * The guts of toString()\r
1300                  */\r
1301                 protected function toStringInternal(forDisplay:Boolean) : String\r
1302                 {\r
1303                         var uri:String = "";\r
1304                         var part:String = "";\r
1305                 \r
1306                         if (isHierarchical() == false)\r
1307                         {\r
1308                                 // non-hierarchical URI\r
1309                 \r
1310                                 uri += (forDisplay ? this.scheme : _scheme);\r
1311                                 uri += ":";\r
1312                                 uri += (forDisplay ? this.nonHierarchical : _nonHierarchical);\r
1313                         }\r
1314                         else\r
1315                         {\r
1316                                 // Hierarchical URI\r
1317                 \r
1318                                 if (isRelative() == false)\r
1319                                 {\r
1320                                         // If it is not a relative URI, then we want the scheme and\r
1321                                         // authority parts in the string.  If it is relative, we\r
1322                                         // do NOT want this stuff.\r
1323                 \r
1324                                         if (_scheme.length != 0)\r
1325                                         {\r
1326                                                 part = (forDisplay ? this.scheme : _scheme);\r
1327                                                 uri += part + ":";\r
1328                                         }\r
1329                 \r
1330                                         if (_authority.length != 0 || isOfType("file"))\r
1331                                         {\r
1332                                                 uri += "//";\r
1333                 \r
1334                                                 // Add on any username/password associated with this\r
1335                                                 // authority\r
1336                                                 if (_username.length != 0)\r
1337                                                 {\r
1338                                                         part = (forDisplay ? this.username : _username);\r
1339                                                         uri += part;\r
1340                 \r
1341                                                         if (_password.length != 0)\r
1342                                                         {\r
1343                                                                 part = (forDisplay ? this.password : _password);\r
1344                                                                 uri += ":" + part;\r
1345                                                         }\r
1346                 \r
1347                                                         uri += "@";\r
1348                                                 }\r
1349                 \r
1350                                                 // add the authority\r
1351                                                 part = (forDisplay ? this.authority : _authority);\r
1352                                                 uri += part;\r
1353                 \r
1354                                                 // Tack on the port number, if any\r
1355                                                 if (port.length != 0)\r
1356                                                         uri += ":" + port;\r
1357                                         }\r
1358                                 }\r
1359                 \r
1360                                 // Tack on the path\r
1361                                 part = (forDisplay ? this.path : _path);\r
1362                                 uri += part;\r
1363                 \r
1364                         } // end hierarchical part\r
1365                 \r
1366                         // Both non-hier and hierarchical have query and fragment parts\r
1367                 \r
1368                         // Add on the query and fragment parts\r
1369                         if (_query.length != 0)\r
1370                         {\r
1371                                 part = (forDisplay ? this.query : _query);\r
1372                                 uri += "?" + part;\r
1373                         }\r
1374                 \r
1375                         if (fragment.length != 0)\r
1376                         {\r
1377                                 part = (forDisplay ? this.fragment : _fragment);\r
1378                                 uri += "#" + part;\r
1379                         }\r
1380                 \r
1381                         return uri;\r
1382                 }\r
1383         \r
1384                 /**\r
1385                  * Forcefully ensure that this URI is properly escaped.\r
1386                  * \r
1387                  * <p>Sometimes URI's are constructed by hand using strings outside\r
1388                  * this class.  In those cases, it is unlikely the URI has been\r
1389                  * properly escaped.  This function forcefully escapes this URI\r
1390                  * by unescaping each part and then re-escaping it.  If the URI\r
1391                  * did not have any escaping, the first unescape will do nothing\r
1392                  * and then the re-escape will properly escape everything.  If\r
1393                  * the URI was already escaped, the unescape and re-escape will\r
1394                  * essentally be a no-op.  This provides a safe way to make sure\r
1395                  * a URI is in the proper escaped form.</p>\r
1396                  */\r
1397                 public function forceEscape() : void\r
1398                 {\r
1399                         // The accessors for each of the members will unescape\r
1400                         // and then re-escape as we get and assign them.\r
1401                         \r
1402                         // Handle the parts that are common for both hierarchical\r
1403                         // and non-hierarchical URI's\r
1404                         this.scheme = this.scheme;\r
1405                         this.setQueryByMap(this.getQueryByMap());\r
1406                         this.fragment = this.fragment;\r
1407                         \r
1408                         if (isHierarchical())\r
1409                         {\r
1410                                 this.authority = this.authority;\r
1411                                 this.path = this.path;\r
1412                                 this.port = this.port;\r
1413                                 this.username = this.username;\r
1414                                 this.password = this.password;\r
1415                         }\r
1416                         else\r
1417                         {\r
1418                                 this.nonHierarchical = this.nonHierarchical;\r
1419                         }\r
1420                 }\r
1421                 \r
1422                 \r
1423                 /**\r
1424                  * Does this URI point to a resource of the given file type?\r
1425                  * Given a file extension (or just a file name, this will strip the\r
1426                  * extension), check to see if this URI points to a file of that\r
1427                  * type.\r
1428                  * \r
1429                  * @param extension     string that contains a file extension with or\r
1430                  * without a dot ("html" and ".html" are both valid), or a file\r
1431                  * name with an extension (e.g. "index.html").\r
1432                  * \r
1433                  * @return true if this URI points to a resource with the same file\r
1434                  * file extension as the extension provided, false otherwise.\r
1435                  */\r
1436                 public function isOfFileType(extension:String) : Boolean\r
1437                 {\r
1438                         var thisExtension:String;\r
1439                         var index:int;\r
1440                 \r
1441                         index = extension.lastIndexOf(".");\r
1442                         if (index != -1)\r
1443                         {\r
1444                                 // Strip the extension\r
1445                                 extension = extension.substr(index + 1);\r
1446                         }\r
1447                         else\r
1448                         {\r
1449                                 // The caller passed something without a dot in it.  We\r
1450                                 // will assume that it is just a plain extension (e.g. "html").\r
1451                                 // What they passed is exactly what we want\r
1452                         }\r
1453                 \r
1454                         thisExtension = getExtension(true);\r
1455                 \r
1456                         if (thisExtension == "")\r
1457                                 return false;\r
1458                 \r
1459                         // Compare the extensions ignoring case\r
1460                         if (compareStr(thisExtension, extension, false) == 0)\r
1461                                 return true;\r
1462                         else\r
1463                                 return false;\r
1464                 }\r
1465                 \r
1466                 \r
1467                 /**\r
1468                  * Get the ".xyz" file extension from the filename in the URI.\r
1469                  * For example, if we have the following URI:\r
1470                  * \r
1471                  * <listing>http://something.com/path/to/my/page.html?form=yes&name=bob#anchor</listing>\r
1472                  * \r
1473                  * <p>This will return ".html".</p>\r
1474                  * \r
1475                  * @param minusDot   If true, this will strip the dot from the extension.\r
1476                  * If true, the above example would have returned "html".\r
1477                  * \r
1478                  * @return  the file extension\r
1479                  */\r
1480                 public function getExtension(minusDot:Boolean = false) : String\r
1481                 {\r
1482                         var filename:String = getFilename();\r
1483                         var extension:String;\r
1484                         var index:int;\r
1485                 \r
1486                         if (filename == "")\r
1487                                 return String("");\r
1488                 \r
1489                         index = filename.lastIndexOf(".");\r
1490                 \r
1491                         // If it doesn't have an extension, or if it is a "hidden" file,\r
1492                         // it doesn't have an extension.  Hidden files on unix start with\r
1493                         // a dot (e.g. ".login").\r
1494                         if (index == -1 || index == 0)\r
1495                                 return String("");\r
1496                 \r
1497                         extension = filename.substr(index);\r
1498                 \r
1499                         // If the caller does not want the dot, remove it.\r
1500                         if (minusDot && extension.charAt(0) == ".")\r
1501                                 extension = extension.substr(1);\r
1502                 \r
1503                         return extension;\r
1504                 }\r
1505                 \r
1506                 /**\r
1507                  * Quick function to retrieve the file name off the end of a URI.\r
1508                  * \r
1509                  * <p>For example, if the URI is:</p>\r
1510                  * <listing>http://something.com/some/path/to/my/file.html</listing>\r
1511                  * <p>this function will return "file.html".</p>\r
1512                  * \r
1513                  * @param minusExtension true if the file extension should be stripped\r
1514                  * \r
1515                  * @return the file name.  If this URI is a directory, the return\r
1516                  * value will be empty string.\r
1517                  */\r
1518                 public function getFilename(minusExtension:Boolean = false) : String\r
1519                 {\r
1520                         if (isDirectory())\r
1521                                 return String("");\r
1522                 \r
1523                         var pathStr:String = this.path;\r
1524                         var filename:String;\r
1525                         var index:int;\r
1526                 \r
1527                         // Find the last path separator.\r
1528                         index = pathStr.lastIndexOf("/");\r
1529                 \r
1530                         if (index != -1)\r
1531                                 filename = pathStr.substr(index + 1);\r
1532                         else\r
1533                                 filename = pathStr;\r
1534                 \r
1535                         if (minusExtension)\r
1536                         {\r
1537                                 // The caller has requested that the extension be removed\r
1538                                 index = filename.lastIndexOf(".");\r
1539                 \r
1540                                 if (index != -1)\r
1541                                         filename = filename.substr(0, index);\r
1542                         }\r
1543                 \r
1544                         return filename;\r
1545                 }\r
1546                 \r
1547                 \r
1548                 /**\r
1549                  * @private\r
1550                  * Helper function to compare strings.\r
1551                  * \r
1552                  * @return true if the two strings are identical, false otherwise.\r
1553                  */\r
1554                 static protected function compareStr(str1:String, str2:String,\r
1555                         sensitive:Boolean = true) : Boolean\r
1556                 {\r
1557                         if (sensitive == false)\r
1558                         {\r
1559                                 str1 = str1.toLowerCase();\r
1560                                 str2 = str2.toLowerCase();\r
1561                         }\r
1562                         \r
1563                         return (str1 == str2)\r
1564                 }\r
1565                 \r
1566                 /**\r
1567                  * Based on the type of this URI (http, ftp, etc.) get\r
1568                  * the default port used for that protocol.  This is\r
1569                  * just intended to be a helper function for the most\r
1570                  * common cases.\r
1571                  */\r
1572                 public function getDefaultPort() : String\r
1573                 {\r
1574                         if (_scheme == "http")\r
1575                                 return String("80");\r
1576                         else if (_scheme == "ftp")\r
1577                                 return String("21");\r
1578                         else if (_scheme == "file")\r
1579                                 return String("");\r
1580                         else if (_scheme == "sftp")\r
1581                                 return String("22"); // ssh standard port\r
1582                         else\r
1583                         {\r
1584                                 // Don't know the port for this URI type\r
1585                                 return String("");\r
1586                         }\r
1587                 }\r
1588                 \r
1589                 /**\r
1590                  * @private\r
1591                  * \r
1592                  * This resolves the given URI if the application has a\r
1593                  * resolver interface defined.  This function does not\r
1594                  * modify the passed in URI and returns a new URI.\r
1595                  */\r
1596                 static protected function resolve(uri:URI) : URI\r
1597                 {\r
1598                         var copy:URI = new URI();\r
1599                         copy.copyURI(uri);\r
1600                         \r
1601                         if (_resolver != null)\r
1602                         {\r
1603                                 // A resolver class has been registered.  Call it.\r
1604                                 return _resolver.resolve(copy);\r
1605                         }\r
1606                         else\r
1607                         {\r
1608                                 // No resolver.  Nothing to do, but we don't\r
1609                                 // want to reuse the one passed in.\r
1610                                 return copy;\r
1611                         }\r
1612                 }\r
1613                 \r
1614                 /**\r
1615                  * Accessor to set and get the resolver object used by all URI\r
1616                  * objects to dynamically resolve URI's before comparison.\r
1617                  */\r
1618                 static public function set resolver(resolver:IURIResolver) : void\r
1619                 {\r
1620                         _resolver = resolver;\r
1621                 }\r
1622                 static public function get resolver() : IURIResolver\r
1623                 {\r
1624                         return _resolver;\r
1625                 }\r
1626                 \r
1627                 /**\r
1628                  * Given another URI, return this URI object's relation to the one given.\r
1629                  * URI's can have 1 of 4 possible relationships.  They can be unrelated,\r
1630                  * equal, parent, or a child of the given URI.\r
1631                  * \r
1632                  * @param uri   URI to compare this URI object to.\r
1633                  * @param caseSensitive  true if the URI comparison should be done\r
1634                  * taking case into account, false if the comparison should be\r
1635                  * performed case insensitive.\r
1636                  * \r
1637                  * @return URI.NOT_RELATED, URI.CHILD, URI.PARENT, or URI.EQUAL\r
1638                  */\r
1639                 public function getRelation(uri:URI, caseSensitive:Boolean = true) : int\r
1640                 {\r
1641                         // Give the app a chance to resolve these URI's before we compare them.\r
1642                         var thisURI:URI = URI.resolve(this);\r
1643                         var thatURI:URI = URI.resolve(uri);\r
1644                         \r
1645                         if (thisURI.isRelative() || thatURI.isRelative())\r
1646                         {\r
1647                                 // You cannot compare relative URI's due to their lack of context.\r
1648                                 // You could have two relative URI's that look like:\r
1649                                 //              ../../images/\r
1650                                 //              ../../images/marketing/logo.gif\r
1651                                 // These may appear related, but you have no overall context\r
1652                                 // from which to make the comparison.  The first URI could be\r
1653                                 // from one site and the other URI could be from another site.\r
1654                                 return URI.NOT_RELATED;\r
1655                         }\r
1656                         else if (thisURI.isHierarchical() == false || thatURI.isHierarchical() == false)\r
1657                         {\r
1658                                 // One or both of the URI's are non-hierarchical.\r
1659                                 if (((thisURI.isHierarchical() == false) && (thatURI.isHierarchical() == true)) ||\r
1660                                         ((thisURI.isHierarchical() == true) && (thatURI.isHierarchical() == false)))\r
1661                                 {\r
1662                                         // XOR.  One is hierarchical and the other is\r
1663                                         // non-hierarchical.  They cannot be compared.\r
1664                                         return URI.NOT_RELATED;\r
1665                                 }\r
1666                                 else\r
1667                                 {\r
1668                                         // They are both non-hierarchical\r
1669                                         if (thisURI.scheme != thatURI.scheme)\r
1670                                                 return URI.NOT_RELATED;\r
1671                 \r
1672                                         if (thisURI.nonHierarchical != thatURI.nonHierarchical)\r
1673                                                 return URI.NOT_RELATED;\r
1674                                                 \r
1675                                         // The two non-hierarcical URI's are equal.\r
1676                                         return URI.EQUAL;\r
1677                                 }\r
1678                         }\r
1679                         \r
1680                         // Ok, this URI and the one we are being compared to are both\r
1681                         // absolute hierarchical URI's.\r
1682                 \r
1683                         if (thisURI.scheme != thatURI.scheme)\r
1684                                 return URI.NOT_RELATED;\r
1685                 \r
1686                         if (thisURI.authority != thatURI.authority)\r
1687                                 return URI.NOT_RELATED;\r
1688                 \r
1689                         var thisPort:String = thisURI.port;\r
1690                         var thatPort:String = thatURI.port;\r
1691                         \r
1692                         // Different ports are considered completely different servers.\r
1693                         if (thisPort == "")\r
1694                                 thisPort = thisURI.getDefaultPort();\r
1695                         if (thatPort == "")\r
1696                                 thatPort = thatURI.getDefaultPort();\r
1697                 \r
1698                         // Check to see if the port is the default port.\r
1699                         if (thisPort != thatPort)\r
1700                                 return URI.NOT_RELATED;\r
1701                 \r
1702                         if (compareStr(thisURI.path, thatURI.path, caseSensitive))\r
1703                                 return URI.EQUAL;\r
1704                 \r
1705                         // Special case check.  If we are here, the scheme, authority,\r
1706                         // and port match, and it is not a relative path, but the\r
1707                         // paths did not match.  There is a special case where we\r
1708                         // could have:\r
1709                         //              http://something.com/\r
1710                         //              http://something.com\r
1711                         // Technically, these are equal.  So lets, check for this case.\r
1712                         var thisPath:String = thisURI.path;\r
1713                         var thatPath:String = thatURI.path;\r
1714                 \r
1715                         if ( (thisPath == "/" || thatPath == "/") &&\r
1716                                  (thisPath == "" || thatPath == "") )\r
1717                         {\r
1718                                 // We hit the special case.  These two are equal.\r
1719                                 return URI.EQUAL;\r
1720                         }\r
1721                 \r
1722                         // Ok, the paths do not match, but one path may be a parent/child\r
1723                         // of the other.  For example, we may have:\r
1724                         //              http://something.com/path/to/homepage/\r
1725                         //              http://something.com/path/to/homepage/images/logo.gif\r
1726                         // In this case, the first is a parent of the second (or the second\r
1727                         // is a child of the first, depending on which you compare to the\r
1728                         // other).  To make this comparison, we must split the path into\r
1729                         // its component parts (split the string on the '/' path delimiter).\r
1730                         // We then compare the \r
1731                         var thisParts:Array, thatParts:Array;\r
1732                         var thisPart:String, thatPart:String;\r
1733                         var i:int;\r
1734                 \r
1735                         thisParts = thisPath.split("/");\r
1736                         thatParts = thatPath.split("/");\r
1737                 \r
1738                         if (thisParts.length > thatParts.length)\r
1739                         {\r
1740                                 thatPart = thatParts[thatParts.length - 1];\r
1741                                 if (thatPart.length > 0)\r
1742                                 {\r
1743                                         // if the last part is not empty, the passed URI is\r
1744                                         // not a directory.  There is no way the passed URI\r
1745                                         // can be a parent.\r
1746                                         return URI.NOT_RELATED;\r
1747                                 }\r
1748                                 else\r
1749                                 {\r
1750                                         // Remove the empty trailing part\r
1751                                         thatParts.pop();\r
1752                                 }\r
1753                                 \r
1754                                 // This may be a child of the one passed in\r
1755                                 for (i = 0; i < thatParts.length; i++)\r
1756                                 {\r
1757                                         thisPart = thisParts[i];\r
1758                                         thatPart = thatParts[i];\r
1759                                                 \r
1760                                         if (compareStr(thisPart, thatPart, caseSensitive) == false)\r
1761                                                 return URI.NOT_RELATED;\r
1762                                 }\r
1763                 \r
1764                                 return URI.CHILD;\r
1765                         }\r
1766                         else if (thisParts.length < thatParts.length)\r
1767                         {\r
1768                                 thisPart = thisParts[thisParts.length - 1];\r
1769                                 if (thisPart.length > 0)\r
1770                                 {\r
1771                                         // if the last part is not empty, this URI is not a\r
1772                                         // directory.  There is no way this object can be\r
1773                                         // a parent.\r
1774                                         return URI.NOT_RELATED;\r
1775                                 }\r
1776                                 else\r
1777                                 {\r
1778                                         // Remove the empty trailing part\r
1779                                         thisParts.pop();\r
1780                                 }\r
1781                                 \r
1782                                 // This may be the parent of the one passed in\r
1783                                 for (i = 0; i < thisParts.length; i++)\r
1784                                 {\r
1785                                         thisPart = thisParts[i];\r
1786                                         thatPart = thatParts[i];\r
1787                 \r
1788                                         if (compareStr(thisPart, thatPart, caseSensitive) == false)\r
1789                                                 return URI.NOT_RELATED;\r
1790                                 }\r
1791                                 \r
1792                                 return URI.PARENT;\r
1793                         }\r
1794                         else\r
1795                         {\r
1796                                 // Both URI's have the same number of path components, but\r
1797                                 // it failed the equivelence check above.  This means that\r
1798                                 // the two URI's are not related.\r
1799                                 return URI.NOT_RELATED;\r
1800                         }\r
1801                         \r
1802                         // If we got here, the scheme and authority are the same,\r
1803                         // but the paths pointed to two different locations that\r
1804                         // were in different parts of the file system tree\r
1805                         return URI.NOT_RELATED;\r
1806                 }\r
1807                 \r
1808                 /**\r
1809                  * Given another URI, return the common parent between this one\r
1810                  * and the provided URI.\r
1811                  * \r
1812                  * @param uri the other URI from which to find a common parent\r
1813                  * @para caseSensitive true if this operation should be done\r
1814                  * with case sensitive comparisons.\r
1815                  * \r
1816                  * @return the parent URI if successful, null otherwise.\r
1817                  */\r
1818                 public function getCommonParent(uri:URI, caseSensitive:Boolean = true) : URI\r
1819                 {\r
1820                         var thisURI:URI = URI.resolve(this);\r
1821                         var thatURI:URI = URI.resolve(uri);\r
1822                 \r
1823                         if(!thisURI.isAbsolute() || !thatURI.isAbsolute() ||\r
1824                                 thisURI.isHierarchical() == false ||\r
1825                                 thatURI.isHierarchical() == false)\r
1826                         {\r
1827                                 // Both URI's must be absolute hierarchical for this to\r
1828                                 // make sense.\r
1829                                 return null;\r
1830                         }\r
1831                         \r
1832                         var relation:int = thisURI.getRelation(thatURI);\r
1833                         if (relation == URI.NOT_RELATED)\r
1834                         {\r
1835                                 // The given URI is not related to this one.  No\r
1836                                 // common parent.\r
1837                                 return null;\r
1838                         }\r
1839                 \r
1840                         thisURI.chdir(".");\r
1841                         thatURI.chdir(".");\r
1842                         \r
1843                         var strBefore:String, strAfter:String;\r
1844                         do\r
1845                         {\r
1846                                 relation = thisURI.getRelation(thatURI, caseSensitive);\r
1847                                 if(relation == URI.EQUAL || relation == URI.PARENT)\r
1848                                         break;\r
1849                 \r
1850                                 // If strBefore and strAfter end up being the same,\r
1851                                 // we know we are at the root of the path because\r
1852                                 // chdir("..") is doing nothing.\r
1853                                 strBefore = thisURI.toString();\r
1854                                 thisURI.chdir("..");\r
1855                                 strAfter = thisURI.toString();\r
1856                         }\r
1857                         while(strBefore != strAfter);\r
1858                 \r
1859                         return thisURI;\r
1860                 }\r
1861                 \r
1862                 \r
1863                 /**\r
1864                  * This function is used to move around in a URI in a way similar\r
1865                  * to the 'cd' or 'chdir' commands on Unix.  These operations are\r
1866                  * completely string based, using the context of the URI to\r
1867                  * determine the position within the path.  The heuristics used\r
1868                  * to determine the action are based off Appendix C in RFC 2396.\r
1869                  * \r
1870                  * <p>URI paths that end in '/' are considered paths that point to\r
1871                  * directories, while paths that do not end in '/' are files.  For\r
1872                  * example, if you execute chdir("d") on the following URI's:<br/>\r
1873                  *    1.  http://something.com/a/b/c/  (directory)<br/>\r
1874                  *    2.  http://something.com/a/b/c  (not directory)<br/>\r
1875                  * you will get:<br/>\r
1876                  *    1.  http://something.com/a/b/c/d<br/>\r
1877                  *    2.  http://something.com/a/b/d<br/></p>\r
1878                  * \r
1879                  * <p>See RFC 2396, Appendix C for more info.</p>\r
1880                  * \r
1881                  * @param reference     the URI or path to "cd" to.\r
1882                  * @param escape true if the passed reference string should be URI\r
1883                  * escaped before using it.\r
1884                  * \r
1885                  * @return true if the chdir was successful, false otherwise.\r
1886                  */\r
1887                 public function chdir(reference:String, escape:Boolean = false) : Boolean\r
1888                 {\r
1889                         var uriReference:URI;\r
1890                         var ref:String = reference;\r
1891                 \r
1892                         if (escape)\r
1893                                 ref = URI.escapeChars(reference);\r
1894                 \r
1895                         if (ref == "")\r
1896                         {\r
1897                                 // NOOP\r
1898                                 return true;\r
1899                         }\r
1900                         else if (ref.substr(0, 2) == "//")\r
1901                         {\r
1902                                 // Special case.  This is an absolute URI but without the scheme.\r
1903                                 // Take the scheme from this URI and tack it on.  This is\r
1904                                 // intended to make working with chdir() a little more\r
1905                                 // tolerant.\r
1906                                 var final:String = this.scheme + ":" + ref;\r
1907                                 \r
1908                                 return constructURI(final);\r
1909                         }\r
1910                         else if (ref.charAt(0) == "?")\r
1911                         {\r
1912                                 // A relative URI that is just a query part is essentially\r
1913                                 // a "./?query".  We tack on the "./" here to make the rest\r
1914                                 // of our logic work.\r
1915                                 ref = "./" + ref;\r
1916                         }\r
1917                 \r
1918                         // Parse the reference passed in as a URI.  This way we\r
1919                         // get any query and fragments parsed out as well.\r
1920                         uriReference = new URI(ref);\r
1921                 \r
1922                         if (uriReference.isAbsolute() ||\r
1923                                 uriReference.isHierarchical() == false)\r
1924                         {\r
1925                                 // If the URI given is a full URI, it replaces this one.\r
1926                                 copyURI(uriReference);\r
1927                                 return true;\r
1928                         }\r
1929                 \r
1930                 \r
1931                         var thisPath:String, thatPath:String;\r
1932                         var thisParts:Array, thatParts:Array;\r
1933                         var thisIsDir:Boolean = false, thatIsDir:Boolean = false;\r
1934                         var thisIsAbs:Boolean = false, thatIsAbs:Boolean = false;\r
1935                         var lastIsDotOperation:Boolean = false;\r
1936                         var curDir:String;\r
1937                         var i:int;\r
1938                 \r
1939                         thisPath = this.path;\r
1940                         thatPath = uriReference.path;\r
1941                 \r
1942                         if (thisPath.length > 0)\r
1943                                 thisParts = thisPath.split("/");\r
1944                         else\r
1945                                 thisParts = new Array();\r
1946                                 \r
1947                         if (thatPath.length > 0)\r
1948                                 thatParts = thatPath.split("/");\r
1949                         else\r
1950                                 thatParts = new Array();\r
1951                         \r
1952                         if (thisParts.length > 0 && thisParts[0] == "")\r
1953                         {\r
1954                                 thisIsAbs = true;\r
1955                                 thisParts.shift(); // pop the first one off the array\r
1956                         }\r
1957                         if (thisParts.length > 0 && thisParts[thisParts.length - 1] == "")\r
1958                         {\r
1959                                 thisIsDir = true;\r
1960                                 thisParts.pop();  // pop the last one off the array\r
1961                         }\r
1962                                 \r
1963                         if (thatParts.length > 0 && thatParts[0] == "")\r
1964                         {\r
1965                                 thatIsAbs = true;\r
1966                                 thatParts.shift(); // pop the first one off the array\r
1967                         }\r
1968                         if (thatParts.length > 0 && thatParts[thatParts.length - 1] == "")\r
1969                         {\r
1970                                 thatIsDir = true;\r
1971                                 thatParts.pop();  // pop the last one off the array\r
1972                         }\r
1973                                 \r
1974                         if (thatIsAbs)\r
1975                         {\r
1976                                 // The reference is an absolute path (starts with a slash).\r
1977                                 // It replaces this path wholesale.\r
1978                                 this.path = uriReference.path;\r
1979                 \r
1980                                 // And it inherits the query and fragment\r
1981                                 this.queryRaw = uriReference.queryRaw;\r
1982                                 this.fragment = uriReference.fragment;\r
1983                 \r
1984                                 return true;\r
1985                         }\r
1986                         else if (thatParts.length == 0 && uriReference.query == "")\r
1987                         {\r
1988                                 // The reference must have only been a fragment.  Fragments just\r
1989                                 // get appended to whatever the current path is.  We don't want\r
1990                                 // to overwrite any query that may already exist, so this case\r
1991                                 // only takes on the new fragment.\r
1992                                 this.fragment = uriReference.fragment;\r
1993                                 return true;\r
1994                         }\r
1995                         else if (thisIsDir == false && thisParts.length > 0)\r
1996                         {\r
1997                                 // This path ends in a file.  It goes away no matter what.\r
1998                                 thisParts.pop();\r
1999                         }\r
2000                 \r
2001                         // By default, this assumes the query and fragment of the reference\r
2002                         this.queryRaw = uriReference.queryRaw;\r
2003                         this.fragment = uriReference.fragment;\r
2004                 \r
2005                         // Append the parts of the path from the passed in reference\r
2006                         // to this object's path.\r
2007                         thisParts = thisParts.concat(thatParts);\r
2008                                         \r
2009                         for(i = 0; i < thisParts.length; i++)\r
2010                         {\r
2011                                 curDir = thisParts[i];\r
2012                                 lastIsDotOperation = false;\r
2013                 \r
2014                                 if (curDir == ".")\r
2015                                 {\r
2016                                         thisParts.splice(i, 1);\r
2017                                         i = i - 1;  // account for removing this item\r
2018                                         lastIsDotOperation = true;\r
2019                                 }\r
2020                                 else if (curDir == "..")\r
2021                                 {\r
2022                                         if (i >= 1)\r
2023                                         {\r
2024                                                 if (thisParts[i - 1] == "..")\r
2025                                                 {\r
2026                                                         // If the previous is a "..", we must have skipped\r
2027                                                         // it due to this URI being relative.  We can't\r
2028                                                         // collapse leading ".."s in a relative URI, so\r
2029                                                         // do nothing.\r
2030                                                 }\r
2031                                                 else\r
2032                                                 {\r
2033                                                         thisParts.splice(i - 1, 2);\r
2034                                                         i = i - 2;  // move back to account for the 2 we removed\r
2035                                                 }\r
2036                                         }\r
2037                                         else\r
2038                                         {\r
2039                                                 // This is the first thing in the path.\r
2040                 \r
2041                                                 if (isRelative())\r
2042                                                 {\r
2043                                                         // We can't collapse leading ".."s in a relative\r
2044                                                         // path.  Do noting.\r
2045                                                 }\r
2046                                                 else\r
2047                                                 {\r
2048                                                         // This is an abnormal case.  We have dot-dotted up\r
2049                                                         // past the base of our "file system".  This is a\r
2050                                                         // case where we had a /path/like/this.htm and were\r
2051                                                         // given a path to chdir to like this:\r
2052                                                         // ../../../../../../mydir\r
2053                                                         // Obviously, it has too many ".." and will take us\r
2054                                                         // up beyond the top of the URI.  However, according\r
2055                                                         // RFC 2396 Appendix C.2, we should try to handle\r
2056                                                         // these abnormal cases appropriately.  In this case,\r
2057                                                         // we will do what UNIX command lines do if you are\r
2058                                                         // at the root (/) of the filesystem and execute:\r
2059                                                         // # cd ../../../../../bin\r
2060                                                         // Which will put you in /bin.  Essentially, the extra\r
2061                                                         // ".."'s will just get eaten.\r
2062                 \r
2063                                                         thisParts.splice(i, 1);\r
2064                                                         i = i - 1;  // account for the ".." we just removed\r
2065                                                 }\r
2066                                         }\r
2067                 \r
2068                                         lastIsDotOperation = true;\r
2069                                 }\r
2070                         }\r
2071                         \r
2072                         var finalPath:String = "";\r
2073                 \r
2074                         // If the last thing in the path was a "." or "..", then this thing is a\r
2075                         // directory.  If the last thing isn't a dot-op, then we don't want to \r
2076                         // blow away any information about the directory (hence the "|=" binary\r
2077                         // assignment).\r
2078                         thatIsDir = thatIsDir || lastIsDotOperation;\r
2079                 \r
2080                         // Reconstruct the path with the abs/dir info we have\r
2081                         finalPath = joinPath(thisParts, thisIsAbs, thatIsDir);\r
2082                 \r
2083                         // Set the path (automatically escaping it)\r
2084                         this.path = finalPath;\r
2085                 \r
2086                         return true;\r
2087                 }\r
2088                 \r
2089                 /**\r
2090                  * @private\r
2091                  * Join an array of path parts back into a URI style path string.\r
2092                  * This is used by the various path logic functions to recombine\r
2093                  * a path.  This is different than the standard Array.join()\r
2094                  * function because we need to take into account the starting and\r
2095                  * ending path delimiters if this is an absolute path or a\r
2096                  * directory.\r
2097                  * \r
2098                  * @param parts the Array that contains strings of each path part.\r
2099                  * @param isAbs         true if the given path is absolute\r
2100                  * @param isDir         true if the given path is a directory\r
2101                  * \r
2102                  * @return the combined path string.\r
2103                  */\r
2104                 protected function joinPath(parts:Array, isAbs:Boolean, isDir:Boolean) : String\r
2105                 {\r
2106                         var pathStr:String = "";\r
2107                         var i:int;\r
2108                 \r
2109                         for (i = 0; i < parts.length; i++)\r
2110                         {\r
2111                                 if (pathStr.length > 0)\r
2112                                         pathStr += "/";\r
2113                 \r
2114                                 pathStr += parts[i];\r
2115                         }\r
2116                 \r
2117                         // If this path is a directory, tack on the directory delimiter,\r
2118                         // but only if the path contains something.  Adding this to an\r
2119                         // empty path would make it "/", which is an absolute path that\r
2120                         // starts at the root.\r
2121                         if (isDir && pathStr.length > 0)\r
2122                                 pathStr += "/";\r
2123                 \r
2124                         if (isAbs)\r
2125                                 pathStr = "/" + pathStr;\r
2126                 \r
2127                         return pathStr;\r
2128                 }\r
2129                 \r
2130                 /**\r
2131                  * Given an absolute URI, make this relative URI absolute using\r
2132                  * the given URI as a base.  This URI instance must be relative\r
2133                  * and the base_uri must be absolute.\r
2134                  * \r
2135                  * @param base_uri      URI to use as the base from which to make\r
2136                  * this relative URI into an absolute URI.\r
2137                  * \r
2138                  * @return true if successful, false otherwise.\r
2139                  */\r
2140                 public function makeAbsoluteURI(base_uri:URI) : Boolean\r
2141                 {\r
2142                         if (isAbsolute() || base_uri.isRelative())\r
2143                         {\r
2144                                 // This URI needs to be relative, and the base needs to be\r
2145                                 // absolute otherwise we won't know what to do!\r
2146                                 return false;\r
2147                         }\r
2148                 \r
2149                         // Make a copy of the base URI.  We don't want to modify\r
2150                         // the passed URI.\r
2151                         var base:URI = new URI();\r
2152                         base.copyURI(base_uri);\r
2153                 \r
2154                         // ChDir on the base URI.  This will preserve any query\r
2155                         // and fragment we have.\r
2156                         if (base.chdir(toString()) == false)\r
2157                                 return false;\r
2158                 \r
2159                         // It worked, so copy the base into this one\r
2160                         copyURI(base);\r
2161                 \r
2162                         return true;\r
2163                 }\r
2164                 \r
2165                 \r
2166                 /**\r
2167                  * Given a URI to use as a base from which this object should be\r
2168                  * relative to, convert this object into a relative URI.  For example,\r
2169                  * if you have:\r
2170                  * \r
2171                  * <listing>\r
2172                  * var uri1:URI = new URI("http://something.com/path/to/some/file.html");\r
2173                  * var uri2:URI = new URI("http://something.com/path/to/another/file.html");\r
2174                  * \r
2175                  * uri1.MakeRelativePath(uri2);</listing>\r
2176                  * \r
2177                  * <p>uri1 will have a final value of "../some/file.html"</p>\r
2178                  * \r
2179                  * <p>Note! This function is brute force.  If you have two URI's\r
2180                  * that are completely unrelated, this will still attempt to make\r
2181                  * the relative URI.  In that case, you will most likely get a\r
2182                  * relative path that looks something like:</p>\r
2183                  * \r
2184                  * <p>../../../../../../some/path/to/my/file.html</p>\r
2185                  * \r
2186                  * @param base_uri the URI from which to make this URI relative\r
2187                  * \r
2188                  * @return true if successful, false if the base_uri and this URI\r
2189                  * are not related, of if error.\r
2190                  */\r
2191                 public function makeRelativeURI(base_uri:URI, caseSensitive:Boolean = true) : Boolean\r
2192                 {\r
2193                         var base:URI = new URI();\r
2194                         base.copyURI(base_uri);\r
2195                         \r
2196                         var thisParts:Array, thatParts:Array;\r
2197                         var finalParts:Array = new Array();\r
2198                         var thisPart:String, thatPart:String, finalPath:String;\r
2199                         var pathStr:String = this.path;\r
2200                         var queryStr:String = this.queryRaw;\r
2201                         var fragmentStr:String = this.fragment;\r
2202                         var i:int;\r
2203                         var diff:Boolean = false;\r
2204                         var isDir:Boolean = false;\r
2205                 \r
2206                         if (isRelative())\r
2207                         {\r
2208                                 // We're already relative.\r
2209                                 return true;\r
2210                         }\r
2211                 \r
2212                         if (base.isRelative())\r
2213                         {\r
2214                                 // The base is relative.  A relative base doesn't make sense.\r
2215                                 return false;\r
2216                         }\r
2217                 \r
2218                 \r
2219                         if ( (isOfType(base_uri.scheme) == false) ||\r
2220                                 (this.authority != base_uri.authority) )\r
2221                         {\r
2222                                 // The schemes and/or authorities are different.  We can't\r
2223                                 // make a relative path to something that is completely\r
2224                                 // unrelated.\r
2225                                 return false;\r
2226                         }\r
2227                 \r
2228                         // Record the state of this URI\r
2229                         isDir = isDirectory();\r
2230                 \r
2231                         // We are based of the directory of the given URI.  We need to\r
2232                         // make sure the URI is pointing to a directory.  Changing\r
2233                         // directory to "." will remove any file name if the base is\r
2234                         // not a directory.\r
2235                         base.chdir(".");\r
2236                 \r
2237                         thisParts = pathStr.split("/");\r
2238                         thatParts = base.path.split("/");\r
2239                         \r
2240                         if (thisParts.length > 0 && thisParts[0] == "")\r
2241                                 thisParts.shift();\r
2242                         \r
2243                         if (thisParts.length > 0 && thisParts[thisParts.length - 1] == "")\r
2244                         {\r
2245                                 isDir = true;\r
2246                                 thisParts.pop();\r
2247                         }\r
2248                         \r
2249                         if (thatParts.length > 0 && thatParts[0] == "")\r
2250                                 thatParts.shift();\r
2251                         if (thatParts.length > 0 && thatParts[thatParts.length - 1] == "")\r
2252                                 thatParts.pop();\r
2253                 \r
2254                 \r
2255                         // Now that we have the paths split into an array of directories,\r
2256                         // we can compare the two paths.  We start from the left of side\r
2257                         // of the path and start comparing.  When we either run out of\r
2258                         // directories (one path is longer than the other), or we find\r
2259                         // a directory that is different, we stop.  The remaining parts\r
2260                         // of each path is then used to determine the relative path.  For\r
2261                         // example, lets say we have:\r
2262                         //    path we want to make relative: /a/b/c/d/e.txt\r
2263                         //    path to use as base for relative: /a/b/f/\r
2264                         //\r
2265                         // This loop will start at the left, and remove directories\r
2266                         // until we get a mismatch or run off the end of one of them.\r
2267                         // In this example, the result will be:\r
2268                         //    c/d/e.txt\r
2269                         //    f\r
2270                         //\r
2271                         // For every part left over in the base path, we prepend a ".."\r
2272                         // to the relative to get the final path:\r
2273                         //   ../c/d/e.txt\r
2274                         while(thatParts.length > 0)\r
2275                         {\r
2276                                 if (thisParts.length == 0)\r
2277                                 {\r
2278                                         // we matched all there is to match, we are done.\r
2279                                         // This is the case where "this" object is a parent\r
2280                                         // path of the given URI.  eg:\r
2281                                         //   this.path = /a/b/                          (thisParts)\r
2282                                         //   base.path = /a/b/c/d/e/            (thatParts)\r
2283                                         break;\r
2284                                 }\r
2285                 \r
2286                                 thisPart = thisParts[0];\r
2287                                 thatPart = thatParts[0];\r
2288                 \r
2289                                 if (compareStr(thisPart, thatPart, caseSensitive))\r
2290                                 {\r
2291                                         thisParts.shift();\r
2292                                         thatParts.shift();\r
2293                                 }\r
2294                                 else\r
2295                                         break;\r
2296                         }\r
2297                 \r
2298                         // If there are any path info left from the base URI, that means\r
2299                         // **this** object is above the given URI in the file tree.  For\r
2300                         // each part left over in the given URI, we need to move up one\r
2301                         // directory to get where we are.\r
2302                         var dotdot:String = "..";\r
2303                         for (i = 0; i < thatParts.length; i++)\r
2304                         {\r
2305                                 finalParts.push(dotdot);\r
2306                         }\r
2307                 \r
2308                         // Append the parts of this URI to any dot-dot's we have\r
2309                         finalParts = finalParts.concat(thisParts);\r
2310                 \r
2311                         // Join the parts back into a path\r
2312                         finalPath = joinPath(finalParts, false /* not absolute */, isDir);\r
2313                 \r
2314                         if (finalPath.length == 0)\r
2315                         {\r
2316                                 // The two URI's are exactly the same.  The proper relative\r
2317                                 // path is:\r
2318                                 finalPath = "./";\r
2319                         }\r
2320                 \r
2321                         // Set the parts of the URI, preserving the original query and\r
2322                         // fragment parts.\r
2323                         setParts("", "", "", finalPath, queryStr, fragmentStr);\r
2324                 \r
2325                         return true;\r
2326                 }\r
2327                 \r
2328                 /**\r
2329                  * Given a string, convert it to a URI.  The string could be a\r
2330                  * full URI that is improperly escaped, a malformed URI (e.g.\r
2331                  * missing a protocol like "www.something.com"), a relative URI,\r
2332                  * or any variation there of.\r
2333                  * \r
2334                  * <p>The intention of this function is to take anything that a\r
2335                  * user might manually enter as a URI/URL and try to determine what\r
2336                  * they mean.  This function differs from the URI constructor in\r
2337                  * that it makes some assumptions to make it easy to import user\r
2338                  * entered URI data.</p>\r
2339                  * \r
2340                  * <p>This function is intended to be a helper function.\r
2341                  * It is not all-knowning and will probably make mistakes\r
2342                  * when attempting to parse a string of unknown origin.  If\r
2343                  * your applicaiton is receiving input from the user, your\r
2344                  * application should already have a good idea what the user\r
2345                  * should  be entering, and your application should be\r
2346                  * pre-processing the user's input to make sure it is well formed\r
2347                  * before passing it to this function.</p>\r
2348                  * \r
2349                  * <p>It is assumed that the string given to this function is\r
2350                  * something the user may have manually entered.  Given this,\r
2351                  * the URI string is probably unescaped or improperly escaped.\r
2352                  * This function will attempt to properly escape the URI by\r
2353                  * using forceEscape().  The result is that a toString() call\r
2354                  * on a URI that was created from unknownToURI() may not match\r
2355                  * the input string due to the difference in escaping.</p>\r
2356                  *\r
2357                  * @param unknown       a potental URI string that should be parsed\r
2358                  * and loaded into this object.\r
2359                  * @param defaultScheme if it is determined that the passed string\r
2360                  * looks like a URI, but it is missing the scheme part, this\r
2361                  * string will be used as the missing scheme.\r
2362                  * \r
2363                  * @return      true if the given string was successfully parsed into\r
2364                  * a valid URI object, false otherwise.\r
2365                  */\r
2366                 public function unknownToURI(unknown:String, defaultScheme:String = "http") : Boolean\r
2367                 {\r
2368                         var temp:String;\r
2369                         \r
2370                         if (unknown.length == 0)\r
2371                         {\r
2372                                 this.initialize();\r
2373                                 return false;\r
2374                         }\r
2375                         \r
2376                         // Some users love the backslash key.  Fix it.\r
2377                         unknown = unknown.replace(/\\/g, "/");\r
2378                         \r
2379                         // Check for any obviously missing scheme.\r
2380                         if (unknown.length >= 2)\r
2381                         {\r
2382                                 temp = unknown.substr(0, 2);\r
2383                                 if (temp == "//")\r
2384                                         unknown = defaultScheme + ":" + unknown;\r
2385                         }\r
2386                         \r
2387                         if (unknown.length >= 3)\r
2388                         {\r
2389                                 temp = unknown.substr(0, 3);\r
2390                                 if (temp == "://")\r
2391                                         unknown = defaultScheme + unknown;\r
2392                         }\r
2393 \r
2394                         // Try parsing it as a normal URI\r
2395                         var uri:URI = new URI(unknown);\r
2396                 \r
2397                         if (uri.isHierarchical() == false)\r
2398                         {\r
2399                                 if (uri.scheme == UNKNOWN_SCHEME)\r
2400                                 {\r
2401                                         this.initialize();\r
2402                                         return false;\r
2403                                 }\r
2404                 \r
2405                                 // It's a non-hierarchical URI\r
2406                                 copyURI(uri);\r
2407                                 forceEscape();\r
2408                                 return true;\r
2409                         }\r
2410                         else if ((uri.scheme != UNKNOWN_SCHEME) &&\r
2411                                 (uri.scheme.length > 0))\r
2412                         {\r
2413                                 if ( (uri.authority.length > 0) ||\r
2414                                         (uri.scheme == "file") )\r
2415                                 {\r
2416                                         // file://... URI\r
2417                                         copyURI(uri);\r
2418                                         forceEscape();  // ensure proper escaping\r
2419                                         return true;\r
2420                                 }\r
2421                                 else if (uri.authority.length == 0 && uri.path.length == 0)\r
2422                                 {\r
2423                                         // It's is an incomplete URI (eg "http://")\r
2424                                         \r
2425                                         setParts(uri.scheme, "", "", "", "", "");\r
2426                                         return false;\r
2427                                 }\r
2428                         }\r
2429                         else\r
2430                         {\r
2431                                 // Possible relative URI.  We can only detect relative URI's\r
2432                                 // that start with "." or "..".  If it starts with something\r
2433                                 // else, the parsing is ambiguous.\r
2434                                 var path:String = uri.path;\r
2435                 \r
2436                                 if (path == ".." || path == "." || \r
2437                                         (path.length >= 3 && path.substr(0, 3) == "../") ||\r
2438                                         (path.length >= 2 && path.substr(0, 2) == "./") )\r
2439                                 {\r
2440                                         // This is a relative URI.\r
2441                                         copyURI(uri);\r
2442                                         forceEscape();\r
2443                                         return true;\r
2444                                 }\r
2445                         }\r
2446                 \r
2447                         // Ok, it looks like we are just a normal URI missing the scheme.  Tack\r
2448                         // on the scheme.\r
2449                         uri = new URI(defaultScheme + "://" + unknown);\r
2450                 \r
2451                         // Check to see if we are good now\r
2452                         if (uri.scheme.length > 0 && uri.authority.length > 0)\r
2453                         {\r
2454                                 // It was just missing the scheme.\r
2455                                 copyURI(uri);\r
2456                                 forceEscape();  // Make sure we are properly encoded.\r
2457                                 return true;\r
2458                         }\r
2459                 \r
2460                         // don't know what this is\r
2461                         this.initialize();\r
2462                         return false;\r
2463                 }\r
2464                 \r
2465         } // end URI class\r
2466 } // end package