Sample Scenarios

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.

1. Sample Change Task
2. Using Eclipse APIs
3. Debugging Exceptions
4. Making a Change

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.

1. Open the run-time workbench.
2. Switch to the CVS Repository Exploring perspective.
3. Open the repository in the CVS Repositories view.
4. Expand Versions node, and then expand TeamProject project to see all versions present in the project. (There should be one, which you created in the CVS tutorial earlier).
   
5. Expand HEAD (that's the implicit tag representing the most recent revision of all files).
6. Right-click in the view and select Tag as Version from the context menu. Enter another version tag, for example: v_A2.
7. Look for the version in the project under the Versions node. It's not there yet.
8. Right-click the project and select Refresh View. The version appears in the view.
   

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 execute method of TagAction and start a Runtime Workbench in the debug mode (as described in the tutorial on writing Eclipse plugins). Try to execute Tag as Version on a file in the Runtime Workbench's Package Explorer, and you'll see that the breakpoint has been hit. Try the same thing now on the same file in the CVS Repository View, and you'll see that the breakpoint is not hit at all.

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.

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.
You might try to use code completion to help you in making the right calls to the API (as shown in the figure below), but there are numerous methods suggested; it may not be obvious which call to use.

Hipikat can help you: to solve this problem, try Hipikat search.
Type control-H (or go to Search > Search) and click on the Hipikat tab, then enter "resource traversal" in the text field and click "Search". The results will appear in the Hipikat Results tab.
Neither the web articles nor the Bugzilla reports look like they would be much help, but if you scroll down past them, you'll reach the newsgroup postings. The first two of these, based on their titles, look quite promising.

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.
Screensnapshots of the results of these actions are shown below. These articles provide direct help on how to use the API to achieve your desired goal.

*** If you don't have an Eclipse newsgroups username, you can get one here.

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.

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.
You will likely be able to get an idea of a good starting point, you might find some reusable code (depending on how closely the other task resembles yours), and you'll gain knowledge of project idioms and implementation patterns.

Let's start by taking a look at the bug report that applies to your task.
Go to Bugzilla Search (ctrl-H or Search > Search, and then click the Bugzilla tab) and type in the bug ID: 20982.
It will open in the Bugzilla Viewer in your Eclipse window:

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.
Bug 10541, a few lines down the list, looks like it refers to a similar task mentioned in Bug 20982. Open it by double-clicking on it or by right-clicking and then choosing "View selected". This will open the report for Bug 10541 in the Bugzilla Viewer.
Notice that at the end of the report, there are comments that list changes made; this is what we are looking for.

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.
Since the changes deal with committing files while in the sync view, CommitSyncAction.java sounds like it would be a helpful file to look at.

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.