Usage Guide of CodeBroker

This document explains how to use CodeBroker.

Running CodeBroker

Starting CodeBroker

Command: M-x start-cb

Key binding: C-c c b

Description: This command starts the backend search engine Fetcher, and creates a small RCI-display buffer at the end of the current emacs frame. It reads user model from cb_prefix/data/user-model and sets discource model to empty.

Ending CodeBroker

Command: M-x kill-cb

Key binding: C-c c b

Description: This command stops Fetcher and kills the RCI-display buffer. The contents of the user model are written back and the discourse model is set to empty.

Invoking delivery

User Action: Enter a doc comment or a signature

Description: CodeBroker delivers when a doc comment is entered, using the contents of the doc comment as a query and returns methods that match the query. The number of returned methods is determined by the variable cb-number-of-delivered in file cb_prefix/cb-setup.el

CodeBroker also delivers methods when a signature is entered, using both the signature and the doc comment before it as a query.

Finding info about a delivered method

User Action: Move cursor over the name of the delivered components.
Description: The message buffer shows the signature of the component (i.e., see the first figure).
User Action: Move mouse cursor over the synopsis of the delivered component in RCI-display.
Desrciption: The message buffer shows the keywords that are common to the doc comment and the document of the component (i.e., see the second figure).
User Action: Left-click on the delivered component
Description: A HTML browser is launched (or the currently open browser is used) to display the full document of the browser.

Filtering the delivery buffer

User Action: Right-click on the component.

Description: This right-click brings the Skip Components Menu, which has three levels of abstraction (from top to bottom): method, class, and package to be removed from the delivery buffer. If the method is chosen, only the method is removed from the delivery buffer. If the class is choosen, all the methods from the class are removed. If the package is chosen, all the methods from the package are removed.

For each chose level, a user can choose one of the three actions:

This Buffer Only The method, class, or package is removed from the buffer. It will reappear if you submit the same query again. This is meant for users to filter those apparently irrelevant components to make finding the needed ones faster.
This Session Only The method, class, or pacakge is not only removed from the current delivery buffer, but will not be delivered in later deliveries because it is added to the discourse model. But it will reappear if you stop CodeBroker and restart it. This is meant for users to filter out those components that are not needed for the current development task. For example, if you do not need methods from java.awt for the current program, you can add java.awt to the discourse model through this action.
All Sessions The method, class, or package is removed from the buffer, and will not be delivered forever because it is added to the user model file. This is used for users to add "known components" to the system. It is not recommended that users to add class or package to user models.

Reformulate queries

Command: cb-query-refine

User Action: Shift right-click on any components in the RCI-display buffer

Description: This creates a Query Reformulation Buffer for users to

Change the query by modifying the contents following Current Concept Query:
Change the query by modifying the signature following Current Constraint Query:
Ask the system not to deliver components from packages or classes by filling the field of Filtered Components. It accepts more than one packages or classes, with each one on a separate line, in the same format as Java import statement except no semicolon is allowed.
Ask the system to deliver only those components that are contained in the packages or class specified in the field of Interested Components. The format of this field is the same as the above one. When both fields are specified, the Filtered Components field is ignored.

To re-submit the query, type M-x cb-requery.

You have to kill the buffer to remove it.

Note: This has a very similar effect as adding things to discourse models with the Skips Component Menu. However, the fields specified in this Query Reformulation Buffer affect the locating process only once.

Customizing CodeBroker

Change the number of components to be delivered

(setq cb-number-of-delivered NUMBER_YOU_WANT) or change it directly in cb_prefix/elisp/cb-setup.el.

Change the threshold of adding components to your user model

If CodeBroker observes that you have used a component from the indexed repository for more than 3 times, it assumes that you have known the component very well and will never deliver the component to you. If you want to change the threshold, you can change set the variable cb-use-time-threshold (see cb_prefix/elisp/cb-setup.el) to any value you want.

Change the log level

CodeBroker has a automatical log mechanism. It logs in three different levels:

Level 0: No logging at all.
Level 1: The numbers of retrieved components, delivered components, components removed by user or discourse models, components added to user or discourse models, and components reused after they are delivered are logged and stored in cb_prefix/data/cb-log-1.
Level 2: The contents of queries, the names of components delivered, retrived, or filtered are logged and stored in cb_prefix/data/cb-log-2.

The default setting is level 1. After you have used CodeBroker for more than 30 days, the system will ask you if you would like to mail you log files to me (Yunwen Ye, the original developer of CodeBroker at

It is greatly appreciated and strongly recommended that you do so to enable me to further my research goals and improve the CodeBroker system. Level 1 log involves no names, so there is no risk of revealing the contents of your programs.

If you are very kind and would like to help me more, please set the log level to 2 and send log files periodically to me for analyzing CodeBroker.

You can disable the logging mechanism by seting cb-log-level to 0.

Get an example

Command: M-x cb-get-an-example <ret> enter name of a method <ret> User Action: Shift-right-click on a component name in the delivery buffer and choose the Get an Example to find an example for the component.

Description: The Illustrator agent of CodeBroker finds a program from a predetermined directory to find a Java program that uses the component. If several Java programs use the same component, the simplest one is shown in the *CB-Example* buffer.

Note: This is still under development. Currently, CodeBroker uses a very simple mechanism to show how this concept works. To use this, you have to change value of the variable BaseDirectory in src/illustrator/getExamples before installation, or in the bin/getExamples file after installation. Further development is underway to support this functionality fully.