Whenever you are using a new framework or API, the challenges are always the same: to learn about all the expectations and usage rules implicit in the API. This can be a very time-consuming process. Fortunately, you are not alone in this; often, others have already overcome these challenges for the API in question. But how to tap into their hard-won knowledge?
This is where Eclipse Code Recommenders comes in. Code Recommenders automatically analyzes existing code using that API and extracts common usage rules and patterns from it. In the form of recommendation models, this knowledge is then fed back into your IDE. Powered by these models, Code Recommenders’ intelligent code completion and extended API documentation then propose to you what others have done in a similar situation. This helps you get up to speed with the new framework or API without countless hours of searching the Internet on how to solve a common problem.
Setting up Code Recommenders is extremely easy, simply install and activate it.
Access the marketplace via Help > Eclipse Marketplace … and search for “Code Recommenders”. From the search results, select “Eclipse Code Recommenders” and click Install. Next, just confirm this selection and accept the license agreement. Finally, click Finish and restart your Eclipse IDE when prompted.
To activate Code Recommenders, trigger Content Assist on an instance of a well-known type like
The first completion proposal will ask you to activate Code Recommenders.
Simply press Enter to do so. That’s it! You are now ready to use Code Recommenders.
There is a lot more to Code Recommenders, though. Read along for information on what features Code Recommenders brings you and how to configure them to your needs.
Eclipse Code Recommenders adds several completion engines to Eclipse’s Content Assist (also known as code completion). Each of these engines makes one aspect of code completion more intelligent.
The Call Completion engine, for example, provides you with recommendations of likely methods to call whenever you trigger code completion on an object, be it a variable, field, or constant. The call completion engine bases its recommendations on what other developers in a similar situation have called on an object of the given type.
The Override Completion engine provides you with recommendations which methods you are most likely to override when triggering code completion in the body of class.
The Subwords Completion engine works together with any other completion engine, or completely on its own. It allows you to enter any part of a completion’s text instead of only exact prefixes.
The Chain Completion engine suggests entire call-chains of methods that return the currently expected type. It works both as a Quick Fix (Ctrl/Cmd + 1) or as its own Content Assist engine reached by multiple Ctrl + Space presses.
The Adaptive Template Completion engine suggests multiple methods that frequently occur together on an object. It works as its own Content Assist engine reached by multiple Ctrl + Space presses. The Adaptive Template Completion engine can be triggered both on object references (pictured above) and type references (pictured below).
The Base Relevance Completion engine adds the standard Eclipse JDT proposal weightings as a base value, ensuring that factors like expected types are factored in when sorting proposals. We therefore suggest that you keep this engine enabled.
The Completion Tips engine provides tips on how to enhance your code completion experience. It may propose, e.g., to install extensions to Code Recommenders that add further features. To do so, it displays additional proposals at the bottom of the list. These proposals are only shown until selected by keyboard; once you have seen the associated tooltip, they won’t show up again.
Eclipse Code Recommenders offers several areas of customization, all of which are accessible through the Eclipse preferences.
You can selectively enable and disable Eclipse Code Recommenders’ completion engines on the Code Recommenders > Completions preference page. Some completion engines also allow for further customization. You can configure them either by selecting the engine on the Code Recommenders > Completions preference page and then clicking Configure or by directly navigating to the engine’s preference page. (All engines that ship with Eclipse Code Recommenders add their preference pages under the Code Recommenders category, but third-party engines may use a different category.)
You can customize the Chain Completion’s settings on the Code Recommenders > Completions > Chains preference page. Here you can adjust the minimum and maximum depth of call chains, as well as the maximum number of chains to find. Increasing these values will slow down Chain Completion with the user adjustable timeout serving as an upper bound for the search time. You can specify ignored Object types. No call chains through ignored types will be found.
Chain Completion always works as a Quick Fix (Ctrl/Cmd + 1). If you want to use it through Content Assist (Ctrl + Space) as well, you have to enable Chain Proposals (Recommenders) in the Java > Editor > Content Assist > Advanced preference page. Add it to the Content Assist cycling checkbox list.
Note that that Chain Proposals cannot be active on the default Content Assist page as its slight delay would slow down your workflow. Activating it on the default Content Assist page will have no effect.
Eclipse Code Recommenders relies on so-called model repositories to provide recommendation models for intelligent code completion and enhanced API documentation. You can add, edit, and remove model repositories on the Code Recommenders > Models preference page. The default model repository provides Code Recommenders models for the Java Runtime Environment (JRE) and org.eclipse classes.
If you wish to add Code Recommenders support for more APIs, add new model repositories by pressing the New... button. If more than one repository provides models for the same class, the respective models are downloaded from the first repository in the list. You can change this priority by using the Up and Down buttons.
Code Recommenders uses so-called advisors to assign project coordinates to your projects’ dependencies. These coordinates are used to identify the correct Code Recommenders models for each dependency. Several advisors, each with their own identification strategy, are available at the Code Recommenders > Advisors preference page. Hover above an advisor to get a detailed description of how it identifies a dependency’s coordinate.
When trying to assign a coordinate to a dependency, Code Recommenders will use advisors in the order they appear in this list. You can selectively enable or disable each advisor and change their priority by using the Up and Down buttons.
After using Code Recommenders for a while, it will ask you to fill out a user survey. If you dismiss the dialog, it will not pop up again. However, you can always find a link to the survey at the Code Recommenders > User Survey preference page, should you decide to provide feedback at a later time. Either way, is greatly appreciated as it helps us to further improve Code Recommenders. So please take a few moments to fill out the survey.
You can export preferences related to the model repositories consulted by Code Recommenders. This includes repository URIs and the list of advisors used to assign project coordinates to dependencies. This can be useful to distribute common settings within your team.
To export the preferences go to File > Export > General > Preferences and select Code Recommenders Model Repositories. Choose a location where the preferences are to be saved and click Finish.
To import settings from an existing preferences file, go to File > Import > General > Preferences and browse for the preferences file. Select Code Recommenders Model Repositories and click Finish.
Code Recommenders has a number of views that offer you extended documentation as well as information about your projects, their dependencies, and Code Recommenders models for them.
Available under Window > Show View > Other... > Recommenders > API Docs, the API Docs view is the one-stop solution for all your documentation needs. It features several pages that offer enhanced documentation about your current selection. Simply select a type or object in your code editor to get more information on how to use it.
The Javadoc page gives you quick access to classic Javadoc documentation with all the features of Eclipse’s built-in Javadoc view. Thus, the API Docs view can act as a complete replacement for it; there’s no need to waste precious screen space with two views.
The Call Recommendations page shows you which methods you likely want to call on a selected object. This page uses the same information as the call completion engine; thus, its recommendations are context-sensitive and take into account how the object was created and what methods have already been called.
The Overrides page shows you which methods you likely want to override when subclassing a selected type. This page uses the same information as the overrides completion engine. Additionally, it shows you exactly how often other developers have overridden specific methods.
When overriding methods, the Self-calls page can show you which
super calls to make based on other subclasses of the same type.
The Static Hooks page allows you to quickly locate all
static (hook) methods available in the selected package.
This experimental API Docs page gives you access to example code snippets for selected types.
Eclipse Code Recommenders downloads the recommendation models for the APIs you use from so-called model repositories. The Model Repositories view (available under Window > Show View > Other... > Recommenders > Model Repositories) gives you an overview of the contents of all your configured repositories. Using this view, you can also add or remove new model repositories.
The view lists the APIs the respective model repository contains recommendation models for in terms of their so-called coordinate. For each known coordinate, the model repository may contain one ore more models of different types (CALL, OVRD, OVRP, OVRM, SELFC, and SELFM) used by the different completion engines. For each type, a blue dot indicates that this type of model is available whereas a red cross indicates that the type of model is unavailable for the coordinate in question. Once a model has been downloaded, the blue dot changes to a green check mark.
Downloaded models are available even when working offline. This way, you can continue working with Code Recommenders even without an Internet connection. You can manually trigger a model download, e.g., to prepare for being offline, by right clicking on a coordinate and selecting Download models from the context menu.
CALL and SELFC models are used by the intelligent call completion engine and the Call Recommendations API Docs view. OVRD, OVRM and OVRP models are used for intelligent override completion engine and the Overrides API Docs view.
To make recommendations for the APIs you use, Eclipse Code Recommenders needs to identify them. It does so by assigning a so-called project coordinate to each of your projects’ dependencies. The Project Coordinates view (available under Window > Show View > Other... > Recommenders > Project Coordinates) shows the mapping from each dependency in your workspace to a project coordinate.
Hovering over the coordinate of an entry will give you further information on how exactly Code Recommenders made the assignment it did, i.e., which advisors suggested which project coordinate. In cases where a correct mapping cannot be found automatically, a double click on a coordinate lets you enter a coordinate manually. You may also consider enabling additional advisors or re-ordering existings ones on the Code Recommenders > Advisors preference page.