RFR: JDK-8248863: Add feature to trigger search via URI fragment

[Jonathan Gibbons]

On Tue, 23 Nov 2021 15:11:33 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> Please review a new feature to trigger a javadoc search on any javadoc page through a specially encoded URI fragment. 
> 
> This allows the search feature to be triggered "locally" in the currently viewed page by clicking on a link to the search fragment, or "remotely" by linking to a page whose URI includes a search fragment. The search fragment uses the following syntax to make it differ from normal page anchors:
> 
>     #!search=search_term
> 
> Although fragments are most commonly used to target elements by their `id` attribute in HTML documents they are by no means limited to this. The [URI specification] defines the fragment in very generic terms as additional information identifying some secondary resource within the primary resource identified by the URI. There are also many examples of [proposed and existing uses] of fragment identifiers for similar tasks.
> 
> [URI specification]: https://datatracker.ietf.org/doc/html/rfc3986#section-3.5
> [proposed and existing uses]: https://en.wikipedia.org/wiki/URI_fragment#Proposals
> 
> I considered other mechanisms such as query strings or javascript links, but they all have significant drawbacks compared to URI fragments. Query strings are usually associated with server side processing and cannot be opened without reloading the page. Javascript links on the other hand cannot be triggered remotely as part of the primary URI, and there are security issues associated with them. I think URI fragments are the right tool for the task.
> 
> The new feature is deployed in the [Help page] with the search examples, which should help to popularize the feature. Additionally it  should be documented in the javadoc search spec, for which I'll file a separate JBS issue. 
> 
> [Help page]: http://cr.openjdk.java.net/~hannesw/8248863/api.00/help-doc.html
> 
> Below are the URIs for the search examples in the Help page as well as a few other examples:
> 
> http://cr.openjdk.java.net/~hannesw/8248863/api.00/help-doc.html#!search=j.l.obj
> http://cr.openjdk.java.net/~hannesw/8248863/api.00/help-doc.html#!search=InpStr
> http://cr.openjdk.java.net/~hannesw/8248863/api.00/help-doc.html#!search=HM.cK
> http://cr.openjdk.java.net/~hannesw/8248863/api.00/index.html#!search=stringbuilder.append
> http://cr.openjdk.java.net/~hannesw/8248863/api.00/index.html#!search=java%20collection%20framework

I guess I would recommend the following:

1. Use query syntax, not fragment syntax
2. Support this feature only on the top level page, so that the proposed search URL is of the form `https://host:port/path/to/api?search=query-string` ... related: this is a publicly visible spec and needs a CSR (this is true whatever form of URL is used.)
3. If the search returns a single unique result, select that page and show the matching element. If the search does not yield a single result, I'm OK to show the top level page with the search-result-menu open. I'm OK with not creating a dedicated search landing page, at least for remotely generated queries, but the more you push on local search (e.g. to link to a set of methods) the more useful a dedicated multiple-results page might become.  Right now, the use of the popup menu for a search URL seems more like a workaround for an inadequate query, than a feature to display multiple search results.

I still don't find the argument for local search links very compelling. I find the argument to support local search links on the same page even less compelling.

I don't like the dual use of fragments for both "traditional" navigate-to-id and the proposed "search".  Your justification in terms of JavaScript is an admission to the internal implementation. Documenting the URL format in spec docs and a CSR is going to be ... well, ... icky.

I note that with 1-2-3 above, you could still "demo" the search-url feature on the `help-doc.html` page, for both unique results and multiple results.

-------------

PR: https://git.openjdk.java.net/jdk/pull/6524