E4/Search Console/Developers Guide

Search Console

The Search Console is implemented on top of the Model-View-Controller design pattern. The diagram below shows the Search Console main components and the relationship between them

Controller

The controller is an internal component and cannot be used directly from contributors. The controller implements use-cases and determines the framework state at every point in time. The controller interacts with outer world via the view. In the case of the search console the view is represented by a small UI framework which on its turn can be customized. To put in in other way, the controller's purpose is to gather the user input data, to pass it to the search engine, to receive the search result and make the UI display it.

Search Engine

The search engine has the purpose of identifying

• the registered object types
• the search destination categories available
• the search providers implementations available

When the search starts, the search engine chooses suitable for the currently selected search destination and object type search provider and executes its search query. The result from the search query is passed back to the controller.

View

The view has two main responsibilities:

• to gather the input parameters
• to display the search result

Contributors are allowed to contribute their own UI (Custom Search Parameters) via which they can create user interface for displaying special custom search parameters.

There are two options for displaying the search result

• Contributors may register their own UI. The search result will be passed to this UI and it is up to its implementation to represent it in the desired way. With this approach however, contributors are on their own and it is up to them to integrate the results within the Eclipse environment (drag and drop, context menus, etc.)
• Search console provides a generic results UI which look and feel can be customized. The result is displayed in a tree structure. Contributors can:
  • build the tree structure (via content providers)
  • customize the tree nodes' looks (via label providers)
  • build the tree nodes' tool tip content (via tool tip providers)
  • register double click listeners
  • create context menu items/toolbar buttons to work with the search result

In order to customize the generic results UI, contributors should register slave controllers and view customizations via the designated extension points. Slave controllers should contribute actions which represent the business logic for the operations to be performed on search result items. View customizations are supposed to install these contributed actions into the user interface (via e.g. context menu, toolbar buttons)

The sequence diagram below gives some more details on installing the actions into the UI

Search Favourites

The search favourites component implements "bookmarking" an already discovered item for further use. Bookmarks are physically persisted and can survive a workbench restart.

Search favourites is also built on top of the MVC design pattern

The search favourites view can be customized the same way as the search console result view – via slave controllers and view customizations.

Persistency

The favourite items persistency is implemented via a persistency framework. Contributors which would like to take advantage of persisting favourite items should contribute store providers and load providers

The sequence diagram below illustrates the interaction between view, controller, persistency framework and store providers when an item is being “bookmarked”

When the search favourites view is opened the bookmarked items are being loaded

Contributing to the search console

The search console defines several several extension points via which contributors may contribute implementations to the framework.

Object types

   <extension
         point="org.eclipse.platform.discovery.runtime.objecttype">
      <objecttype
            displayname="Cheat Sheets"
            id="org.eclipse.demo.cheatsheets.search.objecttype.cheatSheet">
      </objecttype>
   </extension>

The registered object types appear in the “search for” combobox. The value of the “displayname” attribute is displayed to the user, and the value of the “id” attribute is used as unique object type identifier

Destination categories

   <extension
         point="org.eclipse.platform.discovery.runtime.destinationcategory">
      <destinationcategory
            destinationclass="org.eclipse.demo.cheatsheets.search.destinations.CSDestination"
            displayname="Local Cheetsheets"
            id="org.eclipse.demo.cheatsheets.search.destinationcategory.local">
      </destinationcategory>
   </extension>

A destination category groups similar search destinations. The “displayname” attribute value is used for displaying purposes. The value of the “id” attribute represents unique destination category identifier. The value of the “destinationclass” attribute specifies the class/interface which all search destinations from this group should extend/implement. Check the search destinations provider extension point for details on this attribute.

Search destinations providers

   <extension
         point="org.eclipse.platform.discovery.runtime.destinationsprovider">
      <destinationsprovider
            destcategoryid="org.eclipse.demo.cheatsheets.search.destinationcategory.local"
            id="org.eclipse.demo.cheatsheets.search.destinationsprovider.local"
            provider="org.eclipse.demo.cheatsheets.search.destinations.LocalCSDestinationsProvider">
      </destinationsprovider>
   </extension>

