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

These are all valid doubts/questions. I'll try to address them below.

> I'm unconvinced by this feature as implemented.
> 
> As I understand it, the original underlying request was to support external clients (browsers) constructing URLs containing a search query, with the ability to visit the resulting page if the query yielded a unique result, and to display "something" when the result was not unique. For the "not unique" case, I agree that showing search results is a clever solution, as compared to generating a new page containing clickable search results.

Using the existing search infrastructure to display results is the most economical and generic solution. 

Redirecting to the first result would be easy to implement, and I can easily add that feature. But I wasn't sure what the benefit would be compared to directly linking to a resource, as URLs for documented elements usually don't change that often, and if they do the search query might likely fail as well. 

Having a dedicated search landing page could be nice, but requires a lot more work. And of course it wouldn't allow to trigger a search within the current page via link as discussed below.

> I'm unconvinced by the need to embed links within documentation that trigger search results, as exemplified by the Help page examples. I'm not sure what problem that is addressing.

It allows authors to create links that pop up search results containing elements that match some query string. This could be a group of  overloaded methods or constructors, elements with some common name component, or a group of classes within some subpackage.

> I'm unconvinced by the use of fragment syntax instead of the query string. It seems to be pushing the definition too far: _additional information identifying some secondary resource within the primary resource identified by the URI_. I guess I would like to see stronger motivation for _not_ using the query string, especially in the use case of URLs constructed by external clients such as browsers. While not an expert on JavaScript in this area, I see stackoverflow has some simple example JavaScript for accessing the query string.

The practical difference between the query and the fragment parts is that the query is sent to the web server as part of the URI. Changing a query string therefore always results in the current page being reloaded. URI fragments on the contrary are not sent to the server and are only visible to the browser and the JavaScript within the page. URI fragments are therefore the preferred mechanism for information targeted to JavaScript within the browser to trigger some action or state without reloading the page.

> I'm unconvinced by the need to support this mechanism on every generated page, as compared to the top-level page, such that one can search for elements within the overall documentation.

We support search on every page, so in my mind it makes sense to support this search trigger mechanism in every page as well. Of course the usefulness lies more in the context of local search links as described above. I agree it doesn't make much sense for linking to a page remotely.

> Maybe I'm missing the point of this change as implemented. If so, can you provide more justification for the feature as-is.

I hope I did provide some justification the feature I proposed. Summing up, a dedicated search landing page would make more sense in the context of remote links. The proposed solution makes more sense in the context of embedded search links, and therefore depends on the usefulness of that feature.

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

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