org.eclipse.help.search

Interface ISearchEngineResult

All Known Subinterfaces:

ISearchEngineResult2

public interface ISearchEngineResult

A search result created by the help search engine. Engines that have direct access to the search servers are expected to provide one search result object per each hit. Engines that can only compose a search query that returns a document with the results must create one search result object whose URL is the actual query. This URL will then be presented in the Web browser.

This interface is inteded to be implemented by clients.

Since:

3.1

Method Summary

Modifier and Type	Method and Description
IHelpResource	getCategory() Returns a category this search result belongs to.
String	getDescription() Returns the short description of the search result.
boolean	getForceExternalWindow() Tests if the result link must be shown in an external web browser/Help window, or it can also be shown embedded.
String	getHref() Returns the URL (as a string) associated with this help resource.
String	getLabel() Returns the label of the search result to use in the UI.
float	getScore() Returns a float number in the range between 0 and 1 that can be used to sort the hits by relevance (1 being the perfect result).
String	toAbsoluteHref(String href, boolean frames) Converts a relative href into absolute according to the search engine base URL.

Method Detail

getLabel

String getLabel()

Returns the label of the search result to use in the UI.

Returns:

the search result label

getDescription

String getDescription()

Returns the short description of the search result. If coming from an individual search hit, this description is typically composed of the document fragment in the vicinity of the searched expression, or a combination of several document fragments. Other search engines may return a couple of sentencies at the beninning of the document.

Returns:

a short description, or null if not available.

getCategory

IHelpResource getCategory()

Returns a category this search result belongs to. Engines can use this object to denote the origin of the hit in the search domain. The usage of IHelpResource allows search result UI to create a link to the category.

Returns:

a hit category or null if not available.

getHref

String getHref()

Returns the URL (as a string) associated with this help resource.

Returns:

the URL (as a string) associated with the resource

Valid URL of a help resource is:

• a /pluginID/path/to/resource, where
  • pluginID is the unique identifier of the plugin containing the help resource,
  • path/to/document is the help resource path, relative to the plugin directory.
  For example. /myplugin/mytoc.xml or /myplugin/references/myclass.html are vaild.
• string representation of URI to an external document. In this case, all special characters have to be enoded such that the URI is appropriate to be opened with a web browser. http://eclipse.org/documents/my%20file.html and jar:file:/c:/my%20sources/src.zip!/mypackage/MyClass.html are examples of valid URIs.

getScore

float getScore()

Returns a float number in the range between 0 and 1 that can be used to sort the hits by relevance (1 being the perfect result). The number can be interpreted as the probability of a match in the given topic.

Returns:

the score of this hit between 0.0 and 1.0

getForceExternalWindow

boolean getForceExternalWindow()

Tests if the result link must be shown in an external web browser/Help window, or it can also be shown embedded. Contributors should force external window only if the link points at a web page that cannot be displayed in a narrow view without distorsion. Text-only document typically reflows well to fit the narrow view. Documents with tables and/or images normally do not fit without showing the horizontal scroll bar.

Note that returning false does not prevent the link to be opened in the external window. Instead, it indicates that the link should be opened using the current user preferences, which may always force external window for URL rendering.

Returns:

true if external window must be used, false if the link opening mode can be chosen by the help system.

toAbsoluteHref

String toAbsoluteHref(String href,
                      boolean frames)

Converts a relative href into absolute according to the search engine base URL.

Parameters:

href - the relative href to convert into absolute

frames - if true, the resulting href can contain frames in a format suitable for presentation in a standalone web browser. Otherwise, the resulting href should be without frames and suitable for presentation in the embedded web browser inside the workbench.

Returns:

the absolute href that can be used to navigate to the reference as-is