org.eclipse.help.search.ISearchEngineResult Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2000, 2015 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.help.search;
import org.eclipse.help.IHelpResource;
/**
* 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
*/
public interface ISearchEngineResult {
/**
* Returns the label of the search result to use in the UI.
*
* @return the search result label
*/
String getLabel();
/**
* 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.
*
* @return a short description, or null if not available.
*/
String getDescription();
/**
* 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.
*
* @return a hit category or null if not available.
*/
IHelpResource getCategory();
/**
* Returns the URL (as a string) associated with this help resource.
*
* @return 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.
*
*/
String getHref();
/**
* 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.
*
* @return the score of this hit between 0.0 and 1.0
*/
float getScore();
/**
* 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.
*
* @return true if external window must be used,
* false if the link opening mode can be chosen by
* the help system.
*/
boolean getForceExternalWindow();
/**
* Converts a relative href into absolute according to the search engine
* base URL.
*
* @param href
* the relative href to convert into absolute
* @param 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.
* @return the absolute href that can be used to navigate to the reference
* as-is
*/
String toAbsoluteHref(String href, boolean frames);
}