ISearchEngineResult


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    * 
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.help.search;
12  
13  import org.eclipse.help.IHelpResource;
14  
15  /**
16   * A search result created by the help search engine. Engines that have direct
17   * access to the search servers are expected to provide one search result object
18   * per each hit. Engines that can only compose a search query that returns a
19   * document with the results must create one search result object whose URL is
20   * the actual query. This URL will then be presented in the Web browser.
21   * <p>
22   * This interface is inteded to be implemented by clients.
23   * 
24   * @since 3.1
25   */
26  public interface ISearchEngineResult {
27      /**
28       * Returns the label of the search result to use in the UI.
29       * 
30       * @return the search result label
31       */
32      String   getLabel();
33  
34      /**
35       * Returns the short description of the search result. If coming from an
36       * individual search hit, this description is typically composed of the
37       * document fragment in the vicinity of the searched expression, or a
38       * combination of several document fragments. Other search engines may
39       * return a couple of sentencies at the beninning of the document.
40       * 
41       * @return a short description, or <code>null</code> if not available.
42       */
43      String   getDescription();
44  
45      /**
46       * Returns a category this search result belongs to. Engines can use this
47       * object to denote the origin of the hit in the search domain. The usage of
48       * <code>IHelpResource</code> allows search result UI to create a link to
49       * the category.
50       * 
51       * @return a hit category or <code>null</code> if not available.
52       */
53      IHelpResource getCategory();
54  
55      /**
56       * Returns the URL (as a string) associated with this help resource.
57       * 
58       * @return the URL (as a string) associated with the resource
59       *         <p>
60       *         Valid URL of a help resource is:
61       *         <ul>
62       *         <li>a <em>/pluginID/path/to/resource</em>, where
63       *         <ul>
64       *         <li><em>pluginID</em> is the unique identifier of the plugin
65       *         containing the help resource,
66       *         <li><em>path/to/document</em> is the help resource path,
67       *         relative to the plugin directory.
68       *         </ul>
69       *         For example. <em>/myplugin/mytoc.xml</em> or
70       *         <em>/myplugin/references/myclass.html</em> are vaild.
71       *         <li>string representation of URI to an external document. In
72       *         this case, all special characters have to be enoded such that the
73       *         URI is appropriate to be opened with a web browser.
74       *         <em>http://eclipse.org/documents/my%20file.html</em> and
75       *         <em>jar:file:/c:/my%20sources/src.zip!/mypackage/MyClass.html</em>
76       *         are examples of valid URIs.
77       *         </ul>
78       *         </p>
79       */
80      String   getHref();
81  
82      /**
83       * Returns a float number in the range between 0 and 1 that can be used to
84       * sort the hits by relevance (1 being the perfect result). The number can
85       * be interpreted as the probability of a match in the given topic.
86       * 
87       * @return the score of this hit between 0.0 and 1.0
88       */
89      float getScore();
90  
91      /**
92       * Tests if the result link must be shown in an external web browser/Help
93       * window, or it can also be shown embedded. Contributors should force
94       * external window only if the link points at a web page that cannot be
95       * displayed in a narrow view without distorsion. Text-only document
96       * typically reflows well to fit the narrow view. Documents with tables
97       * and/or images normally do not fit without showing the horizontal scroll
98       * bar.
99       * <p>
100      * Note that returning <code>false</code> does not prevent the link to be
101      * opened in the external window. Instead, it indicates that the link should
102      * be opened using the current user preferences, which may always force
103      * external window for URL rendering.
104      * 
105      * @return <code>true</code> if external window must be used,
106      *         <code>false</code> if the link opening mode can be chosen by
107      *         the help system.
108      */
109     boolean getForceExternalWindow();
110 
111     /**
112      * Converts a relative href into absolute according to the search engine
113      * base URL.
114      * 
115      * @param href
116      *            the relative href to convert into absolute
117      * @param frames
118      *            if <code>true</code>, the resulting href can contain frames
119      *            in a format suitable for presentation in a standalone web
120      *            browser. Otherwise, the resulting href should be without
121      *            frames and suitable for presentation in the embedded web
122      *            browser inside the workbench.
123      * @return the absolute href that can be used to navigate to the reference
124      *         as-is
125      */
126     String   toAbsoluteHref(String   href, boolean frames);
127 }
128
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags