activemq-cpp/src/main/decaf/net/URL.h - activemq-cpp - Git at Google

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 #ifndef _DECAF_NET_URL_H_
 #define _DECAF_NET_URL_H_

 #include <decaf/util/Config.h>
 #include <decaf/lang/String.h>

 #include <decaf/io/InputStream.h>
 #include <string>

 namespace decaf {
 namespace net {

     class URI;
     class URLImpl;
     class URLStreamHandler;
     class URLStreamHandlerFactory;
     class URLConnection;
     class Proxy;

     /**
      * 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.
      *
      * @since 1.0
      */
     class DECAF_API URL {
     private:

         URLImpl* impl;

     public:

         /**
          * Creates a URL object from the String representation.
          *
          * This constructor is equivalent to a call to the two-argument constructor with
          * a empty first argument.
          *
          * @param url
          *      the String to parse as a URL.
          *
          * @throws MalformedURLException If the string specifies an unknown protocol.
          */
         URL(const decaf::lang::String& url);

         /**
          * Creates a URL by parsing the given spec within a specified context. The new URL is
          * created from the given context URL and the spec argument as described in RFC2396
          * "Uniform Resource Identifiers : Generic * Syntax" :
          *
          *     <scheme>://<authority><path>?<query>#<fragment>
          *
          * The reference is parsed into the scheme, authority, path, query and fragment parts.
          * If the path component is empty and the scheme, authority, and query components are
          * undefined, then the new URL is a reference to the current document. Otherwise, the
          * fragment and query parts present in the spec are used in the new URL.
          *
          * If the scheme component is defined in the given spec and does not match the scheme
          * of the context, then the new URL is created as an absolute URL based on the spec alone.
          * Otherwise the scheme component is inherited from the context URL.
          *
          * If the authority component is present in the spec then the spec is treated as absolute
          * and the spec authority and path will replace the context authority and path. If the
          * authority component is absent in the spec then the authority of the new URL will be
          * inherited from the context.
          *
          * If the spec's path component begins with a slash character "/" then the path is treated
          * as absolute and the spec path replaces the context path.
          *
          * Otherwise, the path is treated as a relative path and is appended to the context path,
          * as described in RFC2396. Also, in this case, the path is canonicalized through the
          * removal of directory changes made by occurrences of ".." and ".".
          *
          * For a more detailed description of URL parsing, refer to RFC2396.
          *
          * @param context
          *      the URL which is used as the context.
          * @param spec
          *      the URL string representation which has to be parsed.
          *
          * @throws MalformedURLException
          *      if the given string spec could not be parsed as a URL or an invalid
          *      protocol has been found.
          */
         URL(const URL& context, const decaf::lang::String& spec);

         /**
          * Creates a URL object from the specified protocol, host, port number, file, and
          * handler. Specifying a port number of -1 indicates that the URL should use the
          * default port for the protocol. Specifying a handler of null indicates that the
          * URL should use a default stream handler for the protocol, as outlined for:
          *
          *    URL(const String&, const String&, int, const String&)
          *
          * If a URLStreamHandler instance is provided then this class will take ownership
          * of the object and delete at a later time.
          *
          * @param protocol
          *      the name of the protocol to use.
          * @param host
          *      the name of the host.
          * @param port
          *      the port number on the host.
          * @param file
          *      the file on the host
          * @param handler
          *      the stream handler for the URL.
          *
          * @throws MalformedURLException if an unknown protocol is specified.
          */
         URL(const decaf::lang::String& protocol, const decaf::lang::String& host, int port,
             const decaf::lang::String& file, URLStreamHandler* handler);

         /**
          * Creates a URL from the specified protocol name, host name, and file name. The default
          * port for the specified protocol is used.
          *
          * This method is equivalent to calling the four-argument constructor with the arguments
          * being protocol, host, -1, and file. No validation of the inputs is performed by this
          * constructor.
          *
          * @param protocol
          *      the name of the protocol to use.
          * @param host
          *      the name of the host.
          * @param file
          *      the file on the host
          *
          * @throws MalformedURLException if an unknown protocol is specified.
          */
         URL(const decaf::lang::String& protocol, const decaf::lang::String& host, const decaf::lang::String& file);

         /**
          * Creates a new URL instance using the given arguments. The URL uses the
          * specified port instead of the default port for the given protocol.
          *
          * @param protocol
          *      the name of the protocol to use.
          * @param host
          *      the name of the host.
          * @param port
          *      the specific port number of the URL. Value of -1 represents the
          *      default port of the protocol.
          * @param file
          *      the name of the resource.
          *
          * @throws MalformedURLException
          *      if the combination of all arguments do not represent a valid
          *      URL or the protocol is invalid.
          */
         URL(const decaf::lang::String& protocol, const decaf::lang::String& host, int port, const decaf::lang::String& file);

         /**
          * Creates a URL by parsing the given spec with the specified handler within a
          * specified context. If the handler is NULL, the parsing occurs as with the two
          * argument constructor.
          *
          * If a stream handler instance is passed then this object takes ownership of it
          * and will destroy the resources when no longer needed.
          *
          * @param context
          *      the URL which is used as the context.
          * @param spec
          *      the URL string representation which has to be parsed.
          * @param handler
          *      the stream handler for the URL.
          *
          * @throws MalformedURLException if an unknown protocol is specified.
          */
         URL(const URL& context, const decaf::lang::String& spec, URLStreamHandler* handler);

         virtual ~URL();

     public:

         /**
          * Compares this URL for equality with another URL.
          *
          * Two URL objects are equal if they have the same protocol, reference equivalent
          * hosts, have the same port number on the host, and the same file and fragment
          * of the file.
          *
          * Two hosts are considered equivalent if both host names can be resolved into the
          * same IP addresses; else if either host name can't be resolved, the host names
          * must be equal without regard to case; or both host names equal to empty string.
          *
          * Since hosts comparison requires name resolution, this operation is a blocking operation.
          *
          * @return true if this URL is considered equal to the given URL instance.
          */
         bool equals(const URL& other) const;

         /**
          * Gets the authority part of this URL.
          *
          * @return the authority part of this URL.
          */
         decaf::lang::String getAuthority() const;

         /**
          * Gets the default port number of the protocol associated with this URL. If the URL
          * scheme or the URLStreamHandler for the URL do not define a default port number, then
          * -1 is returned.
          *
          * @return the default port for the given scheme.
          */
         int getDefaultPort() const;

         /**
          * Gets the file name of this URL. The returned file portion will be the same as getPath(),
          * plus the concatenation of the value of getQuery(), if any. If there is no query portion,
          * this method and getPath() will return identical results.
          *
          * @return the file name associated with this URL.
          */
         decaf::lang::String getFile() const;

         /**
          * Gets the host name of this URL, if applicable. The format of the host conforms to
          * RFC 2732, i.e. for a literal IPv6 address, this method will return the IPv6 address
          * enclosed in square brackets ('[' and ']').
          *
          * @return the host name for this URL.
          */
         decaf::lang::String getHost() const;

         /**
          * Gets the path part of this URL.
          *
          * @return the path part of this URL.
          */
         decaf::lang::String getPath() const;

         /**
          * Gets the user Info part of this URL.
          *
          * @return the user info part of this URL.
          */
         decaf::lang::String getUserInfo() const;

         /**
          * Gets the port of this URL.
          *
          * @return the port of this URL or -1 if not set.
          */
         int getPort() const;

         /**
          * Gets the protocol of this URL.
          *
          * @return the path part of this URL.
          */
         decaf::lang::String getProtocol() const;

         /**
          * Gets the query part of this URL.
          *
          * @return the query part of this URL or empty string if not set.
          */
         decaf::lang::String getQuery() const;

         /**
          * Gets the anchor or "reference" portion of this URL.
          *
          * @return the anchor or "reference" portion of this URL.
          */
         decaf::lang::String getRef() const;

         /**
          * Creates an integer hash code for this URL which is used in hash based collections.
          *
          * The hash code is based upon all the URL components relevant for URL comparison which
          * means that the host resolution may cause this operation to block.
          *
          * @return the integer has code for this URL.
          */
         int hashCode() const;

         /**
          * Returns a URLConnection object that represents a connection to the remote object
          * referred to by the URL.
          *
          * A new connection is opened every time by calling the openConnection method of the
          * protocol handler for this URL.
          *
          * If for the URL's protocol (such as HTTP), there exists a public, specialized
          * URLConnection subclass belonging to one of the following packages or one of their
          * subpackages: java.lang, java.io, java.util, java.net, the connection returned will
          * be of that subclass. For example, for HTTP an HttpURLConnection will be returned,
          * and for JAR a JarURLConnection will be returned.
          *
          * @return a new URLConnection instance for this URL.
          *
          * @throws IOException if an error occurs while opening the connection.
          */
         URLConnection* openConnection();

         /**
          * Same basic functionality as openConnection() is provided here, except that the connection
          * will be made through the specified proxy; Protocol handlers that do not support proxing
          * will ignore the proxy parameter and make a normal connection.
          *
          * @param proxy
          *      The proxy instance to use to make the connection.
          *
          * @return a new URLConnection instance for this URL.
          *
          * @throws IOException if an error occurs while opening the connection.
          * @throws IllegalArgumentException if proxy is null, or proxy has the wrong type.
          * @throws UnsupportedOperationException if this method is not supported.
          */
         URLConnection* openConnection(const Proxy* proxy);

         /**
          * Shortcut method to opens a connection to this URL and fetch an InputStream
          * for reading from that connection.
          *
          * @return an InputStream that reads from this URL's location.
          *
          * @throws IOException if an error occurs.
          */
         decaf::io::InputStream* openStream();

         /**
          * Compares this URL to the other ignoring the fragment portion to determine if both
          * reference the same remote object.
          *
          * @return true if both URL's reference the same external object.
          */
         bool sameFile(const URL& other) const;

         /**
          * Constructs a string representation of this URL, by calling the toExternalForm
          * method of the stream protocol handler for this object.
          *
          * @return the string representation of this URL.
          */
         decaf::lang::String toExternalForm() const;

         /**
          * Calls toExternalForm to create a string representation of this URL.
          *
          * @return the string representation of this URL.
          */
         std::string toString() const;

         /**
          * Returns a URI instance that is the equivalent of this URL.
          *
          * @return the URI that is the equivalent of this URL.
          */
         URI toURI() const;

     public:

         /**
          * Sets an application's URLStreamHandlerFactory. This method can be called at most once.
          *
          * The URLStreamHandlerFactory instance is used to construct a stream protocol handler
          * from a protocol name.  The provided factory becomes the property of this runtime and
          * will be deleted at shutdown.
          *
          * @param factory
          *      the desired factory.
          *
          * @throws Exception if there is already a set factory.
          */
         static void setURLStreamHandlerFactory(URLStreamHandlerFactory* factory);

     private:

         /**
          * Sets the fields of the URL. This is not a public method so that only URLStreamHandlers
          * can modify URL fields. URLs are otherwise constant.
          *
          * @param protocol
          *      the name of the protocol to use.
          * @param host
          *      the name of the host.
          * @param port
          *      the specific port number of the URL. Value of -1 represents the
          *      default port of the protocol.
          * @param file
          *      the file value.
          * @param ref
          *      the internal reference in the URL
          */
         void set(const decaf::lang::String& protocol, const decaf::lang::String& host, int port,
                  const decaf::lang::String& file, const decaf::lang::String& ref);

         /**
          * Sets the fields of the URL. This is not a public method so that only URLStreamHandlers
          * can modify URL fields. URLs are otherwise constant.
          *
          * @param protocol
          *      the name of the protocol to use.
          * @param host
          *      the name of the host.
          * @param port
          *      the specific port number of the URL. Value of -1 represents the
          *      default port of the protocol.
          * @param authority
          *      the authority value.
          * @param userInfo
          *      the user info value.
          * @param path
          *      the path value.
          * @param query
          *      the query value.
          * @param ref
          *      the internal reference in the URL
          */
         void set(const decaf::lang::String& protocol, const decaf::lang::String& host, int port,
                  const decaf::lang::String& authority, const decaf::lang::String& userInfo,
                  const decaf::lang::String& path, const decaf::lang::String& query,
                  const decaf::lang::String& ref);

         /**
          * Returns the URLStreamHandler configured for this URL, used to validate that
          * the operations performed by a protocol handler are only done on its own URL.
          */
         URLStreamHandler* getURLStreamHandler() const;

     private:

         void initialize(const URL* context, const decaf::lang::String& theSpec, URLStreamHandler* handler);
         void initialize(const decaf::lang::String& protocol, const decaf::lang::String& host, int port,
                         const decaf::lang::String& file, URLStreamHandler* handler);


         friend class URLStreamHandler;

     };

 }}

 #endif /*_DECAF_NET_URL_H_*/
	/*
	* Licensed to the Apache Software Foundation (ASF) under one or more
	* contributor license agreements. See the NOTICE file distributed with
	* this work for additional information regarding copyright ownership.
	* The ASF licenses this file to You under the Apache License, Version 2.0
	* (the "License"); you may not use this file except in compliance with
	* the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	#ifndef _DECAF_NET_URL_H_
	#define _DECAF_NET_URL_H_

	#include <decaf/util/Config.h>
	#include <decaf/lang/String.h>

	#include <decaf/io/InputStream.h>
	#include <string>

	namespace decaf {
	namespace net {

	class URI;
	class URLImpl;
	class URLStreamHandler;
	class URLStreamHandlerFactory;
	class URLConnection;
	class Proxy;

	/**
	* 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.
	*
	* @since 1.0
	*/
	class DECAF_API URL {
	private:

	URLImpl* impl;

	public:

	/**
	* Creates a URL object from the String representation.
	*
	* This constructor is equivalent to a call to the two-argument constructor with
	* a empty first argument.
	*
	* @param url
	* the String to parse as a URL.
	*
	* @throws MalformedURLException If the string specifies an unknown protocol.
	*/
	URL(const decaf::lang::String& url);

	/**
	* Creates a URL by parsing the given spec within a specified context. The new URL is
	* created from the given context URL and the spec argument as described in RFC2396
	* "Uniform Resource Identifiers : Generic * Syntax" :
	*
	* <scheme>://<authority><path>?<query>#<fragment>
	*
	* The reference is parsed into the scheme, authority, path, query and fragment parts.
	* If the path component is empty and the scheme, authority, and query components are
	* undefined, then the new URL is a reference to the current document. Otherwise, the
	* fragment and query parts present in the spec are used in the new URL.
	*
	* If the scheme component is defined in the given spec and does not match the scheme
	* of the context, then the new URL is created as an absolute URL based on the spec alone.
	* Otherwise the scheme component is inherited from the context URL.
	*
	* If the authority component is present in the spec then the spec is treated as absolute
	* and the spec authority and path will replace the context authority and path. If the
	* authority component is absent in the spec then the authority of the new URL will be
	* inherited from the context.
	*
	* If the spec's path component begins with a slash character "/" then the path is treated
	* as absolute and the spec path replaces the context path.
	*
	* Otherwise, the path is treated as a relative path and is appended to the context path,
	* as described in RFC2396. Also, in this case, the path is canonicalized through the
	* removal of directory changes made by occurrences of ".." and ".".
	*
	* For a more detailed description of URL parsing, refer to RFC2396.
	*
	* @param context
	* the URL which is used as the context.
	* @param spec
	* the URL string representation which has to be parsed.
	*
	* @throws MalformedURLException
	* if the given string spec could not be parsed as a URL or an invalid
	* protocol has been found.
	*/
	URL(const URL& context, const decaf::lang::String& spec);

	/**
	* Creates a URL object from the specified protocol, host, port number, file, and
	* handler. Specifying a port number of -1 indicates that the URL should use the
	* default port for the protocol. Specifying a handler of null indicates that the
	* URL should use a default stream handler for the protocol, as outlined for:
	*
	* URL(const String&, const String&, int, const String&)
	*
	* If a URLStreamHandler instance is provided then this class will take ownership
	* of the object and delete at a later time.
	*
	* @param protocol
	* the name of the protocol to use.
	* @param host
	* the name of the host.
	* @param port
	* the port number on the host.
	* @param file
	* the file on the host
	* @param handler
	* the stream handler for the URL.
	*
	* @throws MalformedURLException if an unknown protocol is specified.
	*/
	URL(const decaf::lang::String& protocol, const decaf::lang::String& host, int port,
	const decaf::lang::String& file, URLStreamHandler* handler);

	/**
	* Creates a URL from the specified protocol name, host name, and file name. The default
	* port for the specified protocol is used.
	*
	* This method is equivalent to calling the four-argument constructor with the arguments
	* being protocol, host, -1, and file. No validation of the inputs is performed by this
	* constructor.
	*
	* @param protocol
	* the name of the protocol to use.
	* @param host
	* the name of the host.
	* @param file
	* the file on the host
	*
	* @throws MalformedURLException if an unknown protocol is specified.
	*/
	URL(const decaf::lang::String& protocol, const decaf::lang::String& host, const decaf::lang::String& file);

	/**
	* Creates a new URL instance using the given arguments. The URL uses the
	* specified port instead of the default port for the given protocol.
	*
	* @param protocol
	* the name of the protocol to use.
	* @param host
	* the name of the host.
	* @param port
	* the specific port number of the URL. Value of -1 represents the
	* default port of the protocol.
	* @param file
	* the name of the resource.
	*
	* @throws MalformedURLException
	* if the combination of all arguments do not represent a valid
	* URL or the protocol is invalid.
	*/
	URL(const decaf::lang::String& protocol, const decaf::lang::String& host, int port, const decaf::lang::String& file);

	/**
	* Creates a URL by parsing the given spec with the specified handler within a
	* specified context. If the handler is NULL, the parsing occurs as with the two
	* argument constructor.
	*
	* If a stream handler instance is passed then this object takes ownership of it
	* and will destroy the resources when no longer needed.
	*
	* @param context
	* the URL which is used as the context.
	* @param spec
	* the URL string representation which has to be parsed.
	* @param handler
	* the stream handler for the URL.
	*
	* @throws MalformedURLException if an unknown protocol is specified.
	*/
	URL(const URL& context, const decaf::lang::String& spec, URLStreamHandler* handler);

	virtual ~URL();

	public:

	/**
	* Compares this URL for equality with another URL.
	*
	* Two URL objects are equal if they have the same protocol, reference equivalent
	* hosts, have the same port number on the host, and the same file and fragment
	* of the file.
	*
	* Two hosts are considered equivalent if both host names can be resolved into the
	* same IP addresses; else if either host name can't be resolved, the host names
	* must be equal without regard to case; or both host names equal to empty string.
	*
	* Since hosts comparison requires name resolution, this operation is a blocking operation.
	*
	* @return true if this URL is considered equal to the given URL instance.
	*/
	bool equals(const URL& other) const;

	/**
	* Gets the authority part of this URL.
	*
	* @return the authority part of this URL.
	*/
	decaf::lang::String getAuthority() const;

	/**
	* Gets the default port number of the protocol associated with this URL. If the URL
	* scheme or the URLStreamHandler for the URL do not define a default port number, then
	* -1 is returned.
	*
	* @return the default port for the given scheme.
	*/
	int getDefaultPort() const;

	/**
	* Gets the file name of this URL. The returned file portion will be the same as getPath(),
	* plus the concatenation of the value of getQuery(), if any. If there is no query portion,
	* this method and getPath() will return identical results.
	*
	* @return the file name associated with this URL.
	*/
	decaf::lang::String getFile() const;

	/**
	* Gets the host name of this URL, if applicable. The format of the host conforms to
	* RFC 2732, i.e. for a literal IPv6 address, this method will return the IPv6 address
	* enclosed in square brackets ('[' and ']').
	*
	* @return the host name for this URL.
	*/
	decaf::lang::String getHost() const;

	/**
	* Gets the path part of this URL.
	*
	* @return the path part of this URL.
	*/
	decaf::lang::String getPath() const;

	/**
	* Gets the user Info part of this URL.
	*
	* @return the user info part of this URL.
	*/
	decaf::lang::String getUserInfo() const;

	/**
	* Gets the port of this URL.
	*
	* @return the port of this URL or -1 if not set.
	*/
	int getPort() const;

	/**
	* Gets the protocol of this URL.
	*
	* @return the path part of this URL.
	*/
	decaf::lang::String getProtocol() const;

	/**
	* Gets the query part of this URL.
	*
	* @return the query part of this URL or empty string if not set.
	*/
	decaf::lang::String getQuery() const;

	/**
	* Gets the anchor or "reference" portion of this URL.
	*
	* @return the anchor or "reference" portion of this URL.
	*/
	decaf::lang::String getRef() const;

	/**
	* Creates an integer hash code for this URL which is used in hash based collections.
	*
	* The hash code is based upon all the URL components relevant for URL comparison which
	* means that the host resolution may cause this operation to block.
	*
	* @return the integer has code for this URL.
	*/
	int hashCode() const;

	/**
	* Returns a URLConnection object that represents a connection to the remote object
	* referred to by the URL.
	*
	* A new connection is opened every time by calling the openConnection method of the
	* protocol handler for this URL.
	*
	* If for the URL's protocol (such as HTTP), there exists a public, specialized
	* URLConnection subclass belonging to one of the following packages or one of their
	* subpackages: java.lang, java.io, java.util, java.net, the connection returned will
	* be of that subclass. For example, for HTTP an HttpURLConnection will be returned,
	* and for JAR a JarURLConnection will be returned.
	*
	* @return a new URLConnection instance for this URL.
	*
	* @throws IOException if an error occurs while opening the connection.
	*/
	URLConnection* openConnection();

	/**
	* Same basic functionality as openConnection() is provided here, except that the connection
	* will be made through the specified proxy; Protocol handlers that do not support proxing
	* will ignore the proxy parameter and make a normal connection.
	*
	* @param proxy
	* The proxy instance to use to make the connection.
	*
	* @return a new URLConnection instance for this URL.
	*
	* @throws IOException if an error occurs while opening the connection.
	* @throws IllegalArgumentException if proxy is null, or proxy has the wrong type.
	* @throws UnsupportedOperationException if this method is not supported.
	*/
	URLConnection* openConnection(const Proxy* proxy);

	/**
	* Shortcut method to opens a connection to this URL and fetch an InputStream
	* for reading from that connection.
	*
	* @return an InputStream that reads from this URL's location.
	*
	* @throws IOException if an error occurs.
	*/
	decaf::io::InputStream* openStream();

	/**
	* Compares this URL to the other ignoring the fragment portion to determine if both
	* reference the same remote object.
	*
	* @return true if both URL's reference the same external object.
	*/
	bool sameFile(const URL& other) const;

	/**
	* Constructs a string representation of this URL, by calling the toExternalForm
	* method of the stream protocol handler for this object.
	*
	* @return the string representation of this URL.
	*/
	decaf::lang::String toExternalForm() const;

	/**
	* Calls toExternalForm to create a string representation of this URL.
	*
	* @return the string representation of this URL.
	*/
	std::string toString() const;

	/**
	* Returns a URI instance that is the equivalent of this URL.
	*
	* @return the URI that is the equivalent of this URL.
	*/
	URI toURI() const;

	public:

	/**
	* Sets an application's URLStreamHandlerFactory. This method can be called at most once.
	*
	* The URLStreamHandlerFactory instance is used to construct a stream protocol handler
	* from a protocol name. The provided factory becomes the property of this runtime and
	* will be deleted at shutdown.
	*
	* @param factory
	* the desired factory.
	*
	* @throws Exception if there is already a set factory.
	*/
	static void setURLStreamHandlerFactory(URLStreamHandlerFactory* factory);

	private:

	/**
	* Sets the fields of the URL. This is not a public method so that only URLStreamHandlers
	* can modify URL fields. URLs are otherwise constant.
	*
	* @param protocol
	* the name of the protocol to use.
	* @param host
	* the name of the host.
	* @param port
	* the specific port number of the URL. Value of -1 represents the
	* default port of the protocol.
	* @param file
	* the file value.
	* @param ref
	* the internal reference in the URL
	*/
	void set(const decaf::lang::String& protocol, const decaf::lang::String& host, int port,
	const decaf::lang::String& file, const decaf::lang::String& ref);

	/**
	* Sets the fields of the URL. This is not a public method so that only URLStreamHandlers
	* can modify URL fields. URLs are otherwise constant.
	*
	* @param protocol
	* the name of the protocol to use.
	* @param host
	* the name of the host.
	* @param port
	* the specific port number of the URL. Value of -1 represents the
	* default port of the protocol.
	* @param authority
	* the authority value.
	* @param userInfo
	* the user info value.
	* @param path
	* the path value.
	* @param query
	* the query value.
	* @param ref
	* the internal reference in the URL
	*/
	void set(const decaf::lang::String& protocol, const decaf::lang::String& host, int port,
	const decaf::lang::String& authority, const decaf::lang::String& userInfo,
	const decaf::lang::String& path, const decaf::lang::String& query,
	const decaf::lang::String& ref);

	/**
	* Returns the URLStreamHandler configured for this URL, used to validate that
	* the operations performed by a protocol handler are only done on its own URL.
	*/
	URLStreamHandler* getURLStreamHandler() const;

	private:

	void initialize(const URL* context, const decaf::lang::String& theSpec, URLStreamHandler* handler);
	void initialize(const decaf::lang::String& protocol, const decaf::lang::String& host, int port,
	const decaf::lang::String& file, URLStreamHandler* handler);


	friend class URLStreamHandler;

	};

	}}

	#endif /_DECAF_NET_URL_H_/