A destination provider is an implementation which providers available search destinations for a destination category specified (attribute “destcategoryid”). There might be several destinations providers per a single destination category. However, all the destinations they provide should extend/implement the class/interface specified by the “destinationclass” attribute of the destination category contribution.

Destinations providers are required to implement the IDestinationsProvider interface

Search subdestinations

It is possible to specify that the keyword we are searching for is located in a specific “attribute” of the search artefact. For example, one may want to search for a keyword in an artefact's documentation or in the artefact technical name. In order to implement this feature the search console introduces search subdestinations

   <extension
         point="org.eclipse.platform.discovery.runtime.searchsubdestinations">
      <subdestination
            id="org.eclipse.demo.cheatsheets.search.subdestination.name"
            displayname="Name"
            objecttypeid="org.eclipse.demo.cheatsheets.search.objecttype.cheatSheet"
            categoryid="org.eclipse.demo.cheatsheets.search.destinationcategory.local"
            defaultSelected="true">
         <conflict
               conflictingSubdID="org.eclipse.demo.cheatsheets.search.subdestination.description">
         </conflict>
      </subdestination>
   </extension>

The subdestination contribution should specify the object type ID it is relevant for. The “defaultSelected” attribute specifies whether the subdestination should be enabled by default. The “conflict” element specifies a list of subdestination Ids which this subdestinations conflicts with. Thus it is possible to define mutual subdestinations.

The subdestinations (if available) appear in a drop-down box available right next to the keyword textbox.

Search providers

   <extension
         point="org.eclipse.platform.discovery.runtime.searchprovider">
      <searchprovider
            id="org.eclipse.demo.cheatsheets.search.internal.search.LocalCheatSheetSearchProvider"
            instance="org.eclipse.demo.cheatsheets.search.internal.search.LocalCheatSheetSearchProvider"
            objecttypeid="org.eclipse.demo.cheatsheets.search.objecttype.cheatSheet"
            supportstextsearch="true">
         <category
               categoryid="org.eclipse.demo.cheatsheets.search.destinationcategory.local">
         </category>
      </searchprovider>
   </extension>

The value of the “instance” attribute specifies the fully qualified name of the class implementing the search provider. The value of the “objecttypeid” attribute specifies the object type this search provider is capable of searching for. The boolean value of the “supportstextsearch” attribute specifies whether the current search provider can search by a keyword. The “category” element specifies a list IDs of destination categories this search provider is applicable for.

Search providers instances are required to implement the ISearchProvider interface

Advanced search parameters

It is very possible that the standard search parameters (destination and keyword) are not sufficient for performing a search. Therefore contributors may specify their custom UI via which the user can input additional search constraints. This UI is displayed in an “advanced options” section in the search console view.

   <extension
         point="org.eclipse.platform.discovery.ui.advancedsearchparams">
      <advancedsearchparams
            id="org.eclipse.demo.cheatsheets.search.advancedsearchparams"
            searchproviderid="org.eclipse.demo.cheatsheets.search.internal.search.LocalCheatSheetSearchProvider"
            uicontributorclass="org.eclipse.demo.cheatsheets.search.internal.CustomSearchParamsUiContributor">
      </advancedsearchparams>
   </extension>

The value of the “uicontributorclass” specifies the fully qualified name of the class which implements the custom user interface. The value of the “searchproviderid” attribute specified the ID of the search provider this user interface is applicable for.

UI contributor instances are required to implement the IAdvancedSearchParamsUiContributor interface

Custom search results user interface

Contributors may implement their own user interface which displays the search results

   <extension
         point="org.eclipse.platform.discovery.ui.customresultui">
      <contributor
            id="org.eclipse.demo.cheatsheets.search.resultui.creator"
            creator="org.eclipse.demo.cheatsheets.search.internal.resultui.SearchResultCustomUiCreator"
            searchproviderid="org.eclipse.demo.cheatsheets.search.internal.search.LocalCheatSheetSearchProvider">
      </contributor>
   </extension>

The value of the “creator” attribute specifies the fully qualified name of the class which creates the custom UI. The value of the “searchproviderid” specifies the ID of the search provider whose result should be displayed by this custom UI.

