Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com
Answertopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

Eclipse Plug-in Developer Guide
Previous Page Home Next Page

Search Engine

Identifier:
org.eclipse.help.ui.searchEngine

Since:
3.1

Description:
This extension point is used to plug in search participants in the federated help search. Each search engine can be configured individually. When search is initiated, each search engine is executed as a background job, and the results are collated in the help view immediately under the query.

Search engines defined here will not automatically show up as federated search participants until engine product binding is established, unless productId attribute is left undefined. For engines that define it, only thouse bound to a particular product will show up when that product is running.

Search engines can simply compose a URL and provide only one hit containing that URL as href. Popular search engines for which API support requires license can be plugged in like this. On the other end of the spectrum, search engines can communicate with the server and receive individual hits with information like label, href, short description, score etc. Local help engine can produce hits this way.

Regardless of the search mechanism, engines can provide various search scope settings using JFace preference pages. These pages are shown when 'Advanced Settings' link is followed from the Help view. In addition to root preference pages defined with the engine, additional preference sub-pages can be plugged in for more advanced settings.

Scope settings are loaded and stored using IPreferenceStore objects. Scope settings for all engines are grouped together under a named scope set. When first opened, default scope set ('Default') is created, but users can define more scope sets and flip between them.

Since federated search support is part of org.eclipse.help.base plug-in, a factory is needed to create search scope objects from the data in the preference store. Clients that plug in scope preference pages are required to plug in scope factories as well.

Engines defined in this extension point do not show up in the UI by default. What is shown there is a concrete instance of a search engine that can be individually modified. Products can preconfigure the help system with a number of instances of the registered engine types, possibly parametrized to perform in a desired way. In addition, users can add their own instances of the registered engines and configure them to their liking.

Configuration Markup:

<!ELEMENT extension ( engine | engineType)+>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED

>


<!ELEMENT engineType ( description? , subpage*)>

<!ATTLIST engineType

id           CDATA #REQUIRED

label        CDATA #REQUIRED

icon         CDATA #IMPLIED

class        CDATA #REQUIRED

pageClass    CDATA #IMPLIED

scopeFactory CDATA #IMPLIED

>

defines a particular type of a search engine. Search engine type can be used to create concrete engine instances either by the user or pre-loaded by the product. In order to be useful, engine types must be configurable so that a number of engines can be created using a single engine type.


  • id - a unique name of the search engine type
  • label - a translatable name of the search engine type
  • icon - a 16x16 image that will be used to visually represent this engine type
  • class - a fully qualified name of the class that implements org.eclipse.help.search.ISearchEngine. The class is responsible for searching based on a given query and scope.
  • pageClass - a fully qualified name of the class that extends org.eclipse.help.ui.RootScopePage class. This page holds the master switch for the search engine and is typically used to host widgets used to narrow down the search scope for the engine.
  • scopeFactory - a fully qualified name of the class that implements org.eclipse.help.ui.ISearchScopeFactory. The factory is responsible for creating ISearchScope objects from settings stored in IPreferenceStore class. If pageClass is specified, scope factory must be specified as well.

<!ELEMENT description (#PCDATA)>

a short description of the search engine



<!ELEMENT subpage EMPTY>

<!ATTLIST subpage

id       CDATA #REQUIRED

label    CDATA #REQUIRED

class    CDATA #IMPLIED

category CDATA #REQUIRED

>

a child page to the root scope preference page defined in the engine element. If pageClass engine attribute is not defined, sub-pages will be ignored.


  • id - a unique identifier of this page
  • label - a translatable name of this page
  • class - a fully qualified name of a class that implements org.eclipse.help.ui.ISearchScopePage interface.
  • category - id of the parent subpage or engine id if the parent is the root page.

<!ELEMENT engine ( description? , param*)>

<!ATTLIST engine

productId    IDREF #IMPLIED

engineTypeId IDREF #REQUIRED

enabled      (true | false)

label        CDATA #IMPLIED

id           CDATA #REQUIRED

>

Specifies a concrete instance of a particular search engine type. Instance may be bound to the product in order to show up only when that product is active. Engine can have its own label and description. If not specified, engine type data will be used. Finally, each engine type defines a valid set of parameters that can be passed to it to configure it. Engines can specify values of these parameters.


  • productId - used to determine which engine is appropriate for the current product (as defined by org.eclipse.core.runtime.Platform.getProduct()). If not specified, the engine will appear for all the products.
  • engineTypeId - the unique identifier of a valid seach engine type
  • enabled - if true, the engine will initially be enabled. Users can override this value in the UI.
  • label - an optional label for this engine. If not specified, the label of the engine type will be used
  • id - a unique identifier of this engine

<!ELEMENT param EMPTY>

<!ATTLIST param

name  CDATA #REQUIRED

value CDATA #REQUIRED

>

an optional parameter that is used to configure this instance of a search engine type. Valid parameters are defined by the engine type.


  • name - the name of the parameter
  • value - the value of the parameter

Examples:
The following is the example of the help search extension:


   <extension
         point=
"org.eclipse.help.ui.searchEngine"
>
      <engineType
            scopeFactory=
"com.example.xyz.XYZScopeFactory"

            label=
"XYZ Search"

            class=
"com.example.xyz.search.XYZSearch"

            icon=
"icons/etool16/xyzsearch.gif"

           pageClass=
"com.example.xyz.search.XYZSearchPage"

            id=
"com.example.xyz.XYZSearch"
>
         <description>
            Instances of XYZ Search search the XYZ site.
         </description>
      </engineType>
      <engine
            enabled=
"true"

            engineTypeId=
"com.example.xyz.search.XYZSearch"

            id=
"com.example.xyz.XYZSearch"

            label=
"XYZ Search"
>
      </engine>
      <engine
            enabled=
"true"

            engineTypeId=
"org.eclipse.help.ui.web"

            id=
"org.eclipse.sdk.Eclipse"

            label=
"%search.Eclipse.label"
>
        <description>
         %search.Eclipse.desc
        </description>
        <param 
         name=
"url"
 
         value=
"https://eclipse.org/search/search.cgi?q={expression}&amp;ul=&amp;ps=20&amp;m=all"
>
        </param>
      </engine>
    </extension>

Supplied Implementation:
Help UI plug-in provides search engine types for local help documentation, InfoCenter and Web search, as well as local help search engine instance. This instance does not accept parameters and has no product Id, thus will appear in every product.

Products can create concrete instances of InfoCenter and Web searches by using their engine id and the required paramaters.

InfoCenter engine type has engineId org.eclipse.help.ui.infoCenter and accepts one parameter url that points at the remote server where InfoCenter is installed. Results are shown in the same way as the local help results.

Web search engine type has engine id org.eclipse.help.ui.web and accepts one parameter url that represents a concrete search query with the actual search string replaced with a substitution symbol '{expression}', as in the following example:


https://eclipse.org/search/search.cgi?q={expression}&ul=&ps=20&m=all

Web search results are shown as one link that will open the web browser with the search string substituted in the url parameter.


Copyright (c) 2000, 2005 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 https://www.eclipse.org/legal/epl-v10.html


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire