Hipikat Installation and User Manual

This document serves as a brief introduction to installing and using Hipikat Client for Eclipse. Brief because, we hope, the tool is very simple to use and its interface is pretty obvious.

Installing Hipikat

To install Hipikat, use either the Eclipse update manager (setup instructions) or manually install the zipped package from the downloads page.

That's it! You can now start Eclipse.

Hipikat Setup

Once Hipikat client is installed, you will see the "Hipikat" tab in the Eclipse Preferences dialog. Within it, you can set up the following parameters:

• Address of the Hipikat server (set by default to our server running at the University of British Columbia).
• URL of the Bugzilla server (initialized to Eclipse Bugzilla server, by default). This is used by the "Bug report" viewer to view Bugzilla items within Eclipse.
• Your email address. This field is not required, but it will let us know the association between you and the client ID of your Hipikat plugin. See the downloads page for the description of how client IDs work.
• Which browser to use to view Web pages and newsgroup articles. This can either be the system default browser (application registered to handle URLs on Windows, or Mozilla or Netscape on Unix), or you can give the path to your own browser, including any command-line arguments it may require. If any arguments need space within them, including the pathname, be sure to enclose them in quotes, for example:

  C:/Program Files/Opera/opera.exe or "/usr/bin/X11/xterm -e /usr/bin/lynx".

  Note:Mozilla 1.0 for Windows has a bug in that even when it registers itself as a default Web browser, it still leaves Internet Explorer as the handler for "news:" URLs. Therefore, you will be forced to use Outlook to read news articles recommended by Hipikat, until the issue is resolved in subsequent versions of Mozilla (the bug has been entered in Bugzilla: http://bugzilla.mozilla.org/show_bug.cgi?id=121369). Alternatively, the registry key under HKEY_LOCAL_MACHINE\SOFTWARE\Clients\News should be updated to point to Mozilla.

Using Hipikat

The basic user interface to Hipikat is very simple: if it's possible to make a query on something on screen, there will be an option "Query Hipikat" in the right-click menu. For example, Hipikat knows about files in the CVS. Therefore, you can right-click on any versioned file -- in the Navigator, Package Explorer, or CVS Repositories view, even on a revision in the CVS Resource History view -- and select "Query Hipikat" from the context menu, as can be seen in figure 1:

Hipikat can also be used as an integrated search interface to the Eclipse project. When you have the Hipikat plugin installed, you will see that the search dialog has a Hipikat tab present, as in figure below. (Note: If the Hipikat tab is not visible, it may be because it has to be enabled: this is done from the "Customize" button, in the bottom-left of the dialog.) Enter the search terms in the text box and press Enter to proceed. The terms are implicitly AND-ed together, and we use some familiar information retrieval like stemming (eliminating common endings, so that, for example, both a search on "run" will match documents containing "run", "running", "runs", etc.). Currently, numbers are not treated as searchable terms, although words containing a combination of numbers and special characters like period are (that is, searching on "123" will not give any matches, while "2.0" will).

Hipikat can also be queried by right-clicking on a bug report opened in the Bugzilla Viewer, a versioned file in the editor, or a class member in either the Outline view or the Hierarchy view.

Results of a query or search come up in the Hipikat view, shown below. The view lists recommendations, giving for each its type (Web page, news article, CVS revision, or a Bugzilla item), name, why it was recommended, and -- if applicable -- an estimate of how close the match was.

Double-clicking on a recommendation will open it for viewing. Bug reports and CVS artifacts are opened within Eclipse, while news articles and Web pages are opened through the Web browser. Also, right-clicking on a recommendation will pop up a context menu. From this menu you can also open the item for viewing, but more importantly, you can use it as another Hipikat query, as well as remove it from the recommendation list if it doesn't seem relevant to your current task. Lastly, for a CVS revision, you can also see its differences to the preceding revision in the standard Eclipse "Compare with CVS revision" view.

Previous Hipikat queries are accessible through the drop-down history menu at the right end of the view's toolbar. The toolbar also contains (going further from right to left) buttons to stop an ongoing query (query in progress is indicated by spinning arrows), and to indicate usefulness of a recommendation (or lack thereof) by giving it a thumbs up or down. (Currently, the only visible effect of ranking an item is moving it up or down in the recommendation list view, although we plan to eventually use it to refine the recommendations by a collaborative filtering step.)

In addition to the Hipikat search interface, a Bugzilla Search tab has also been added to the Eclipse Search pane. You can enter a bug ID or keywords in the text field and, if desired, limit the search by selecting particular attributes within the middle section of the search pane. Press Enter or click "Search" to proceed.

If a Bugzilla ID was entered, that particular bug report will open in the Bugzilla Viewer. Otherwise, the results will appear in the Search tab. From here, you can open any of the items by double-clicing on them. You can also query Hipikat on one of the items by right-clicking on it and selecting "Query Hipikat".