[API CHANGE] Adapt css.uri UNOIDL entities to RFC 3986

...which obsoleted RFC 2396.  Notable changes are that the distinction between
hierarchical and opaque URIs has been dropped, and that the relative URI
resolution specification has been made more rigid.

As a consequence, various features of css.uri entities have changed:

* XUriReference.isHierarchical is obsolete and deprecated.

* The behavior of XUriReference.hasAuthority, XUriReference.getAuthority,
  XUriReference.getPath, XUriReference.hasRelativePath,
  XUriReference.getPathSegmentCount, XUriReference.getPathSegment,
  XUriReference.hasQuery, and XUriReference.getQuery has been made consistent
  for all URIs, no matter whether they were considered hierarchical or opaque in
  the past.

* The behavior of XUriReferenceFactory.makeAbsolute and
  XUriReferenceFactory.makeRelative has been changed to match the RFC 3986
  reference resolution specification.  The XUriReferenceFactory.makeAbsolulte
  parameter processSpecialBaseSegments has been renamed to
  processAdditionalSpecialSegments, as per the updated specification it now
  controls treatment of special segments in the given uriReference, in addition
  to special segments in the given baseUriReference.  (Renaming UNOIDL interface
  method parameters is technically an incompatible change, but the benefits of
  improved clarity presumably outweigh any potential drawbacks in this case.)

The implementation in stoc has been adapted, and various call sites have been
adapted to the deprecated XUriReference.isHierarchical semantics.

Change-Id: Ic6e00fdbce5abef70d75ec2f753d22fefe361457
Reviewed-on: https://gerrit.libreoffice.org/77861
Tested-by: Jenkins
Reviewed-by: Stephan Bergmann <sbergman@redhat.com>

7 files changed, 45 insertions, 42 deletions

diff --git a/udkapi/com/sun/star/uri/UriReferenceFactory.idl b/udkapi/com/sun/star/uri/UriReferenceFactory.idl
index cddc9cf383a2..c19e8167d1d1 100644
--- a/udkapi/com/sun/star/uri/UriReferenceFactory.idl
+++ b/udkapi/com/sun/star/uri/UriReferenceFactory.idl
@@ -27,7 +27,7 @@ published interface XUriReferenceFactory;
 /**
    creates URI references.
 
-   <p>See <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a> for a
+   <p>See <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC&nbsp;3986</a> for a
    description of URI references and related terms.</p>
 
    <p>For parsing absolute URI references, this service tries to use a
diff --git a/udkapi/com/sun/star/uri/XUriReference.idl b/udkapi/com/sun/star/uri/XUriReference.idl
index 147eaba79f2e..ba42f283f8c6 100644
--- a/udkapi/com/sun/star/uri/XUriReference.idl
+++ b/udkapi/com/sun/star/uri/XUriReference.idl
@@ -27,7 +27,7 @@ module com { module sun { module star { module uri {
 /**
    represents generic, mutable URI references.
 
-   <p>See <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a> for a
+   <p>See <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC&nbsp;3986</a> for a
    description of URI references and related terms.</p>
 
    <p>This interface only handles generic URI references (both absolute and
@@ -54,6 +54,8 @@ published interface XUriReference: com::sun::star::uno::XInterface {
     /**
        returns whether this URI reference is absolute or relative.
 
+       <p>A URI is absolute if it has a scheme.</p>
+
        @returns
        `TRUE` if this URI reference is absolute, `FALSE` if it is relative.
      */
