Sonatype for Eclipse
The Eclipse IDE is an open-sourced software application for software development managed by the Eclipse Foundation. It's used for development in many ecosystems and is the most widely used IDE for Java development.
The Sonatype for Eclipse integration is available on the Eclipse Marketplace.
Note
Maven-based Java projects are fully supported.
Gradle-based Java projects are supported with limited functionality. "Migrate to Selected" and "Locate Declarations" features are not available for Gradle-based projects.
Installing the Integration
Check the integration requirements for Eclipse before starting the installation process.
Sonatype IQ for Eclipse can be installed by adding a new software repository.
Navigate to the Help menu and select Install New Software.
Press the Add button in the Install dialog and create a new repository with the following information:
Name: Enter a name of your choice.
Location: Set to URL for the Sonatype IQ for Eclipse repository:
https://download.sonatype.com/clm/eclipse/releases/
Note
This URL is specifically designed to function within Eclipse and is not intended to be directly accessible through a web browser.
Click OK. A list of available releases is downloaded and an entry for the latest version of Sonatype IQ for Eclipse is displayed.
Tip
Uncheck the item Show only the latest versions of available software, if you need to install an older release.
Select the version of Sonatype IQ for Eclipse you would like to install and press Next>, proceed through accepting the end user license agreement and restart Eclipse to complete the installation.
Configuring the Integration
After the successful installation of Sonatype IQ for Eclipse, you will be able to choose to show the Sonatype IQ for Eclipse view. To access this view:
Choose the Window menu and select Other in the Show View submenu.
Locate the Sonatype IQ for Eclipse section with Component Info:
Select it and press Open and the view will appear in your IDE.
Tip
By typing "Compo" in the filter input, Component Info is automatically highlighted.
Once the view is displayed, a warning appears. This is because you need to point Eclipse at your IQ Server:
Press the Configure button
in the top right-hand side of the component view.Once in Sonatype IQ for Eclipse Configuration area, there are a number of parameters you will need to complete before you can review data from IQ Server:
Sonatype IQ Server URL: The Sonatype IQ Server URL input field has to be configured with the URL of your IQ server.
PKI Authentication: Select this option to delegate authentication to the JVM.
User Authentication: Select this option to enter the username and password your system administrator has assigned you.
Persist credentials in Eclipse secure storage: This option allows you to store your credentials in the Eclipse secure storage vault. Select this option to skip entering your credentials during subsequent restarts.
Warning
OS X users: If you are unable to log in using the Persist credentials option, deselect the checkbox and restart Eclipse. The secure storage bug reported by Eclipse (see bug details) could be preventing you from using this feature.
Application Name: The Application Name is the application that has been configured in the Sonatype IQ Server for you. This should match the common name you associate with the application. If you don’t see a name you recognize, contact your Sonatype IQ Server Administrator.
Note
The drop-down will display a list of all available applications after pressing the Refresh button.
Additional Maven Scopes: The compile and runtime scopes will always be considered. Additional scopes (provided, test, and system) you would like to include can also be selected.
Assigned vs. Unassigned Content: After selecting an application name that represents a collection of policies configured in your Sonatype IQ Server, you can determine the Eclipse projects that should be analyzed. The list on the left titled Unassigned content contains all projects in your current Eclipse workspace that have not been assigned to an Sonatype IQ Server Application. Select a project from that list and add it to the Assigned content list on the right by clicking the Add button. This will add the project to the component analysis via the Sonatype IQ Server. In order to perform an analysis, the project needs to be open. To select multiple projects use the Shift and Control keys, and then click the Add button. The Add All, Remove and Remove All buttons help you to control the projects to analyze for different analysis sessions.
Note
Projects can, at most, be assigned to a single application.
With a finished selection of the projects you want to analyze, press the Finish button and wait for the component list to be displayed in the view.
Tip
Only open projects will be taken into account as part of the component analysis.
Using the Component Info View
Once the integration has been configured and the component analysis is completed, a component view will look similar to the examples shown below. The list of components will reflect an analysis of the build path.
If a Golden Version of the component is available, the suggestion will be marked with a star icon:
If there is no Golden Version available, but other remediations exist, they will be shown as Available Fix Version(s):
Note
For Maven projects we include the compile and runtime scopes in the component evaluation. If you wish to include additional dependencies found in provided, test, and system scope, these can be configured.
The top left-hand corner of the Sonatype IQ for Eclipse Component Info view displays either the number of projects currently being examined in the view, or the name of the specific project. Next to that, the number of components found, and the number of components shown in the list is displayed.
The top right-hand corner provides a number of buttons to access the following features of Sonatype IQ for Eclipse:
Icon | Name | Description | |
|---|---|---|---|
| Open Component Details | Opens another window with more details about the selected component including policy violations, license analysis and security issues. | |
| Open POM | Opens the Maven pom.xml file of the selected component from the list in the Maven POM Editor. | |
| Locate Declarations | Starts a search that displays all usages of a selected component in the projects currently examined. This feature is only available for Maven projects. | |
| Filter | Brings up the filter selection, that lets you narrow down the number of components visible in the view. | |
| Configure | Activates the configuration dialog for the component analysis. | |
| Refresh | Refreshes the component list and analysis results. | |
| Show information about the plugin | Displays the Sonatype IQ for Eclipse support pages in an external browser. | |
| Minimize | Minimize the view. | |
| Maximize | Maximize the view. |
The left-hand side of the view contains the list of components found in the project and identified by their artifact identifier and version number. A color indicator beside the components signals potential policy violations. The right-hand side of the view displays the details of the selected component from the list on the left.
Tip
You may notice some components are black or gray. This indicates components you have included (black) in your application, versus components that are included via a transitive dependency (gray).
By clicking on the list header on the left, the list can be ordered by the threat level of the policy a component has violated. In cases where there is no violation, the threat is simply light blue.
When you select a specific component in the list, the details, various properties, and a visualization of the different versions is displayed to the right of the list.
Tip
Depending on your screen size, the visual display may be shown below the component list. Try adjusting your screen size, or adjusting the panel.
Filtering the Component List
The list of components found in the analysis and displayed in the component info view can be configured by pressing the Filter button 
. The filter dialog, displayed below, allows you to narrow down the components shown.
 |
