/*******************************************************************************
 * 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);
}