/*******************************************************************************
* Copyright (c) 2000, 2015 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* 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.
* <p>
* 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 <code>null</code> 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
* <code>IHelpResource</code> allows search result UI to create a link to
* the category.
*
* @return a hit category or <code>null</code> 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
* <p>
* Valid URL of a help resource is:
* <ul>
* <li>a <em>/pluginID/path/to/resource</em>, where
* <ul>
* <li><em>pluginID</em> is the unique identifier of the plugin
* containing the help resource,
* <li><em>path/to/document</em> is the help resource path,
* relative to the plugin directory.
* </ul>
* For example. <em>/myplugin/mytoc.xml</em> or
* <em>/myplugin/references/myclass.html</em> are vaild.
* <li>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.
* <em>http://eclipse.org/documents/my%20file.html</em> and
* <em>jar:file:/c:/my%20sources/src.zip!/mypackage/MyClass.html</em>
* are examples of valid URIs.
* </ul>
* </p>
*/
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.
* <p>
* Note that returning <code>false</code> 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 <code>true</code> if external window must be used,
* <code>false</code> 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 <code>true</code>, 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);
}