Hipikat's purpose is to point out work already done in the project that's similar to the one the developer (you) is currently working on. You can also use it to search through the archives of newsgroups and other information about the project (such as the Web site) to whether your question has already been discussed and answered in the past.
This section will give you an idea of the things that are possible with Hipikat, by describing three scenarios in which Hipikat can be used to help a project team member gain a better understanding of how to go about his or her task.
Example 1: Sample Change Task
In this example, we will guide you through an example interaction of using Hipikat to fix an Eclipse bug. The bug we use is Bug 116, which concerns showing new versions in the CVS Repository view when "Tag as version" is selected in the view's context menu.
First, open the bug report. You can do this directly from Eclipse. Open the Search dialog, switch to the Bugzilla Search pane, and enter the bug number into the "Bug id or Summary" field:
Note: Entering more than just a single bug id in this dialog will execute a Bugzilla search and display results in the Search view.
An editor will open displaying the bug:
You can scroll through it and read all the comments that were added to
it (of which, in this case, there weren't many). Note that the bug was opened
in version 1.0 of eclipse, so some terminology has changed by now. (Specifically,
"streams" have been renamed to "versions" in the CVS Repository view.)
Let's try to reproduce the bug and understand it, so we can decide what the desired behaviour should be.
The desired behaviour would be to have the version appear in CVS Repositories view immediately after you created it via the dialog. Keep in mind, though, how long it took whey you selected "Refresh View" in the last step -- that's what the comment by "KM" in the Bugzilla was about. "Refresh View" works by talking to the repository to find out all the tags in a project (or projects), something which is not necessary in this case since we're adding to the view the tag that was just created by the user!
At this point you can ask Hipikat whether it knows about prior work that's been done in Eclipse that might be similar to your change task. To do this, right-click in the bug editor and select Query Hipikat from the context menu.
After a brief wait while the Hipikat server is returning the results, a Hipikat Results view opens at the bottom of the screen:
Each Hipikat suggestion lists the artifact's type (e.g., a file revision, Web page, etc.), descriptive name, the reason why it was suggested, and its confidence. All the artifacts suggested in this case are prior change tasks (bug fixes and enhancements) logged in Bugzilla. These suggestions were made based on their similarity to the text of the description of bug 116. The "closeness" of the similarity is in this case shown as a number in the Confidence column. These are pretty relative and are mostly just used internally to rank the matching documents, so you don't have to worry about them too much (briefly, two identical documents would have a similarity of 1.0, while documents that have nothing in common would have similarity of 0). In other cases, as we will see later, the confidence might be more descriptive; this depends on the reason a recommendation was included.
Selecting a recommendation in the list shows its name in the status bar, in case it doesn't fit in the results view. Double-clicking will open the artifact, either in Eclipse or an external viewer (such as a browser or the newsreader), depending on the type of the artifact. Now scroll through the list of recommendations for Bug 116 and see if any of them look promising.
In particular, note Bug 11419: "Automatically add version to repo view when tagging". This certainly looks similar to what we're currently working on. Open the bug report to have a closer look at its details:
Note two things: first, this bug covers functionality similar to that of Bug 116, except that it is invoked from context menu in the Package Explorer and not CVS Repository view. Second, the bug has been marked fixed. This means that we might be able to learn from its fix about the techniques and APIs we will need to implement the changes required for Bug 116.
With this in mind, we make another Hipikat query, this one on bug 11419. You can do this either from its editor, as we did before, or from the context menu when it is selected in the Hipikat Results view. Notice the arrows at the top of the Hipikat Results view spinning; this indicates that the query is in progress. (If you want to cancel the query, click on the spinner.) Shortly, the results view will change to show a new set of recommendations:
As you can see, at the very top of the list are file revisions from the CVS repository that Hipikat recommended because they likely implement the fix. (There are a number of different ways this is determined, as you can sometimes see in the "Reason" column. It is also not perfect: there may be a case when the recommendation list for a "fixed" bug does not include any source files, because Hipikat could not determine the relationship.)
In this case, there is only a single file revision included in the recommendations. Select it to see in the status line at the bottom of the window which class it came from (the status bar will display the full information: repository, directory, file name and its revision number): TagAction.java. Without even opening it, you can see from the directory name that it came from plugin team.cvs.ui, which makes sense. Right click on it to see what options we have in the Hipikat Results context menu:
Let's look now at the option in the context menu: "View selected" opens the artifact and is equivalent to double-clicking on it. "View revision's changes" and "Show in resource history" appear only in the context menus of CVS artifacts. "View revision's changes" will show the comparison between the revision and its immediate ancestor in a standard Eclipse "compare" view where the revisions's additions to the code will be highlighted. "Show in resource history" does the same thing as the corresponding item in the Team context menu in the Package Explorer: it shows the file's revision history, along with all the check-in dates, comments and revision authors. "Remove" and "Remove all" are pretty straight-forward and remove the items from the recommendation list; you can use them when a Hipikat recommendation is obviously not useful to you and you don't want it to clutter the view. Lastly, "Query Hipikat" executes a Hipikat query on the artifact selected in the results view.
Back to our task, let's look at the changes to the code that were introduced by the recommended revision. Select it and choose View revision's changes from the context menu. The following editor will shortly appear:
As you can see, only the TagAction's run method has been changed by the revision and the bulk of the change revolves around the call to the CVSUIPlugin's repository manager. At this point, we can switch to Eclipse and use its built-in search facilities to find out more about the classes. First, we want to open the currentTagAction.java. (Opening the revision suggested by Hipikat will open the editor on the contents of that revision only. This editor will not be linked in with the rest of the workbench projects-- that is, you cannot perform various Java searches from it, view hierarchy, set breakpoints, etc. -- and besides, we want to find out whether that code is still present in the current revision of TagAction at all.)
Therefore, open TagAction.java now. You can do it by executing a Java search for the declaration of class TagAction, or simply look for it in the Package Explorer (you can see the class's plugin and path from the status bar when the recommendation is selected in Hipikat Results view): it will be in org.eclipse.team.cvs.ui plugin. You will see that the code has changed a bit since revision 1.13, but that version's additions are still recognizable in the execute method:
Now we can use Eclipse's Java navigation to learn more about the classes and methods that are used in those lines. Try selecting CVSUIPlugin, addVersionTags, getCVSFolderFor, getProject, and other class and method references in those lines (e.g., the interaction betwen CVSTeamProvider and IResource) and selecting Navigate|Open Declaration (or the F3 shortcut) to see the relevant source, which often also includes the Javadoc. Spend some time trying to understand how these methods work and how the code added to TagAction.execute in revision 1.13 uses them to fix bug 11419. You should try to get an understanding of functions and difference between ICVSResource and IResource (and their subclasses representing folders and files), what a repository manager is in the CVS UI plugin, and what its "addVersionTags" method does. If using the F3 shortcut takes you to an interface, try to find classes implementing the interface to see the actual code. You can also try setting a breakpoint in TagAction.execute and check what happens when you tag a file, folder, or project from the Package Explorer.
If you now have a good idea now how the tags are added to the repository manager (and then shown in the CVS Repository view), the question remains why the versions appear in the CVS Repository view when Tag as Version is executed from the context menu on a resource in the workspace (feature added by the fix for bug 11419), but not when it is executed from the CVS Repository view itself (which is the bug we're working on, 116).
There are a couple of ways to test this, one of which is to set a breakpoint in the
Therefore, it is more likely that some other action is tied to the Tag as Version in the CVS Repository View. This, as we've learned in the Eclipse plugins tutorial, is defined in the plugin's (team.cvs.ui) plugin.xml file. Try opening that file now and look through it for the references to TagAction (you can use Edit->Find to search for a text within an editor window). You will find only one:
Notice that this action is defined as contributing to the context menu of IResource's, which - as we know from our exploration of TagAction earlier - correspond to files and directories in the workspace (that is, local files). CVS Repository view, on the other hand, displays the remote repository, whose contents are not in the Eclipse workspace.
There are a few ways now to look for what might be another class handling the action. An easy one is to just look at other actions in the team.cvs.ui plugin. Another one would be to look in its plugin.xml for other actions using the label "Tag as Version...". Actually, we would have to look in the plugin.properties, because (as indicated by "%" prefix in the label names in plugin.xml) the label names declared in plugin.xml are just the names of properties in plugin.properties file (to make changing them, such as for internationalization, easier). Let's do the latter:
Note the second identical label, this one using property name TagInRepositoryAction.label. Let's go back to plugin.xml and try to see where it is referenced:
As the action contributed to ICVSRemoteResource, with the label "Tag in Repository", TagInRepositoryAction certainly looks promising. Let's open it and have a look at its execute method:
Note the highlighted code in this method that's very similar to the code in TagAction before the changes fixing Bug 11419 were implemented (in particular, note the call to ICVSRemoteResource.tag within a loop -- "for" in TagInRepositoryAction and "while" in TagAction). Therefore, that's likely where we need to place our changes to fix Bug 116.
Go ahead and try to add the code using what you've learned from the fix for Bug 11419. What were the steps added there? The version tag was added to the repository manager of the CVS UI plugin, on the project to which the tagged files belonged. Keep in mind that TagInRepositoryAction is working on ICVSRemoteResource, while TagAction worked on IResource, so you should have an understanding of how the two resource classes (and their subclasses) are similar and different.
Hint: whereas in Bug 11419 the first argument to the RepositoryManager.addVersionTags was the CVS folder corresponding to the project folder itself (returned by CVSWorkspaceRoot.getCVSFolderFor), here you do not have an IResource (whose project can be found through CVSTeamProvider) but directly a CVS resource. In this case, the CVSFolder of the project can be found by going up the parent relationship.
Example 2: Using Eclipse APIs
Imagine that you are a developer of Eclipse. The version of Eclipse you are working on does not ensure that a user is asked, on a commit of a directory to a version control system, to commit any uncommitted files in that directory. Your task is to provide this functionality. To achieve this goal, you must be able to programmatically traverse the directory tree, looking for unmanaged resources (files).
From previous experience, you know that the Eclipse API you need to use is the IResource interface, whose subinterfaces IFolder and IFile represent resources in the file system.
The problem is, it is not obvious to you how to use the API to traverse
the directory tree.
Hipikat can help you: to solve this problem, try Hipikat search.
Open these articles either by double-clicking on them or by right-clicking and selecting
"View selected", and then entering your username and password for Eclipse newsgroups.
*** If you don't have an Eclipse newsgroups username, you can get one
Example 3: Debugging Exceptions
The problem: A null-pointer exception continually occurs from an Eclipse UI call, but the documentation doesn't explain why. Could this be an Eclipse bug?
Solution: We can try to find out why this happens by highlighting the relevant console output, right-clicking on it, and selecting "Query Hipikat".
Hipikat comes up with a Bugzilla report for Bug 19761, which can be opened either by double-clicking it or by right-clicking and then selecting "View selected". It will open in the Eclipse Bugzilla Viewer, where you can find out how the issue was resolved.
. . .
Example 4: Making a Change
Suppose that you are a newcomer to the Eclipse project, and you have been assigned to begin work on an enhancement request (the one introduced in Bugzilla Bug 20982), but the problem is, you are not entirely sure how or where to start.
Here is a solution: use Hipikat to search for similar work that has been done in
the past, and find out how it was implemented.
Let's start by taking a look at the bug report that applies to your task.
Now, to find other artifacts that are related to this one, right-click on the bug viewing
pane and select "Query Hipikat". This will result in a list of recommendations in the Hipikat
Results pane at the bottom of the window.
To find artifacts related to this bug report, right-click either on the line in the Hipikat
Results tab that contains Bug 10541 or on the Bugzilla viewing pane, and select "Query Hipikat".
Many of the new items listed are CVS revisions, which is exactly what we need. Move the mouse
over each item in the list to find the file(s) that you would like to inspect.
To open the file alongside it previous revision so that the two can be compared, right-click on the
line containing the CommitSyncAction.java file, and select "View Revision's Changes".
You will now be able to inspect the method of implementation of the changes discussed in Bug 10541,
and apply the knowledge to your own work on the enhancement request contained in Bug 20982.