Issue #11505 - Document HttpURI methods

[afarber]

Add method-level Javadoc to HttpURI class which was missing documentation for most public methods:

• Document all interface getter methods (getAuthority, getDecodedPath, getCanonicalPath, getFragment, getHost, getPath, getPathQuery, getPort, getQuery, getScheme, getUser, etc.)
• Expand getParam() docs to explain path parameters vs query parameters with RFC2396 reference
• Improve violation-related method docs (isAmbiguous, hasViolations, hasViolation, getViolations)
• Document all Mutable builder methods (clear, decodedPath, fragment, host, normalize, param, path, pathQuery, port, query, scheme, uri, user)
• Add "@see" cross-references between related methods

[joakime]

This first shows up in https://www.rfc-editor.org/rfc/rfc2068#section-3.2.1
I've never seen it called matrix parameters before.

[joakime]

BTW, where did you get "matrix parameters" from?

[afarber]

https://stackoverflow.com/q/2048121/165071

[joakime]

Thanks.

Looks like Tim Berners-Lee even had comments about this awkward, and historical, piece of the URL/URI specs.

https://www.w3.org/DesignIssues/MatrixURIs.html

[joakime]

Looks like Jakarta EE Rest (what used to be called JAXRS) even has a @MatrixParam concept that uses this ...

https://github.com/jakartaee/rest/blob/4.0.0-RELEASE/jaxrs-spec/src/main/asciidoc/chapters/appendix/_annotation_table.adoc

It's implementation is a bit limited though, it only cares about the last path segment.
If a param exists in path segments that are not the last it considers that entire URL/URI as ambiguous and doesn't throws an exception.

[afarber]

@joakime should we add the "matrix parameters" back to the Javadoc then, to pay a tribute? Suggest a text

[joakime]

Interestingly the path parameters are still referenced in the current active URI spec too.

See: https://www.rfc-editor.org/rfc/rfc3986#section-3.3

   Aside from dot-segments in hierarchical paths, a path segment is
   considered opaque by the generic syntax.  URI producing applications
   often use the reserved characters allowed in a segment to delimit
   scheme-specific or dereference-handler-specific subcomponents.  For
   example, the semicolon (";") and equals ("=") reserved characters are
   often used to delimit parameters and parameter values applicable to
   that segment.  The comma (",") reserved character is often used for ...