The Scope setting determines which projects' components are displayed in the list:
Field | Description |
|---|---|
All open projects | include all the components, from all open projects. |
Current selection project(s) | include the components from the project currently selected in the package explorer. |
Current selection working set(s) | include the components from all the projects in the working set currently selected in the package explorer. |
Project | include the components from the project selected in the drop-down. |
Working Set | include the components from all the projects in the working set selected in the drop-down. |
Searching for Component Usages
Once you have selected a specific component in the list on the left of the component info view, Sonatype IQ Server can determine in which projects the component is used. After pressing the Locate Declarations button 
, and once the search has been completed, you will see the results in a tree view of projects and project pom.xml files, all displayed in the Search window.
Inspecting this list can help you assess the impact of a potential upgrade to a new component version. Looking at the found projects, you can potentially remove wrong declarations, determine side effects from transitive dependencies, or find out why this component shows up as a dependency at all.
Note
Locate Declarations is only available for Maven-based Java projects.
Inspecting Component Details
Press the Open Component Details button 
to access the details about policy violations, license analysis and security issues for a specific component selected in the list. An example details view is shown below:
 |
The Policy Violations section in the top contains a list of all the policies that have been violated by the component.
The License Analysis section contains the threat levels posed by the licenses declared for each component, as well as those that have been observed in the source code.
The Security Issues section below contains the list of issues found. They are sorted from higher to lower risk, with each issue detailed by a threat level ranging from 0 to 10, or potentially with the value unscored and a descriptive text in the Summary column. In addition, links to the security vulnerability database entry are added as links in the Problem Code column.
Migrating to Different Component Versions
Note
Migrate to Selected is only available for Maven-based Java projects.
If you determine that a component upgrade is required to avoid a security or license issue or a policy violation, after reviewing your component usage, Sonatype IQ for Eclipse can be used to assist you in the necessary refactoring.
The first step to start the migration is to select a newer version for the component in the visualization chart, or by selecting the recommended version. An example is displayed in the image below:
Once you have selected a different version than the one currently used, the Migrate to Selected button will become active. Pressing the button opens a dialog that assists you in the migration to the newer component. The complexity of this task varies considerably from project setup to project setup. The migration wizard is able to detect circumstances such as the component being a transitive dependency or versions managed in a property.
The simplest flow is when a dependency version can be applied and the result is a single dialog like the one displayed below.
 |
If the version is managed in a property, the initial screen in the following example allows you to select if you want to continue with a property upgrade, or perform a replacing version upgrade.
 |
Once you have selected to perform a property upgrade, you will be able to apply it in the next screen, as shown below:
 |
The Refactoring screen features navigation tools allowing you to view all potential changes in the dialog, and step through them one-by-one before deciding to continue.
After you have completed the refactoring of your project files, you should perform a full build, as well as a thorough test, to determine that you can proceed with the new version in your development.
Typically, smaller version changes will have a higher chance of working without any major refactorings, or adaptations, of your code base and projects, while larger version changes potentially give you more new features or bug fixes.
Your release cycle, customer demands, production issues, and other influencing factors will determine your version upgrade choices. You might decide a multi-step approach, where you do a small version upgrade immediately to resolve current issues and then work on the larger upgrade subsequently to get the benefits of using a newer version. Or, you might be okay with doing an upgrade to the latest available version straight away. Potentially, a combination of approaches in different branches of your source code management system is used to figure out the best way of going forward with the upgrade.
Sonatype IQ for Eclipse and other tools of the IQ Server suite can assist you through the process of upgrading, as well as monitoring, the applications after upgrade completion.