1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 /*

    18  * Licensed to the Apache Software Foundation (ASF) under one or more

    19  * contributor license agreements.  See the NOTICE file distributed with

    20  * this work for additional information regarding copyright ownership.

    21  * The ASF licenses this file to You under the Apache License, Version 2.0

    22  * (the "License"); you may not use this file except in compliance with

    23  * the License.  You may obtain a copy of the License at

    24  * 

    25  *      http://www.apache.org/licenses/LICENSE-2.0

    26  * 

    27  * Unless required by applicable law or agreed to in writing, software

    28  * distributed under the License is distributed on an "AS IS" BASIS,

    29  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    30  * See the License for the specific language governing permissions and

    31  * limitations under the License.

    32  */

    33 

    34 /*

    35  * $Id: XMLUri.hpp 568078 2007-08-21 11:43:25Z amassari $

    36  */

    37 

    38 #if !defined(XMLURI_HPP)

    39 #define XMLURI_HPP

    40 

    41 #include <xercesc/util/XMemory.hpp>

    42 #include <xercesc/util/XMLString.hpp>

    43 

    44 #include <xercesc/internal/XSerializable.hpp>

    45 #include <xercesc/framework/XMLBuffer.hpp>

    46 

    47 XERCES_CPP_NAMESPACE_BEGIN

    48 

    49 /*

    50  * This class is a direct port of Java's URI class, to distinguish

    51  * itself from the XMLURL, we use the name XMLUri instead of

    52  * XMLURI.

    53  *

    54  * TODO: how to relate XMLUri and XMLURL since URL is part of URI.

    55  *

    56  */

    57 

    58 class XMLUTIL_EXPORT XMLUri : public XSerializable, public XMemory

    59 {

    60 public:

    61 

    62     // -----------------------------------------------------------------------

    63     //  Constructors and Destructor

    64     // -----------------------------------------------------------------------

    65 

    66     /**

    67      * Construct a new URI from a URI specification string.

    68      *

    69      * If the specification follows the "generic URI" syntax, (two slashes

    70      * following the first colon), the specification will be parsed

    71      * accordingly - setting the

    72      *                           scheme,

    73      *                           userinfo,

    74      *                           host,

    75      *                           port,

    76      *                           path,

    77      *                           querystring and

    78      *                           fragment

    79      * fields as necessary.

    80      *

    81      * If the specification does not follow the "generic URI" syntax,

    82      * the specification is parsed into a

    83      *                           scheme and

    84      *                           scheme-specific part (stored as the path) only.

    85      *

    86      * @param uriSpec the URI specification string (cannot be null or empty)

    87      *

    88      * @param manager Pointer to the memory manager to be used to

    89      *                allocate objects.

    90      *

    91      * ctor# 2

    92      *

    93      */

    94     XMLUri(const XMLCh* const    uriSpec,

    95            MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager);

    96 

    97     /**

    98      * Construct a new URI from a base URI and a URI specification string.

    99      * The URI specification string may be a relative URI.

   100      *

   101      * @param baseURI the base URI (cannot be null if uriSpec is null or

   102      *                empty)

   103      *

   104      * @param uriSpec the URI specification string (cannot be null or

   105      *                empty if base is null)

   106      *

   107      * @param manager Pointer to the memory manager to be used to

   108      *                allocate objects.

   109      *

   110      * ctor# 7 relative ctor

   111      *

   112      */

   113     XMLUri(const XMLUri* const  baseURI

   114          , const XMLCh* const   uriSpec

   115          , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager);

   116 

   117     /**

   118      * Copy constructor

   119      */

   120     XMLUri(const XMLUri& toCopy);

   121     XMLUri& operator=(const XMLUri& toAssign);

   122 

   123     virtual ~XMLUri();

   124 

   125     // -----------------------------------------------------------------------

   126     //  Getter methods

   127     // -----------------------------------------------------------------------

   128     /**

   129      * Get the URI as a string specification. See RFC 2396 Section 5.2.

   130      *

   131      * @return the URI string specification

   132      */

   133     const XMLCh* getUriText() const;

   134 

   135     /**

   136      * Get the scheme for this URI.

   137      *

   138      * @return the scheme for this URI

   139      */

   140      const XMLCh* getScheme() const;

   141 

   142     /**

   143      * Get the userinfo for this URI.

   144      *

   145      * @return the userinfo for this URI (null if not specified).

   146      */

   147      const XMLCh* getUserInfo() const;

   148 

   149 

   150     /**

   151      * Get the host for this URI.

   152      *

   153      * @return the host for this URI (null if not specified).

   154      */

   155      const XMLCh* getHost() const;

   156 

   157     /**

   158      * Get the port for this URI.

   159      *

   160      * @return the port for this URI (-1 if not specified).

   161      */

   162      int getPort() const;

   163      

   164     /**

   165      * Get the registry based authority for this URI.

   166      * 

   167      * @return the registry based authority (null if not specified).

   168      */

   169      const XMLCh* getRegBasedAuthority() const;

   170 

   171     /**

   172      * Get the path for this URI. Note that the value returned is the path

   173      * only and does not include the query string or fragment.

   174      *

   175      * @return the path for this URI.

   176      */

   177      const XMLCh* getPath() const;

   178 

   179     /**

   180      * Get the query string for this URI.

   181      *

   182      * @return the query string for this URI. Null is returned if there

   183      *         was no "?" in the URI spec, empty string if there was a

   184      *         "?" but no query string following it.

   185      */

   186      const XMLCh* getQueryString() const;

   187 

   188     /**

   189      * Get the fragment for this URI.

   190      *

   191      * @return the fragment for this URI. Null is returned if there

   192      *         was no "#" in the URI spec, empty string if there was a

   193      *         "#" but no fragment following it.

   194      */

   195      const XMLCh* getFragment() const;

   196 

   197     // -----------------------------------------------------------------------

   198     //  Setter methods

   199     // -----------------------------------------------------------------------

   200 

   201     /**

   202      * Set the scheme for this URI. The scheme is converted to lowercase

   203      * before it is set.

   204      *

   205      * @param newScheme the scheme for this URI (cannot be null)

   206      *

   207      */

   208      void setScheme(const XMLCh* const newScheme);

   209 

   210     /**

   211      * Set the userinfo for this URI. If a non-null value is passed in and

   212      * the host value is null, then an exception is thrown.

   213      *

   214      * @param newUserInfo the userinfo for this URI

   215      *

   216      */

   217      void setUserInfo(const XMLCh* const newUserInfo);

   218 

   219     /**

   220      * Set the host for this URI. If null is passed in, the userinfo

   221      * field is also set to null and the port is set to -1.

   222      *

   223      * Note: This method overwrites registry based authority if it

   224      * previously existed in this URI.

   225      *

   226      * @param newHost the host for this URI

   227      *

   228      */

   229      void setHost(const XMLCh* const newHost);

   230 

   231     /**

   232      * Set the port for this URI. -1 is used to indicate that the port is

   233      * not specified, otherwise valid port numbers are  between 0 and 65535.

   234      * If a valid port number is passed in and the host field is null,

   235      * an exception is thrown.

   236      *

   237      * @param newPort the port number for this URI

   238      *

   239      */

   240      void setPort(int newPort);

   241      

   242     /**

   243      * Sets the registry based authority for this URI.

   244      * 

   245      * Note: This method overwrites server based authority

   246      * if it previously existed in this URI.

   247      * 

   248      * @param newRegAuth the registry based authority for this URI

   249      */

   250      void setRegBasedAuthority(const XMLCh* const newRegAuth);

   251 

   252     /**

   253      * Set the path for this URI.

   254      *

   255      * If the supplied path is null, then the

   256      * query string and fragment are set to null as well.

   257      *

   258      * If the supplied path includes a query string and/or fragment,

   259      * these fields will be parsed and set as well.

   260      *

   261      * Note:

   262      *

   263      * For URIs following the "generic URI" syntax, the path

   264      * specified should start with a slash.

   265      *

   266      * For URIs that do not follow the generic URI syntax, this method

   267      * sets the scheme-specific part.

   268      *

   269      * @param newPath the path for this URI (may be null)

   270      *

   271      */

   272      void setPath(const XMLCh* const newPath);

   273 

   274     /**

   275      * Set the query string for this URI. A non-null value is valid only

   276      * if this is an URI conforming to the generic URI syntax and

   277      * the path value is not null.

   278      *

   279      * @param newQueryString the query string for this URI

   280      *

   281      */

   282      void setQueryString(const XMLCh* const newQueryString);

   283 

   284     /**

   285      * Set the fragment for this URI. A non-null value is valid only

   286      * if this is a URI conforming to the generic URI syntax and

   287      * the path value is not null.

   288      *

   289      * @param newFragment the fragment for this URI

   290      *

   291      */

   292      void setFragment(const XMLCh* const newFragment);

   293 

   294      // -----------------------------------------------------------------------

   295     //  Miscellaneous methods

   296     // -----------------------------------------------------------------------

   297 

   298     /**

   299      * Determine whether a given string contains only URI characters (also

   300      * called "uric" in RFC 2396). uric consist of all reserved

   301      * characters, unreserved characters and escaped characters.

   302      *

   303      * @return true if the string is comprised of uric, false otherwise

   304      */

   305     static bool isURIString(const XMLCh* const uric);

   306 

   307     /**

   308      * Determine whether a given string is a valid URI

   309      */

   310     static bool isValidURI( const XMLUri* const baseURI

   311                           , const XMLCh* const uriStr);

   312     /**

   313      * Determine whether a given string is a valid URI

   314      */

   315     static bool isValidURI( bool haveBaseURI

   316                           , const XMLCh* const uriStr);

   317 

   318 

   319     static void normalizeURI(const XMLCh*     const systemURI,

   320                                    XMLBuffer&       normalizedURI);

   321 

   322     /***

   323      * Support for Serialization/De-serialization

   324      ***/

   325     DECL_XSERIALIZABLE(XMLUri)

   326 

   327     XMLUri(MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager);

   328 

   329 private:

   330 

   331     static const XMLCh MARK_OR_RESERVED_CHARACTERS[];

   332     static const XMLCh RESERVED_CHARACTERS[];

   333     static const XMLCh MARK_CHARACTERS[];

   334     static const XMLCh SCHEME_CHARACTERS[];

   335     static const XMLCh USERINFO_CHARACTERS[];

   336     static const XMLCh REG_NAME_CHARACTERS[];

   337     static const XMLCh PATH_CHARACTERS[];

   338 

   339     //helper method for getUriText

   340     void buildFullText();

   341 

   342     // -----------------------------------------------------------------------

   343     //  Private helper methods

   344     // -----------------------------------------------------------------------

   345 

   346     /**

   347      * Determine whether a character is a reserved character:

   348      *

   349      * @return true if the string contains any reserved characters

   350      */

   351     static bool isReservedCharacter(const XMLCh theChar);

   352     

   353     /**

   354      * Determine whether a character is a path character:

   355      *

   356      * @return true if the character is path character

   357      */

   358     static bool isPathCharacter(const XMLCh theChar);

   359 

   360     /**

   361      * Determine whether a char is an unreserved character.

   362      *

   363      * @return true if the char is unreserved, false otherwise

   364      */

   365     static bool isUnreservedCharacter(const XMLCh theChar);

   366 

   367     /**

   368      * Determine whether a char is an reserved or unreserved character.

   369      *

   370      * @return true if the char is reserved or unreserved, false otherwise

   371      */                

   372     static bool isReservedOrUnreservedCharacter(const XMLCh theChar);

   373 

   374     /**

   375      * Determine whether a scheme conforms to the rules for a scheme name.

   376      * A scheme is conformant if it starts with an alphanumeric, and

   377      * contains only alphanumerics, '+','-' and '.'.

   378      *

   379      * @return true if the scheme is conformant, false otherwise

   380      */

   381     static bool isConformantSchemeName(const XMLCh* const scheme);

   382 

   383     /**

   384      * Determine whether a userInfo conforms to the rules for a userinfo.

   385      *

   386      * @return true if the scheme is conformant, false otherwise

   387      */

   388     static void isConformantUserInfo(const XMLCh* const userInfo

   389         , MemoryManager* const manager);

   390     

   391     /**

   392      * Determines whether the components host, port, and user info

   393      * are valid as a server authority.

   394      *

   395      * @return true if the given host, port, and userinfo compose

   396      * a valid server authority

   397      */

   398     static bool isValidServerBasedAuthority(const XMLCh* const host

   399                                            , const int hostLen

   400                                            , const int port

   401                                            , const XMLCh* const userinfo

   402                                            , const int userLen);

   403                                            

   404     /**

   405      * Determines whether the components host, port, and user info

   406      * are valid as a server authority.

   407      *

   408      * @return true if the given host, port, and userinfo compose

   409      * a valid server authority

   410      */

   411     static bool isValidServerBasedAuthority(const XMLCh* const host

   412                                            , const int port

   413                                            , const XMLCh* const userinfo

   414                                            , MemoryManager* const manager);

   415       

   416    /**

   417     * Determines whether the given string is a registry based authority.

   418     * 

   419     * @param authority the authority component of a URI

   420     * 

   421     * @return true if the given string is a registry based authority

   422     */

   423     static bool isValidRegistryBasedAuthority(const XMLCh* const authority

   424                                              , const int authLen);

   425 

   426    /**

   427     * Determines whether the given string is a registry based authority.

   428     * 

   429     * @param authority the authority component of a URI

   430     * 

   431     * @return true if the given string is a registry based authority

   432     */

   433     static bool isValidRegistryBasedAuthority(const XMLCh* const authority);

   434 

   435     /**

   436      * Determine whether a string is syntactically capable of representing

   437      * a valid IPv4 address, IPv6 reference or the domain name of a network host.

   438      *

   439      * A valid IPv4 address consists of four decimal digit groups

   440      * separated by a '.'.

   441      *

   442      * See RFC 2732 Section 3, and RFC 2373 Section 2.2, for the 

   443      * definition of IPv6 references.

   444      *

   445      * A hostname consists of domain labels (each of which must begin and

   446      * end with an alphanumeric but may contain '-') separated by a '.'.

   447      * See RFC 2396 Section 3.2.2.

   448      *

   449      * @return true if the string is a syntactically valid IPv4 address

   450      *              or hostname

   451      */

   452      static bool isWellFormedAddress(const XMLCh* const addr

   453          , MemoryManager* const manager);

   454      

   455     /**

   456      * Determines whether a string is an IPv4 address as defined by 

   457      * RFC 2373, and under the further constraint that it must be a 32-bit

   458      * address. Though not expressed in the grammar, in order to satisfy 

   459      * the 32-bit address constraint, each segment of the address cannot 

   460      * be greater than 255 (8 bits of information).

   461      *

   462      * @return true if the string is a syntactically valid IPv4 address

   463      */

   464      static bool isWellFormedIPv4Address(const XMLCh* const addr, const int length);

   465      

   466     /**

   467      * Determines whether a string is an IPv6 reference as defined

   468      * by RFC 2732, where IPv6address is defined in RFC 2373. The 

   469      * IPv6 address is parsed according to Section 2.2 of RFC 2373,

   470      * with the additional constraint that the address be composed of

   471      * 128 bits of information.

   472      *

   473      * Note: The BNF expressed in RFC 2373 Appendix B does not 

   474      * accurately describe section 2.2, and was in fact removed from

   475      * RFC 3513, the successor of RFC 2373.

   476      *

   477      * @return true if the string is a syntactically valid IPv6 reference

   478      */

   479      static bool isWellFormedIPv6Reference(const XMLCh* const addr, const int length);

   480      

   481     /**

   482      * Helper function for isWellFormedIPv6Reference which scans the 

   483      * hex sequences of an IPv6 address. It returns the index of the 

   484      * next character to scan in the address, or -1 if the string 

   485      * cannot match a valid IPv6 address. 

   486      *

   487      * @param address the string to be scanned

   488      * @param index the beginning index (inclusive)

   489      * @param end the ending index (exclusive)

   490      * @param counter a counter for the number of 16-bit sections read

   491      * in the address

   492      *

   493      * @return the index of the next character to scan, or -1 if the

   494      * string cannot match a valid IPv6 address

   495      */

   496      static int scanHexSequence (const XMLCh* const addr, int index, int end, int& counter);

   497 

   498     /**

   499      * Get the indicator as to whether this URI uses the "generic URI"

   500      * syntax.

   501      *

   502      * @return true if this URI uses the "generic URI" syntax, false

   503      *         otherwise

   504      */

   505      bool isGenericURI();

   506 

   507     // -----------------------------------------------------------------------

   508     //  Miscellaneous methods

   509     // -----------------------------------------------------------------------

   510 

   511     /**

   512      * Initialize all fields of this URI from another URI.

   513      *

   514      * @param toCopy the URI to copy (cannot be null)

   515      */

   516      void initialize(const XMLUri& toCopy);

   517 

   518     /**

   519      * Initializes this URI from a base URI and a URI specification string.

   520      * See RFC 2396 Section 4 and Appendix B for specifications on parsing

   521      * the URI and Section 5 for specifications on resolving relative URIs

   522      * and relative paths.

   523      *

   524      * @param baseURI the base URI (may be null if uriSpec is an absolute

   525      *               URI)

   526      *

   527      * @param uriSpec the URI spec string which may be an absolute or

   528      *                  relative URI (can only be null/empty if base

   529      *                  is not null)

   530      *

   531      */

   532      void initialize(const XMLUri* const baseURI

   533                    , const XMLCh*  const uriSpec);

   534 

   535     /**

   536      * Initialize the scheme for this URI from a URI string spec.

   537      *

   538      * @param uriSpec the URI specification (cannot be null)

   539      *

   540      */

   541      void initializeScheme(const XMLCh* const uriSpec);

   542 

   543     /**

   544      * Initialize the authority (userinfo, host and port) for this

   545      * URI from a URI string spec.

   546      *

   547      * @param uriSpec the URI specification (cannot be null)

   548      *

   549      */

   550      void initializeAuthority(const XMLCh* const uriSpec);

   551 

   552     /**

   553      * Initialize the path for this URI from a URI string spec.

   554      *

   555      * @param uriSpec the URI specification (cannot be null)

   556      *

   557      */

   558      void initializePath(const XMLCh* const uriSpec);

   559 

   560      /**

   561       * cleanup the data variables

   562       *

   563       */

   564      void cleanUp();

   565 

   566     static bool isConformantSchemeName(const XMLCh* const scheme,

   567                                        const int schemeLen);

   568     static bool processScheme(const XMLCh* const uriStr, int& index);

   569     static bool processAuthority(const XMLCh* const uriStr, const int authLen);

   570     static bool isWellFormedAddress(const XMLCh* const addr, const int addrLen);

   571     static bool processPath(const XMLCh* const pathStr, const int pathStrLen,

   572                             const bool isSchemePresent);

   573 

   574     // -----------------------------------------------------------------------

   575     //  Data members

   576     //

   577     //  for all the data member, we own it,

   578     //  responsible for the creation and/or deletion for

   579     //  the memory allocated.

   580     //

   581     // -----------------------------------------------------------------------

   582     int             fPort;

   583     XMLCh*          fScheme;

   584     XMLCh*          fUserInfo;

   585     XMLCh*          fHost;

   586     XMLCh*          fRegAuth;

   587     XMLCh*          fPath;

   588     XMLCh*          fQueryString;

   589     XMLCh*          fFragment;

   590     XMLCh*          fURIText;

   591     MemoryManager*  fMemoryManager;

   592 };

   593 

   594 // ---------------------------------------------------------------------------

   595 //  XMLUri: Getter methods

   596 // ---------------------------------------------------------------------------

   597 inline const XMLCh* XMLUri::getScheme() const

   598 {

   599     return fScheme;

   600 }

   601 

   602 inline const XMLCh* XMLUri::getUserInfo() const

   603 {

   604 	return fUserInfo;

   605 }

   606 

   607 inline const XMLCh* XMLUri::getHost() const

   608 {

   609 	return fHost;

   610 }

   611 

   612 inline int XMLUri::getPort() const

   613 {

   614 	return fPort;

   615 }

   616 

   617 inline const XMLCh* XMLUri::getRegBasedAuthority() const

   618 {

   619 	return fRegAuth;

   620 }

   621 

   622 inline const XMLCh* XMLUri::getPath() const

   623 {

   624 	return fPath;

   625 }

   626 

   627 inline const XMLCh* XMLUri::getQueryString() const

   628 {

   629 	return fQueryString;

   630 }

   631 

   632 inline const XMLCh* XMLUri::getFragment() const

   633 {

   634 	return fFragment;

   635 }

   636 

   637 inline const XMLCh* XMLUri::getUriText() const

   638 {

   639     //

   640     //  Fault it in if not already. Since this is a const method and we

   641     //  can't use mutable members due the compilers we have to support,

   642     //  we have to cast off the constness.

   643     //

   644     if (!fURIText)

   645         ((XMLUri*)this)->buildFullText();

   646 

   647     return fURIText;

   648 }

   649 

   650 // ---------------------------------------------------------------------------

   651 //  XMLUri: Helper methods

   652 // ---------------------------------------------------------------------------

   653 inline bool XMLUri::isReservedOrUnreservedCharacter(const XMLCh theChar)

   654 {

   655    return (XMLString::isAlphaNum(theChar) ||

   656            XMLString::indexOf(MARK_OR_RESERVED_CHARACTERS, theChar) != -1);

   657 }

   658 

   659 inline bool XMLUri::isReservedCharacter(const XMLCh theChar)

   660 {

   661     return (XMLString::indexOf(RESERVED_CHARACTERS, theChar) != -1);

   662 }

   663 

   664 inline bool XMLUri::isPathCharacter(const XMLCh theChar)

   665 {

   666     return (XMLString::indexOf(PATH_CHARACTERS, theChar) != -1);

   667 }

   668 

   669 inline bool XMLUri::isUnreservedCharacter(const XMLCh theChar)

   670 {

   671     return (XMLString::isAlphaNum(theChar) ||

   672             XMLString::indexOf(MARK_CHARACTERS, theChar) != -1);

   673 }

   674 

   675 XERCES_CPP_NAMESPACE_END

   676 

   677 #endif