The results UI creators instances are required to implement the ISearchResultCustomUiCreator interface

Customizing the generic search result user interface

The search console offers a generic implementation for displaying the search results. Contributors may customize the generic view via slave controllers and view customizations. This concept has been already discussed above. Therefore only their contribution is shown in the example below

   <extension
         point="org.eclipse.platform.discovery.integration.searchconsole">
      <viewcustomization
            customizationimpl="org.eclipse.demo.cheatsheets.search.internal.view.console.ConsoleCustomization"
            id="org.eclipse.demo.cheatsheets.search.internal.view.ConsoleCustomization">
      </viewcustomization>
      <slavecontroller
            id="org.eclipse.demo.cheatsheets.search.internal.slave.ConsoleSlaveController"
            implclass="org.eclipse.demo.cheatsheets.search.internal.slave.ConsoleSlaveController">
      </slavecontroller>
   </extension>

Slave controllers are required to implement the ISearchConsoleSlaveController interface; view customizations are required to implement the ISearchConsoleCustomization interface

Contributing to the search favourites

Persistency

Favourites items are stored and loaded via implementation called store and load providers. This concept has been already discussed above. Below are examples for contributing such implementations

• Store provider

   <extension
         point="org.eclipse.platform.discovery.integration.persistence.mementostoreprovider">
      <provider
            class="org.eclipse.demo.cheatsheets.search.internal.persistency.CSStoreProvider"
            id="org.eclipse.demo.cheatsheets.search.internal.persistency.CSStoreProvider">
      </provider>
   </extension>

The “provider” element specifies the store provider. Its “class” attribute specifies the fully qualified name of the class which implements the provider

Store providers are required to implement the IMementoStoreProvider interface

• Load provider

   <extension
         point="org.eclipse.platform.discovery.integration.persistence.mementoloadprovider">
      <provider
            class="org.eclipse.demo.cheatsheets.search.internal.persistency.CSLoadProvider"
            id="org.eclipse.demo.cheatsheets.search.internal.persistency.CSLoadProvider">
      </provider>
   </extension>

The “provider” element specifies the load provider. Its “class” attribute specifies the fully qualified name of the class which implements the provider

Load providers are required to implement the IMementoLoadProvider interface

Customizing the search favourites view

Similarly to search console customization, contributors may register slave controllers and view customizations to the search favourites view. The concept has been already discussed so here is just an example

   <extension
         point="org.eclipse.platform.discovery.integration.searchfavorites">
      <viewcustomization
            customizationimpl="org.eclipse.demo.cheatsheets.search.internal.view.favorites.FavoritesCustomization"
            id="org.eclipse.demo.cheatsheets.search.internal.view.favorites.FavoritesCustomization">
      </viewcustomization>
      <slavecontroller
            id="org.eclipse.demo.cheatsheets.search.internal.slave.FavoritesSlaveController"
            implclass="org.eclipse.demo.cheatsheets.search.internal.slave.FavoritesSlaveController">
      </slavecontroller>
   </extension>

Slave controllers are required to implement the ISearchFavoritesSlaveController interface; view customizations are required to implement the ISearchFavoritesViewCustomization interface

Search destinations preferences

Search destinations are the concrete places a search can be performed in. In the most common case, those destinations provide information on how to connect to a remote system. In order to provide consistent user experience, the search console framework offers the Search Destinations preference page which is designed to create new search destinations and manage existing ones.

Contributed search components could contribute a search destination configurator in order to plug into this preference page

   <extension
         point="org.eclipse.platform.discovery.destprefs.configurator">
      <destinationConfigurator
            contributorClass="org.eclipse.demo.cheatsheets.ui.CheatSheetsDestinationPrefsConfigurator"
            destProviderId="org.eclipse.demo.cheatsheets.search.destinationsprovider.local"
            id="org.eclipse.demo.cheatsheets.ui.dest.prefs.configurator">
      </destinationConfigurator>
   </extension>

Contributed destination preferences configurators are required to implement the ISearchDestinationConfigurator interface