@@ -86,7 +88,7 @@ published interface XUriReference: com::sun::star::uno::XInterface {
     string getSchemeSpecificPart();
 
     /**
-       returns whether this URI reference is hierarchical or opaque.
+       returns whether this URI reference is hierarchical or opaque, in the sense of RFC&nbsp2396.
 
        <p>An absolute URI reference is hierarchical if its scheme-specific part
        starts with &ldquo;<code>/</code>&rdquo;.  A relative URI reference is
@@ -94,23 +96,25 @@ published interface XUriReference: com::sun::star::uno::XInterface {
 
        @returns
        `TRUE` if this URI reference is hierarchical, `FALSE` if it is opaque.
+
+       @deprecated RFC&nbsp;3986 no longer differentiates between hierarchical and opaque URIs.
      */
     boolean isHierarchical();
 
     /**
-       returns whether this (hierarchical) URI reference has an authority part.
+       returns whether this URI reference has an authority part.
 
        @returns
-       `TRUE` if this URI reference is hierarchical and has an authority part.
+       `TRUE` if this URI reference has an authority part.
      */
     boolean hasAuthority();
 
     /**
-       returns the authority part of this (hierarchical) URI reference.
+       returns the authority part of this URI reference.
 
        @returns
        the textual representation of the authority part (with the exact spelling
-       retained), if this is a hierarchical URI reference that has an authority
+       retained), if this is a URI reference that has an authority
        part; otherwise, an empty `string` is returned.
      */
     string getAuthority();
@@ -120,28 +124,26 @@ published interface XUriReference: com::sun::star::uno::XInterface {
 
        @returns
        the textual representation of the path part (with the exact spelling
-       retained), if this is a hierarchical URI reference; for an opaque URI
-       reference, the scheme-specific part (with the exact spelling retained) is
-       returned.
+       retained).
      */
     string getPath();
 
     /**
-       returns whether this (relative) URI reference has a relative path.
+       returns whether this URI reference has a relative path.
 
        @returns
-       `TRUE` if this URI reference is relative and has a relative path.
+       `TRUE` if this URI reference has a relative path.
      */
     boolean hasRelativePath();
 
     /**
-       returns the number of path segments of this (hierarchical) URI reference.
+       returns the number of path segments of this URI reference.
 
-       <p>For an opaque URI reference, and for a hierarchical URI reference with
-       an empty path, the number of path segments is zero.  For a hierarchical
+       <p>For a URI reference with
+       an empty path, the number of path segments is zero.  For a
        URI reference with an absolute, non-empty path, the number of path
        segments equals the number of &ldquo;<code>/</code>&rdquo; delimiters.
-       For a hierarchical URI reference with a relative, non-empty path, the
+       For a URI reference with a relative, non-empty path, the
        number of path segments equals the number of &ldquo;<code>/</code>&rdquo;
        delimiters, plus one.</p>
 
@@ -151,7 +153,7 @@ published interface XUriReference: com::sun::star::uno::XInterface {
     long getPathSegmentCount();
 
     /**
-       returns a given path segment of this (hierarchical) URI reference.
+       returns a given path segment of this URI reference.
 
        @param index
        the index of the path segment, starting at zero.
@@ -159,27 +161,27 @@ published interface XUriReference: com::sun::star::uno::XInterface {
        @returns
        the textual representation of the given path segment (with the exact
        spelling retained, without any delimiting &ldquo;<code>/</code>&rdquo;),
-       if this URI reference is hierarchical and has that many path segments;
+       if this URI reference has that many path segments;
        otherwise, and in particular if <code>index</code> is negative, an empty
        `string` is returned.
      */
     string getPathSegment([in] long index);
 
     /**
-       returns whether this (hierarchical) URI reference has a query part.
+       returns whether this URI reference has a query part.
 
        @returns
-       `TRUE` if this URI reference is hierarchical and has a query part.
+       `TRUE` if this URI reference has a query part.
      */
     boolean hasQuery();
 
     /**
-       returns the query part of this (hierarchical) URI reference.
+       returns the query part of this URI reference.
 
        @returns
        the textual representation of the query part (with the exact spelling
        retained; without the delimiting &ldquo;<code>?</code>&rdquo;), if this
-       is a hierarchical URI reference that has a query part; otherwise, an
+       is a URI reference that has a query part; otherwise, an
        empty `string` is returned.
      */
     string getQuery();
diff --git a/udkapi/com/sun/star/uri/XUriReferenceFactory.idl b/udkapi/com/sun/star/uri/XUriReferenceFactory.idl
index 133f1f3cf23d..e87542aa4f58 100644
--- a/udkapi/com/sun/star/uri/XUriReferenceFactory.idl
+++ b/udkapi/com/sun/star/uri/XUriReferenceFactory.idl
@@ -29,7 +29,7 @@ module com { module sun { module star { module uri {
 /**
    creates URI references.
 
-   <p>See <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a> for a
+   <p>See <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC&nbsp;3986</a> for a
    description of URI references and related terms.</p>
 
    @since OOo 2.0
@@ -59,35 +59,38 @@ published interface XUriReferenceFactory: com::sun::star::uno::XInterface {
 
        @param uriReference
        any URI reference.  Backwards-compatible relative URI references starting
-       with a scheme component (see RFC&nbsp;2396, Section&nbsp;5.2,
-       step&nbsp;3) are not supported; instead, they are interpreted as absolute
+       with a scheme component (see RFC&nbsp;3986, Sections 5.2.2 and&nbsp;5.4,2)
+       are not supported; instead, they are interpreted as absolute
        URI references.
 
-       @param processSpecialBaseSegments
+       @param processAdditionalSpecialSegments
        if `TRUE`, special segments (&ldquo;<code>.</code>&rdquo; and
        &ldquo;<code>..</code>&rdquo;) within the path of the base URI (except
-       for the last, cut-off segment) are processed as suggested by
-       RFC&nbsp;2396.  If `FALSE`, special segments within the path of the base
-       URI are treated like ordinary segments.
+       for the last, cut-off segment), and within an already absolute <code>uriReference</code>, are
+       processed as required by
+       RFC&nbsp;3986.  If `FALSE`, such special segments
+       are treated like ordinary segments.
+       Conformance with RFC&nbsp;3986 requires `TRUE` to be passed.
 
        @param excessParentSegments
        details how excess special parent segments
        (&ldquo;<code>..</code>&rdquo;) are handled.
+       Conformance with RFC&nbsp;3986 requires REMOVE to be passed.
 
        @returns
        a fresh object that supports
        com::sun::star::uri::XUriReference (and possibly also
        additional, scheme-specific interfaces), if the given
-       <code>uriReference</code> is either already absolute, or can be resolved
+       <code>uriReference</code> can be resolved
        to an absolute URI reference, relative to the given
        <code>baseUriReference</code>; otherwise, `NULL` is returned.
        Especially, if <code>baseUriReference</code> is `NULL`, or is not an
-       absolute, hierarchical URI reference, or if <code>uriReference</code> is
+       absolute URI reference, or if <code>uriReference</code> is
        `NULL`, then `NULL` is always returned.
      */
     XUriReference makeAbsolute(
         [in] XUriReference baseUriReference, [in] XUriReference uriReference,
-        [in] boolean processSpecialBaseSegments,
+        [in] boolean processAdditionalSpecialSegments,
         [in] RelativeUriExcessParentSegments excessParentSegments);
 
     /**
@@ -134,13 +137,13 @@ published interface XUriReferenceFactory: com::sun::star::uno::XInterface {
        @returns
        a fresh object that supports
        com::sun::star::uri::XUriReference, if the given
-       <code>uriReference</code> is either already relative, or is not
-       hierarchical, or is of a different scheme than the given
+       <code>uriReference</code> is either already relative, or has a relative
+       path, or is of a different scheme than the given
        <code>baseUriReference</code>, or can be changed to a relative URI
        reference, relative to the given <code>baseUriReference</code>;
        otherwise, `NULL` is returned.  Especially, if
-       <code>baseUriReference</code> is `NULL`, or is not an absolute,
-       hierarchical URI reference, or if <code>uriReference</code> is `NULL`,
+       <code>baseUriReference</code> is `NULL`, or is not an absolute
+       URI reference, or if <code>uriReference</code> is `NULL`,
        then `NULL` is always returned.
      */
     XUriReference makeRelative(
diff --git a/udkapi/com/sun/star/uri/XUriSchemeParser.idl b/udkapi/com/sun/star/uri/XUriSchemeParser.idl
index e07aec8e4c7a..573a3cfb918c 100644
--- a/udkapi/com/sun/star/uri/XUriSchemeParser.idl
+++ b/udkapi/com/sun/star/uri/XUriSchemeParser.idl
@@ -28,7 +28,7 @@ module com { module sun { module star { module uri {
 /**
    parses textual representations of absolute URIs.
 
-   <p>See <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a> for a
+   <p>See <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC&nbsp;3986</a> for a
    description of URIs and related terms.</p>
 
    @since OOo 2.0
diff --git a/udkapi/com/sun/star/uri/XVndSunStarExpandUrl.idl b/udkapi/com/sun/star/uri/XVndSunStarExpandUrl.idl
index 0bcfe32a5458..8de9d5380096 100644
--- a/udkapi/com/sun/star/uri/XVndSunStarExpandUrl.idl
+++ b/udkapi/com/sun/star/uri/XVndSunStarExpandUrl.idl
@@ -38,8 +38,7 @@ module com { module sun { module star { module uri {
    where the <var>opaque_part</var> is a UTF-8 string as described in
    <a href="http://udk.openoffice.org/common/man/concept/micro_deployment.html">
    Bootstrap Arguments and Micro Deployment</a>.  See
-   <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
-   <a href="http://www.ietf.org/rfc/rfc2732.txt">RFC&nbsp;2732</a>, and
+   <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC&nbsp;3986</a>
    <a href="http://www.ietf.org/rfc/rfc2234.txt">RFC&nbsp;2234</a> for
    details.</p>
 
diff --git a/udkapi/com/sun/star/uri/XVndSunStarScriptUrl.idl b/udkapi/com/sun/star/uri/XVndSunStarScriptUrl.idl
index bd5295930fa7..ca703bcf4bdb 100644
--- a/udkapi/com/sun/star/uri/XVndSunStarScriptUrl.idl
+++ b/udkapi/com/sun/star/uri/XVndSunStarScriptUrl.idl
@@ -41,8 +41,7 @@ module com { module sun { module star { module uri {
    <code>"$"</code> / <code>"+"</code> / <code>","</code> / <code>":"</code> /
    <code>";"</code> / <code>"@"</code> / <code>"["</code> /
    <code>"]"</code><br/>
-   See <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
-   <a href="http://www.ietf.org/rfc/rfc2732.txt">RFC&nbsp;2732</a>, and
+   See <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC&nbsp;3986</a>
    <a href="http://www.ietf.org/rfc/rfc2234.txt">RFC&nbsp;2234</a> for
    details.</p>
 
diff --git a/udkapi/type_reference/udkapi.idl b/udkapi/type_reference/udkapi.idl
index 5000acfc73e1..071173d15cd5 100644
--- a/udkapi/type_reference/udkapi.idl
+++ b/udkapi/type_reference/udkapi.idl
@@ -1844,7 +1844,7 @@ module com {
     published interface XUriReferenceFactory {
      interface ::com::sun::star::uno::XInterface;
      ::com::sun::star::uri::XUriReference parse([in] string uriReference);
-     ::com::sun::star::uri::XUriReference makeAbsolute([in] ::com::sun::star::uri::XUriReference baseUriReference, [in] ::com::sun::star::uri::XUriReference uriReference, [in] boolean processSpecialBaseSegments, [in] ::com::sun::star::uri::RelativeUriExcessParentSegments excessParentSegments);
+     ::com::sun::star::uri::XUriReference makeAbsolute([in] ::com::sun::star::uri::XUriReference baseUriReference, [in] ::com::sun::star::uri::XUriReference uriReference, [in] boolean processAdditionalSpecialSegments, [in] ::com::sun::star::uri::RelativeUriExcessParentSegments excessParentSegments);
      ::com::sun::star::uri::XUriReference makeRelative([in] ::com::sun::star::uri::XUriReference baseUriReference, [in] ::com::sun::star::uri::XUriReference uriReference, [in] boolean preferAuthorityOverRelativePath, [in] boolean preferAbsoluteOverRelativePath, [in] boolean encodeRetainedSpecialSegments);
     };
     published service UriReferenceFactory: ::com::sun::star::uri::XUriReferenceFactory;