2 Copyright (c) 2008, Adobe Systems Incorporated
\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
9 * Redistributions of source code must retain the above copyright notice,
\r
10 this list of conditions and the following disclaimer.
\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
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
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
33 package com.adobe.net
\r
35 import flash.utils.ByteArray;
\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
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
51 * <p>URI's fall into one of three categories:
\r
53 * <li><scheme>:<scheme-specific-part>#<fragment> (non-hierarchical)</li>
\r
54 * <li><scheme>:<authority><path>?<query>#<fragment> (hierarchical)</li>
\r
55 * <li><path>?<query>#<fragment> (relative hierarchical)</li>
\r
58 * <p>The query and fragment parts are optional.</p>
\r
60 * <p>This class supports both non-hierarchical and hierarchical URI's</p>
\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
69 * @langversion ActionScript 3.0
\r
70 * @playerversion Flash 9.0
\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
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
86 // Baseline of what characters must be escaped
\r
87 public static const URIbaselineEscape:String = URImustEscape + ":?#/@";
\r
89 // Characters that must be escaped in the part part.
\r
90 public static const URIpathEscape:String = URImustEscape + "?#";
\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
97 // This is what each name/value pair must escape "&=" as well
\r
98 // so they don't conflict with the "param=value¶m2=value2"
\r
100 public static const URIqueryPartEscape:String = URImustEscape + "#&=";
\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
107 // Baseline uninitialized setting for the URI scheme.
\r
108 public static const UNKNOWN_SCHEME:String = "unknown";
\r
110 // The following bitmaps are used for performance enhanced
\r
111 // character escaping.
\r
113 // Baseline characters that need to be escaped. Many parts use
\r
115 protected static const URIbaselineExcludedBitmap:URIEncodingBitmap =
\r
116 new URIEncodingBitmap(URIbaselineEscape);
\r
118 // Scheme escaping bitmap
\r
119 protected static const URIschemeExcludedBitmap:URIEncodingBitmap =
\r
120 URIbaselineExcludedBitmap;
\r
122 // User/pass escaping bitmap
\r
123 protected static const URIuserpassExcludedBitmap:URIEncodingBitmap =
\r
124 URIbaselineExcludedBitmap;
\r
126 // Authority escaping bitmap
\r
127 protected static const URIauthorityExcludedBitmap:URIEncodingBitmap =
\r
128 URIbaselineExcludedBitmap;
\r
130 // Port escaping bitmap
\r
131 protected static const URIportExludedBitmap:URIEncodingBitmap =
\r
132 URIbaselineExcludedBitmap;
\r
134 // Path escaping bitmap
\r
135 protected static const URIpathExcludedBitmap:URIEncodingBitmap =
\r
136 new URIEncodingBitmap(URIpathEscape);
\r
138 // Query (whole) escaping bitmap
\r
139 protected static const URIqueryExcludedBitmap:URIEncodingBitmap =
\r
140 new URIEncodingBitmap(URIqueryEscape);
\r
142 // Query (individual parts) escaping bitmap
\r
143 protected static const URIqueryPartExcludedBitmap:URIEncodingBitmap =
\r
144 new URIEncodingBitmap(URIqueryPartEscape);
\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
149 protected static const URIfragmentExcludedBitmap:URIEncodingBitmap =
\r
150 URIqueryExcludedBitmap;
\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
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
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
180 * URI Constructor. If no string is given, this will initialize
\r
181 * this URI object to a blank URI.
\r
183 public function URI(uri:String = null) : void
\r
194 * Method that loads the URI from the given string.
\r
196 protected function constructURI(uri:String) : Boolean
\r
198 if (!parseURI(uri))
\r
206 * @private Private initializiation.
\r
208 protected function initialize() : void
\r
213 _scheme = UNKNOWN_SCHEME;
\r
222 _nonHierarchical = "";
\r
226 * @private Accessor to explicitly set/get the hierarchical
\r
227 * state of the URI.
\r
229 protected function set hierState(state:Boolean) : void
\r
233 // Clear the non-hierarchical data
\r
234 _nonHierarchical = "";
\r
236 // Also set the state vars while we are at it
\r
237 if (_scheme == "" || _scheme == UNKNOWN_SCHEME)
\r
242 if (_authority.length == 0 && _path.length == 0)
\r
249 // Clear the hierarchical data
\r
258 if (_scheme == "" || _scheme == UNKNOWN_SCHEME)
\r
264 protected function get hierState() : Boolean
\r
266 return (_nonHierarchical.length == 0);
\r
271 * @private Functions that performs some basic consistency validation.
\r
273 protected function validateURI() : Boolean
\r
275 // Check the scheme
\r
278 if (_scheme.length <= 1 || _scheme == UNKNOWN_SCHEME)
\r
280 // we probably parsed a C:\ type path or no scheme
\r
283 else if (verifyAlpha(_scheme) == false)
\r
284 return false; // Scheme contains bad characters
\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
296 if (_nonHierarchical.search('\\') != -1)
\r
297 return false; // some kind of local path
\r
300 // Looks like it's ok.
\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
312 * For simplicity, we parse the URI in the following order:
\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
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
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
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
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
353 * Anything else will probably result in a parsing error, or a bogus
\r
356 * Note that non-hierarchical URIs *MUST* have a scheme, otherwise
\r
357 * they will be mistaken for relative URI's.
\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
363 * @return true if successful, false if there was some kind of
\r
366 protected function parseURI(uri:String) : Boolean
\r
368 var baseURI:String = uri;
\r
369 var index:int, index2:int;
\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
376 // Remove any fragments (anchors) from the URI
\r
377 index = baseURI.indexOf("#");
\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
384 // Trim off the fragment
\r
385 baseURI = baseURI.substr(0, index);
\r
388 // We need to strip off any CGI parameters (eg '?param=bob')
\r
389 index = baseURI.indexOf("?");
\r
392 if (baseURI.length > (index + 1))
\r
393 _query = baseURI.substr(index + 1, baseURI.length - (index + 1)); // +1 is to skip the '?'
\r
395 // Trim off the query
\r
396 baseURI = baseURI.substr(0, index);
\r
399 // Now try to find the scheme part
\r
400 index = baseURI.search(':');
\r
401 index2 = baseURI.search('/');
\r
403 var containsColon:Boolean = (index != -1);
\r
404 var containsSlash:Boolean = (index2 != -1);
\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
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
419 // We found a scheme
\r
420 _scheme = baseURI.substr(0, index);
\r
422 // Normalize the scheme
\r
423 _scheme = _scheme.toLowerCase();
\r
425 baseURI = baseURI.substr(index + 1);
\r
427 if (baseURI.substr(0, 2) == "//")
\r
429 // This is a hierarchical URI
\r
430 _nonHierarchical = "";
\r
432 // Trim off the "//"
\r
433 baseURI = baseURI.substr(2, baseURI.length - 2);
\r
437 // This is a non-hierarchical URI like "mailto:bob@mail.com"
\r
438 _nonHierarchical = baseURI;
\r
440 if ((_valid = validateURI()) == false)
\r
441 initialize(); // Bad URI. Clear it.
\r
443 // No more parsing to do for this case
\r
449 // No scheme. We will consider this a relative URI
\r
452 _nonHierarchical = "";
\r
455 // Ok, what we have left is everything after the <scheme>://
\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
462 // Don't bother looking for the authority. It's a relative URI
\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
477 // Trim all leading slashes
\r
478 while(baseURI.charAt(0) == "/")
\r
479 baseURI = baseURI.substr(1, baseURI.length - 1);
\r
482 index = baseURI.search('/');
\r
485 // No path. We must have passed something like "http://something.com"
\r
486 _authority = baseURI;
\r
491 _authority = baseURI.substr(0, index);
\r
492 _path = baseURI.substr(index, baseURI.length - index);
\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
500 // We have a username and possibly a password
\r
501 _username = _authority.substr(0, index);
\r
503 // Remove the username/password from the authority
\r
504 _authority = _authority.substr(index + 1); // Skip the '@'
\r
506 // Now check to see if the username also has a password
\r
507 index = _username.search(':');
\r
510 _password = _username.substring(index + 1, _username.length);
\r
511 _username = _username.substr(0, index);
\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
528 _port = _authority.substring(index + 1, _authority.length); // skip the ':'
\r
529 _authority = _authority.substr(0, index);
\r
536 // Lastly, normalize the authority. Domain names
\r
537 // are case insensitive.
\r
538 _authority = _authority.toLowerCase();
\r
541 if ((_valid = validateURI()) == false)
\r
542 initialize(); // Bad URI. Clear it
\r
548 /********************************************************************
\r
551 public function copyURI(uri:URI) : void
\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
563 this._valid = uri._valid;
\r
564 this._relative = uri._relative;
\r
570 * Checks if the given string only contains a-z or A-Z.
\r
572 protected function verifyAlpha(str:String) : Boolean
\r
574 var pattern:RegExp = /[^a-z]/;
\r
577 str = str.toLowerCase();
\r
578 index = str.search(pattern);
\r
587 * Is this a valid URI?
\r
589 * @return true if this object represents a valid URI, false
\r
592 public function isValid() : Boolean
\r
594 return this._valid;
\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
603 public function isAbsolute() : Boolean
\r
605 return !this._relative;
\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
615 public function isRelative() : Boolean
\r
617 return this._relative;
\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
630 * @return true if this URI represents a directory resource, false
\r
631 * if this URI represents a file resource.
\r
633 public function isDirectory() : Boolean
\r
635 if (_path.length == 0)
\r
638 return (_path.charAt(path.length - 1) == '/');
\r
643 * Is this URI a hierarchical URI? URI's can be
\r
645 public function isHierarchical() : Boolean
\r
652 * The scheme of the URI.
\r
654 public function get scheme() : String
\r
656 return URI.unescapeChars(_scheme);
\r
658 public function set scheme(schemeStr:String) : void
\r
660 // Normalize the scheme
\r
661 var normalized:String = schemeStr.toLowerCase();
\r
662 _scheme = URI.fastEscapeChars(normalized, URI.URIschemeExcludedBitmap);
\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
673 public function get authority() : String
\r
675 return URI.unescapeChars(_authority);
\r
677 public function set authority(authorityStr:String) : void
\r
679 // Normalize the authority
\r
680 authorityStr = authorityStr.toLowerCase();
\r
682 _authority = URI.fastEscapeChars(authorityStr,
\r
683 URI.URIauthorityExcludedBitmap);
\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
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
696 * <p>The URI specification allows for authentication
\r
697 * credentials to be embedded in the URI as such:</p>
\r
699 * <p>http://user:passwd@host/path/to/file.htm</p>
\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
705 public function get username() : String
\r
707 return URI.unescapeChars(_username);
\r
709 public function set username(usernameStr:String) : void
\r
711 _username = URI.fastEscapeChars(usernameStr, URI.URIuserpassExcludedBitmap);
\r
713 // Only hierarchical URI's can have a username.
\r
714 this.hierState = true;
\r
719 * The password of the URI. Similar to username.
\r
720 * @see URI.username
\r
722 public function get password() : String
\r
724 return URI.unescapeChars(_password);
\r
726 public function set password(passwordStr:String) : void
\r
728 _password = URI.fastEscapeChars(passwordStr,
\r
729 URI.URIuserpassExcludedBitmap);
\r
731 // Only hierarchical URI's can have a password.
\r
732 this.hierState = true;
\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
741 * <p>http://site.com:8080/index.htm</p>
\r
743 public function get port() : String
\r
745 return URI.unescapeChars(_port);
\r
747 public function set port(portStr:String) : void
\r
749 _port = URI.escapeChars(portStr);
\r
751 // Only hierarchical URI's can have a port.
\r
752 this.hierState = true;
\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
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
766 * <p>An absolute path may look like:</p>
\r
767 * <listing>/full/path/to/my/file.htm</listing>
\r
769 * <p>A relative path may look like:</p>
\r
771 * path/to/my/file.htm
\r
772 * ../images/logo.gif
\r
773 * ../../reports/index.htm
\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
780 * <listing>http:/site.com/path/to/file.htm</listing>
\r
782 * <p>This absolute URI has an absolute path of "/path/to/file.htm".</p>
\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
788 * /absolute/path/to/file.htm
\r
790 * ../path/to/file.htm
\r
793 public function get path() : String
\r
795 return URI.unescapeChars(_path);
\r
797 public function set path(pathStr:String) : void
\r
799 this._path = URI.fastEscapeChars(pathStr, URI.URIpathExcludedBitmap);
\r
801 if (this._scheme == UNKNOWN_SCHEME)
\r
803 // We set the path. This is a valid URI now.
\r
807 // Only hierarchical URI's can have a path.
\r
813 * The query (CGI) portion of the URI. This part is valid for
\r
814 * both hierarchical and non-hierarchical URI's.
\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
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
828 * <listing>http://site.com/script.php?param1=value1¶m2=value2</listing>
\r
830 * <p>This class has specific support for this query syntax</p>
\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
843 * If a different query syntax is being used, a subclass of URI
\r
844 * can be created to handle that specific syntax.
\r
846 * @see URI.getQueryValue, URI.getQueryByMap
\r
848 public function get query() : String
\r
850 return URI.unescapeChars(_query);
\r
852 public function set query(queryStr:String) : void
\r
854 _query = URI.fastEscapeChars(queryStr, URI.URIqueryExcludedBitmap);
\r
856 // both hierarchical and non-hierarchical URI's can
\r
857 // have a query. Do not set the hierState.
\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
867 public function get queryRaw() : String
\r
871 public function set queryRaw(queryStr:String) : void
\r
878 * The fragment (anchor) portion of the URI. This is valid for
\r
879 * both hierarchical and non-hierarchical URI's.
\r
881 public function get fragment() : String
\r
883 return URI.unescapeChars(_fragment);
\r
885 public function set fragment(fragmentStr:String) : void
\r
887 _fragment = URI.fastEscapeChars(fragmentStr, URIfragmentExcludedBitmap);
\r
889 // both hierarchical and non-hierarchical URI's can
\r
890 // have a fragment. Do not set the hierState.
\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
900 public function get nonHierarchical() : String
\r
902 return URI.unescapeChars(_nonHierarchical);
\r
904 public function set nonHierarchical(nonHier:String) : void
\r
906 _nonHierarchical = URI.fastEscapeChars(nonHier, URInonHierexcludedBitmap);
\r
908 // This is a non-hierarchical URI.
\r
909 this.hierState = false;
\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
919 public function setParts(schemeStr:String, authorityStr:String,
\r
920 portStr:String, pathStr:String, queryStr:String,
\r
921 fragmentStr:String) : void
\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
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
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
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
950 * @param unescaped character string to be escaped.
\r
952 * @return escaped character string
\r
954 * @see encodeURIComponent
\r
955 * @see fastEscapeChars
\r
957 static public function escapeChars(unescaped:String) : String
\r
959 // This uses the excluded set by default.
\r
960 return fastEscapeChars(unescaped, URI.URIbaselineExcludedBitmap);
\r
965 * Unescape any URI escaped characters in the given character
\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
973 * @param escaped the escaped string to be unescaped.
\r
975 * @return unescaped string.
\r
977 static public function unescapeChars(escaped:String /*, onlyHighASCII:Boolean = false*/) : String
\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
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
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
998 * @param unescaped the unescaped string to be escaped
\r
999 * @param bitmap the set of characters that need to be escaped
\r
1001 * @return the escaped string.
\r
1003 static public function fastEscapeChars(unescaped:String, bitmap:URIEncodingBitmap) : String
\r
1005 var escaped:String = "";
\r
1009 for (i = 0; i < unescaped.length; i++)
\r
1011 c = unescaped.charAt(i);
\r
1013 x = bitmap.ShouldEscape(c);
\r
1016 c = x.toString(16);
\r
1017 if (c.length == 1)
\r
1021 c = c.toUpperCase();
\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
1036 * @param scheme scheme to check for
\r
1038 * @return true if this URI object is of the given type, false
\r
1041 public function isOfType(scheme:String) : Boolean
\r
1043 // Schemes are never case sensitive. Ignore case.
\r
1044 scheme = scheme.toLowerCase();
\r
1045 return (this._scheme == scheme);
\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
1055 * @param name name of the query value to get.
\r
1057 * @return the value of the query name, empty string if the
\r
1058 * query name does not exist.
\r
1060 public function getQueryValue(name:String) : String
\r
1066 map = getQueryByMap();
\r
1072 value = map[item];
\r
1077 // Didn't find the specified key
\r
1078 return new String("");
\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
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
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
1096 public function setQueryValue(name:String, value:String) : void
\r
1100 map = getQueryByMap();
\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
1107 setQueryByMap(map);
\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
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
1121 * @return Object that contains the name/value pairs of the query.
\r
1123 * @see #setQueryByMap
\r
1124 * @see #getQueryValue
\r
1125 * @see #setQueryValue
\r
1127 public function getQueryByMap() : Object
\r
1129 var queryStr:String;
\r
1133 var name:String, value:String;
\r
1135 var map:Object = new Object();
\r
1138 // We need the raw query string, no unescaping.
\r
1139 queryStr = this._query;
\r
1141 pairs = queryStr.split('&');
\r
1142 for each (pair in pairs)
\r
1144 if (pair.length == 0)
\r
1147 item = pair.split('=');
\r
1149 if (item.length > 0)
\r
1152 continue; // empty array
\r
1154 if (item.length > 1)
\r
1159 name = queryPartUnescape(name);
\r
1160 value = queryPartUnescape(value);
\r
1162 map[name] = value;
\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
1174 * @param map object that contains the name/value pairs as
\r
1175 * members of that object.
\r
1177 * @see #getQueryByMap
\r
1178 * @see #getQueryValue
\r
1179 * @see #setQueryValue
\r
1181 public function setQueryByMap(map:Object) : void
\r
1184 var name:String, value:String;
\r
1185 var queryStr:String = "";
\r
1186 var tmpPair:String;
\r
1192 value = map[item];
\r
1194 if (value == null)
\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
1205 if (value.length > 0)
\r
1211 if (queryStr.length != 0)
\r
1212 queryStr += '&'; // Add the separator
\r
1214 queryStr += tmpPair;
\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
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
1233 * @param unescaped unescaped string that is to be escaped.
\r
1235 * @return escaped string.
\r
1237 * @see #queryUnescape
\r
1239 static public function queryPartEscape(unescaped:String) : String
\r
1241 var escaped:String = unescaped;
\r
1242 escaped = URI.fastEscapeChars(unescaped, URI.URIqueryPartExcludedBitmap);
\r
1248 * Unescape the individual name/value string pairs.
\r
1250 * @param escaped escaped string to be unescaped
\r
1252 * @return unescaped string
\r
1254 * @see #queryEscape
\r
1256 static public function queryPartUnescape(escaped:String) : String
\r
1258 var unescaped:String = escaped;
\r
1259 unescaped = unescapeChars(unescaped);
\r
1264 * Output this URI as a string. The resulting string is properly
\r
1265 * escaped and well formed for machine processing.
\r
1267 public function toString() : String
\r
1272 return toStringInternal(false);
\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
1285 * @return the URI in string format with all escape sequences
\r
1290 public function toDisplayString() : String
\r
1292 return toStringInternal(true);
\r
1299 * The guts of toString()
\r
1301 protected function toStringInternal(forDisplay:Boolean) : String
\r
1303 var uri:String = "";
\r
1304 var part:String = "";
\r
1306 if (isHierarchical() == false)
\r
1308 // non-hierarchical URI
\r
1310 uri += (forDisplay ? this.scheme : _scheme);
\r
1312 uri += (forDisplay ? this.nonHierarchical : _nonHierarchical);
\r
1316 // Hierarchical URI
\r
1318 if (isRelative() == false)
\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
1324 if (_scheme.length != 0)
\r
1326 part = (forDisplay ? this.scheme : _scheme);
\r
1327 uri += part + ":";
\r
1330 if (_authority.length != 0 || isOfType("file"))
\r
1334 // Add on any username/password associated with this
\r
1336 if (_username.length != 0)
\r
1338 part = (forDisplay ? this.username : _username);
\r
1341 if (_password.length != 0)
\r
1343 part = (forDisplay ? this.password : _password);
\r
1344 uri += ":" + part;
\r
1350 // add the authority
\r
1351 part = (forDisplay ? this.authority : _authority);
\r
1354 // Tack on the port number, if any
\r
1355 if (port.length != 0)
\r
1356 uri += ":" + port;
\r
1360 // Tack on the path
\r
1361 part = (forDisplay ? this.path : _path);
\r
1364 } // end hierarchical part
\r
1366 // Both non-hier and hierarchical have query and fragment parts
\r
1368 // Add on the query and fragment parts
\r
1369 if (_query.length != 0)
\r
1371 part = (forDisplay ? this.query : _query);
\r
1372 uri += "?" + part;
\r
1375 if (fragment.length != 0)
\r
1377 part = (forDisplay ? this.fragment : _fragment);
\r
1378 uri += "#" + part;
\r
1385 * Forcefully ensure that this URI is properly escaped.
\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
1397 public function forceEscape() : void
\r
1399 // The accessors for each of the members will unescape
\r
1400 // and then re-escape as we get and assign them.
\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
1408 if (isHierarchical())
\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
1418 this.nonHierarchical = this.nonHierarchical;
\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
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
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
1436 public function isOfFileType(extension:String) : Boolean
\r
1438 var thisExtension:String;
\r
1441 index = extension.lastIndexOf(".");
\r
1444 // Strip the extension
\r
1445 extension = extension.substr(index + 1);
\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
1454 thisExtension = getExtension(true);
\r
1456 if (thisExtension == "")
\r
1459 // Compare the extensions ignoring case
\r
1460 if (compareStr(thisExtension, extension, false) == 0)
\r
1468 * Get the ".xyz" file extension from the filename in the URI.
\r
1469 * For example, if we have the following URI:
\r
1471 * <listing>http://something.com/path/to/my/page.html?form=yes&name=bob#anchor</listing>
\r
1473 * <p>This will return ".html".</p>
\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
1478 * @return the file extension
\r
1480 public function getExtension(minusDot:Boolean = false) : String
\r
1482 var filename:String = getFilename();
\r
1483 var extension:String;
\r
1486 if (filename == "")
\r
1487 return String("");
\r
1489 index = filename.lastIndexOf(".");
\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
1497 extension = filename.substr(index);
\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
1507 * Quick function to retrieve the file name off the end of a URI.
\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
1513 * @param minusExtension true if the file extension should be stripped
\r
1515 * @return the file name. If this URI is a directory, the return
\r
1516 * value will be empty string.
\r
1518 public function getFilename(minusExtension:Boolean = false) : String
\r
1520 if (isDirectory())
\r
1521 return String("");
\r
1523 var pathStr:String = this.path;
\r
1524 var filename:String;
\r
1527 // Find the last path separator.
\r
1528 index = pathStr.lastIndexOf("/");
\r
1531 filename = pathStr.substr(index + 1);
\r
1533 filename = pathStr;
\r
1535 if (minusExtension)
\r
1537 // The caller has requested that the extension be removed
\r
1538 index = filename.lastIndexOf(".");
\r
1541 filename = filename.substr(0, index);
\r
1550 * Helper function to compare strings.
\r
1552 * @return true if the two strings are identical, false otherwise.
\r
1554 static protected function compareStr(str1:String, str2:String,
\r
1555 sensitive:Boolean = true) : Boolean
\r
1557 if (sensitive == false)
\r
1559 str1 = str1.toLowerCase();
\r
1560 str2 = str2.toLowerCase();
\r
1563 return (str1 == str2)
\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
1572 public function getDefaultPort() : String
\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
1584 // Don't know the port for this URI type
\r
1585 return String("");
\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
1596 static protected function resolve(uri:URI) : URI
\r
1598 var copy:URI = new URI();
\r
1599 copy.copyURI(uri);
\r
1601 if (_resolver != null)
\r
1603 // A resolver class has been registered. Call it.
\r
1604 return _resolver.resolve(copy);
\r
1608 // No resolver. Nothing to do, but we don't
\r
1609 // want to reuse the one passed in.
\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
1618 static public function set resolver(resolver:IURIResolver) : void
\r
1620 _resolver = resolver;
\r
1622 static public function get resolver() : IURIResolver
\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
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
1637 * @return URI.NOT_RELATED, URI.CHILD, URI.PARENT, or URI.EQUAL
\r
1639 public function getRelation(uri:URI, caseSensitive:Boolean = true) : int
\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
1645 if (thisURI.isRelative() || thatURI.isRelative())
\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
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
1656 else if (thisURI.isHierarchical() == false || thatURI.isHierarchical() == false)
\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
1662 // XOR. One is hierarchical and the other is
\r
1663 // non-hierarchical. They cannot be compared.
\r
1664 return URI.NOT_RELATED;
\r
1668 // They are both non-hierarchical
\r
1669 if (thisURI.scheme != thatURI.scheme)
\r
1670 return URI.NOT_RELATED;
\r
1672 if (thisURI.nonHierarchical != thatURI.nonHierarchical)
\r
1673 return URI.NOT_RELATED;
\r
1675 // The two non-hierarcical URI's are equal.
\r
1680 // Ok, this URI and the one we are being compared to are both
\r
1681 // absolute hierarchical URI's.
\r
1683 if (thisURI.scheme != thatURI.scheme)
\r
1684 return URI.NOT_RELATED;
\r
1686 if (thisURI.authority != thatURI.authority)
\r
1687 return URI.NOT_RELATED;
\r
1689 var thisPort:String = thisURI.port;
\r
1690 var thatPort:String = thatURI.port;
\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
1698 // Check to see if the port is the default port.
\r
1699 if (thisPort != thatPort)
\r
1700 return URI.NOT_RELATED;
\r
1702 if (compareStr(thisURI.path, thatURI.path, caseSensitive))
\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
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
1715 if ( (thisPath == "/" || thatPath == "/") &&
\r
1716 (thisPath == "" || thatPath == "") )
\r
1718 // We hit the special case. These two are equal.
\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
1735 thisParts = thisPath.split("/");
\r
1736 thatParts = thatPath.split("/");
\r
1738 if (thisParts.length > thatParts.length)
\r
1740 thatPart = thatParts[thatParts.length - 1];
\r
1741 if (thatPart.length > 0)
\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
1750 // Remove the empty trailing part
\r
1754 // This may be a child of the one passed in
\r
1755 for (i = 0; i < thatParts.length; i++)
\r
1757 thisPart = thisParts[i];
\r
1758 thatPart = thatParts[i];
\r
1760 if (compareStr(thisPart, thatPart, caseSensitive) == false)
\r
1761 return URI.NOT_RELATED;
\r
1766 else if (thisParts.length < thatParts.length)
\r
1768 thisPart = thisParts[thisParts.length - 1];
\r
1769 if (thisPart.length > 0)
\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
1774 return URI.NOT_RELATED;
\r
1778 // Remove the empty trailing part
\r
1782 // This may be the parent of the one passed in
\r
1783 for (i = 0; i < thisParts.length; i++)
\r
1785 thisPart = thisParts[i];
\r
1786 thatPart = thatParts[i];
\r
1788 if (compareStr(thisPart, thatPart, caseSensitive) == false)
\r
1789 return URI.NOT_RELATED;
\r
1792 return URI.PARENT;
\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
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
1809 * Given another URI, return the common parent between this one
\r
1810 * and the provided URI.
\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
1816 * @return the parent URI if successful, null otherwise.
\r
1818 public function getCommonParent(uri:URI, caseSensitive:Boolean = true) : URI
\r
1820 var thisURI:URI = URI.resolve(this);
\r
1821 var thatURI:URI = URI.resolve(uri);
\r
1823 if(!thisURI.isAbsolute() || !thatURI.isAbsolute() ||
\r
1824 thisURI.isHierarchical() == false ||
\r
1825 thatURI.isHierarchical() == false)
\r
1827 // Both URI's must be absolute hierarchical for this to
\r
1832 var relation:int = thisURI.getRelation(thatURI);
\r
1833 if (relation == URI.NOT_RELATED)
\r
1835 // The given URI is not related to this one. No
\r
1840 thisURI.chdir(".");
\r
1841 thatURI.chdir(".");
\r
1843 var strBefore:String, strAfter:String;
\r
1846 relation = thisURI.getRelation(thatURI, caseSensitive);
\r
1847 if(relation == URI.EQUAL || relation == URI.PARENT)
\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
1857 while(strBefore != strAfter);
\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
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
1879 * <p>See RFC 2396, Appendix C for more info.</p>
\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
1885 * @return true if the chdir was successful, false otherwise.
\r
1887 public function chdir(reference:String, escape:Boolean = false) : Boolean
\r
1889 var uriReference:URI;
\r
1890 var ref:String = reference;
\r
1893 ref = URI.escapeChars(reference);
\r
1900 else if (ref.substr(0, 2) == "//")
\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
1906 var final:String = this.scheme + ":" + ref;
\r
1908 return constructURI(final);
\r
1910 else if (ref.charAt(0) == "?")
\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
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
1922 if (uriReference.isAbsolute() ||
\r
1923 uriReference.isHierarchical() == false)
\r
1925 // If the URI given is a full URI, it replaces this one.
\r
1926 copyURI(uriReference);
\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
1939 thisPath = this.path;
\r
1940 thatPath = uriReference.path;
\r
1942 if (thisPath.length > 0)
\r
1943 thisParts = thisPath.split("/");
\r
1945 thisParts = new Array();
\r
1947 if (thatPath.length > 0)
\r
1948 thatParts = thatPath.split("/");
\r
1950 thatParts = new Array();
\r
1952 if (thisParts.length > 0 && thisParts[0] == "")
\r
1955 thisParts.shift(); // pop the first one off the array
\r
1957 if (thisParts.length > 0 && thisParts[thisParts.length - 1] == "")
\r
1960 thisParts.pop(); // pop the last one off the array
\r
1963 if (thatParts.length > 0 && thatParts[0] == "")
\r
1966 thatParts.shift(); // pop the first one off the array
\r
1968 if (thatParts.length > 0 && thatParts[thatParts.length - 1] == "")
\r
1971 thatParts.pop(); // pop the last one off the array
\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
1980 // And it inherits the query and fragment
\r
1981 this.queryRaw = uriReference.queryRaw;
\r
1982 this.fragment = uriReference.fragment;
\r
1986 else if (thatParts.length == 0 && uriReference.query == "")
\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
1995 else if (thisIsDir == false && thisParts.length > 0)
\r
1997 // This path ends in a file. It goes away no matter what.
\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
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
2009 for(i = 0; i < thisParts.length; i++)
\r
2011 curDir = thisParts[i];
\r
2012 lastIsDotOperation = false;
\r
2014 if (curDir == ".")
\r
2016 thisParts.splice(i, 1);
\r
2017 i = i - 1; // account for removing this item
\r
2018 lastIsDotOperation = true;
\r
2020 else if (curDir == "..")
\r
2024 if (thisParts[i - 1] == "..")
\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
2033 thisParts.splice(i - 1, 2);
\r
2034 i = i - 2; // move back to account for the 2 we removed
\r
2039 // This is the first thing in the path.
\r
2043 // We can't collapse leading ".."s in a relative
\r
2044 // path. Do noting.
\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
2063 thisParts.splice(i, 1);
\r
2064 i = i - 1; // account for the ".." we just removed
\r
2068 lastIsDotOperation = true;
\r
2072 var finalPath:String = "";
\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
2078 thatIsDir = thatIsDir || lastIsDotOperation;
\r
2080 // Reconstruct the path with the abs/dir info we have
\r
2081 finalPath = joinPath(thisParts, thisIsAbs, thatIsDir);
\r
2083 // Set the path (automatically escaping it)
\r
2084 this.path = finalPath;
\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
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
2102 * @return the combined path string.
\r
2104 protected function joinPath(parts:Array, isAbs:Boolean, isDir:Boolean) : String
\r
2106 var pathStr:String = "";
\r
2109 for (i = 0; i < parts.length; i++)
\r
2111 if (pathStr.length > 0)
\r
2114 pathStr += parts[i];
\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
2125 pathStr = "/" + pathStr;
\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
2135 * @param base_uri URI to use as the base from which to make
\r
2136 * this relative URI into an absolute URI.
\r
2138 * @return true if successful, false otherwise.
\r
2140 public function makeAbsoluteURI(base_uri:URI) : Boolean
\r
2142 if (isAbsolute() || base_uri.isRelative())
\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
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
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
2159 // It worked, so copy the base into this one
\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
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
2175 * uri1.MakeRelativePath(uri2);</listing>
\r
2177 * <p>uri1 will have a final value of "../some/file.html"</p>
\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
2184 * <p>../../../../../../some/path/to/my/file.html</p>
\r
2186 * @param base_uri the URI from which to make this URI relative
\r
2188 * @return true if successful, false if the base_uri and this URI
\r
2189 * are not related, of if error.
\r
2191 public function makeRelativeURI(base_uri:URI, caseSensitive:Boolean = true) : Boolean
\r
2193 var base:URI = new URI();
\r
2194 base.copyURI(base_uri);
\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
2203 var diff:Boolean = false;
\r
2204 var isDir:Boolean = false;
\r
2208 // We're already relative.
\r
2212 if (base.isRelative())
\r
2214 // The base is relative. A relative base doesn't make sense.
\r
2219 if ( (isOfType(base_uri.scheme) == false) ||
\r
2220 (this.authority != base_uri.authority) )
\r
2222 // The schemes and/or authorities are different. We can't
\r
2223 // make a relative path to something that is completely
\r
2228 // Record the state of this URI
\r
2229 isDir = isDirectory();
\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
2237 thisParts = pathStr.split("/");
\r
2238 thatParts = base.path.split("/");
\r
2240 if (thisParts.length > 0 && thisParts[0] == "")
\r
2241 thisParts.shift();
\r
2243 if (thisParts.length > 0 && thisParts[thisParts.length - 1] == "")
\r
2249 if (thatParts.length > 0 && thatParts[0] == "")
\r
2250 thatParts.shift();
\r
2251 if (thatParts.length > 0 && thatParts[thatParts.length - 1] == "")
\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
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
2271 // For every part left over in the base path, we prepend a ".."
\r
2272 // to the relative to get the final path:
\r
2274 while(thatParts.length > 0)
\r
2276 if (thisParts.length == 0)
\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
2286 thisPart = thisParts[0];
\r
2287 thatPart = thatParts[0];
\r
2289 if (compareStr(thisPart, thatPart, caseSensitive))
\r
2291 thisParts.shift();
\r
2292 thatParts.shift();
\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
2305 finalParts.push(dotdot);
\r
2308 // Append the parts of this URI to any dot-dot's we have
\r
2309 finalParts = finalParts.concat(thisParts);
\r
2311 // Join the parts back into a path
\r
2312 finalPath = joinPath(finalParts, false /* not absolute */, isDir);
\r
2314 if (finalPath.length == 0)
\r
2316 // The two URI's are exactly the same. The proper relative
\r
2321 // Set the parts of the URI, preserving the original query and
\r
2322 // fragment parts.
\r
2323 setParts("", "", "", finalPath, queryStr, fragmentStr);
\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
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
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
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
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
2363 * @return true if the given string was successfully parsed into
\r
2364 * a valid URI object, false otherwise.
\r
2366 public function unknownToURI(unknown:String, defaultScheme:String = "http") : Boolean
\r
2370 if (unknown.length == 0)
\r
2372 this.initialize();
\r
2376 // Some users love the backslash key. Fix it.
\r
2377 unknown = unknown.replace(/\\/g, "/");
\r
2379 // Check for any obviously missing scheme.
\r
2380 if (unknown.length >= 2)
\r
2382 temp = unknown.substr(0, 2);
\r
2384 unknown = defaultScheme + ":" + unknown;
\r
2387 if (unknown.length >= 3)
\r
2389 temp = unknown.substr(0, 3);
\r
2390 if (temp == "://")
\r
2391 unknown = defaultScheme + unknown;
\r
2394 // Try parsing it as a normal URI
\r
2395 var uri:URI = new URI(unknown);
\r
2397 if (uri.isHierarchical() == false)
\r
2399 if (uri.scheme == UNKNOWN_SCHEME)
\r
2401 this.initialize();
\r
2405 // It's a non-hierarchical URI
\r
2410 else if ((uri.scheme != UNKNOWN_SCHEME) &&
\r
2411 (uri.scheme.length > 0))
\r
2413 if ( (uri.authority.length > 0) ||
\r
2414 (uri.scheme == "file") )
\r
2418 forceEscape(); // ensure proper escaping
\r
2421 else if (uri.authority.length == 0 && uri.path.length == 0)
\r
2423 // It's is an incomplete URI (eg "http://")
\r
2425 setParts(uri.scheme, "", "", "", "", "");
\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
2436 if (path == ".." || path == "." ||
\r
2437 (path.length >= 3 && path.substr(0, 3) == "../") ||
\r
2438 (path.length >= 2 && path.substr(0, 2) == "./") )
\r
2440 // This is a relative URI.
\r
2447 // Ok, it looks like we are just a normal URI missing the scheme. Tack
\r
2449 uri = new URI(defaultScheme + "://" + unknown);
\r
2451 // Check to see if we are good now
\r
2452 if (uri.scheme.length > 0 && uri.authority.length > 0)
\r
2454 // It was just missing the scheme.
\r
2456 forceEscape(); // Make sure we are properly encoded.
\r
2460 // don't know what this is
\r
2461 this.initialize();
\r
2465 } // end URI class
\r
fnp / redakcja.git / blob