svn commit: r667784 - /activemq/activemq-cpp/trunk/src/main/decaf/net/URL.h

[ta...@apache.org]

Author: tabish
Date: Sat Jun 14 05:29:35 2008
New Revision: 667784

URL: http://svn.apache.org/viewvc?rev=667784&view=rev
Log:
Workong on enhancing the functionality of Decaf

Modified:
    activemq/activemq-cpp/trunk/src/main/decaf/net/URL.h

Modified: activemq/activemq-cpp/trunk/src/main/decaf/net/URL.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/src/main/decaf/net/URL.h?rev=667784&r1=667783&r2=667784&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/src/main/decaf/net/URL.h (original)
+++ activemq/activemq-cpp/trunk/src/main/decaf/net/URL.h Sat Jun 14 05:29:35 2008
@@ -23,6 +23,85 @@
 namespace decaf{
 namespace net{
 
+    /**
+     * Class URL represents a Uniform Resource Locator, a pointer to a "resource"
+     * on the World Wide Web. A resource can be something as simple as a file
+     * or a directory, or it can be a reference to a more complicated object,
+     * such as a query to a database or to a search engine. More information on
+     * the types of URLs and their formats can be found at:
+     *
+     *  http://www.ksc.nasa.gov/facts/internet/url-primer.html
+     *
+     * In general, a URL can be broken into several parts. The previous example
+     * of a URL indicates that the protocol to use is http (HyperText Transfer
+     * Protocol) and that the information resides on a host machine named
+     * www.ksc.nasa.gov. The information on that host machine is named
+     * /facts/internet/url-primer.html. The exact meaning of this name on the
+     * host machine is both protocol dependent and host dependent. The information
+     * normally resides in a file, but it could be generated on the fly. This
+     * component of the URL is called the path component.
+     *
+     * A URL can optionally specify a "port", which is the port number to which
+     * the TCP connection is made on the remote host machine. If the port is not
+     * specified, the default port for the protocol is used instead. For example,
+     * the default port for http is 80. An alternative port could be specified as:
+     *
+     *  http://www.ksc.nasa.gov:80/facts/internet/url-primer.html
+     *
+     * The syntax of URL is defined by RFC 2396: Uniform Resource Identifiers (URI):
+     * Generic Syntax, amended by RFC 2732: Format for Literal IPv6 Addresses in URLs.
+     * The Literal IPv6 address format also supports scope_ids. The syntax and usage
+     * of scope_ids is described here.
+     *
+     * A URL may have appended to it a "fragment", also known as a "ref" or a
+     * "reference". The fragment is indicated by the sharp sign character "#" followed
+     * by more characters. For example,
+     *
+     *  http://www.apache.org/cms/index.html#chapter1
+     *
+     * This fragment is not technically part of the URL. Rather, it indicates that
+     * after the specified resource is retrieved, the application is specifically
+     * interested in that part of the document that has the tag chapter1 attached to
+     * it. The meaning of a tag is resource specific.
+     *
+     * An application can also specify a "relative URL", which contains only enough
+     * information to reach the resource relative to another URL. Relative URLs
+     * are frequently used within HTML pages. For example, if the contents of the URL:
+     *
+     *  http://www.apache.org/cms/index.html
+     *
+     * contained within it the relative URL:
+     *
+     *  FAQ.html
+     *
+     * it would be a shorthand for:
+     *
+     *  http://www.apache.org/cms/FAQ.html
+     *
+     * The relative URL need not specify all the components of a URL. If the protocol,
+     * host name, or port number is missing, the value is inherited from the fully
+     * specified URL. The file component must be specified. The optional fragment is
+     * not inherited.
+     *
+     * The URL class does not itself encode or decode any URL components according
+     * to the escaping mechanism defined in RFC2396. It is the responsibility of the
+     * caller to encode any fields, which need to be escaped prior to calling URL,
+     * and also to decode any escaped fields, that are returned from URL. Furthermore,
+     * because URL has no knowledge of URL escaping, it does not recognise equivalence
+     * between the encoded or decoded form of the same URL. For example, the two URLs:
+     *
+     *  http://foo.com/hello world/ and http://foo.com/hello%20world
+     *
+     * would be considered not equal to each other.
+     *
+     * Note, the URI class does perform escaping of its component fields in certain
+     * circumstances. The recommended way to manage the encoding and decoding of URLs
+     * is to use URI, and to convert between these two classes using toURI() and
+     * URI.toURL().
+     *
+     * The URLEncoder and URLDecoder classes can also be used, but only for HTML form
+     * encoding, which is not the same as the encoding scheme defined in RFC2396.
+     */
     class DECAF_API URL {
     public: