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

[Hannes Wallnöfer]

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

This feature needs more work, closing the PR and deferring the JBS issue to 19.

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

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