5.3.4. Axivion Dashboard Server Access

5.3.4.1. Configuration

Connection to Axivion Dashboard Server

The first step after installing the plugin is to configure access to the Axivion Dashboard Server in the Eclipse preferences. To access the settings, use Window > Preferences > Axivion Suite > Dashboard Server Settings.

|dashboard| preference page.

Axivion Dashboard Server preference page.

Here, the Axivion Dashboard Servers and users are configured. The credentials are the same as those used to access the Axivion Dashboard Server via a web browser. You can add several Axivion Dashboard Servers. However, only one dashboard is used at any given time. Use the Add Dashboard button to add another dashboard to the list of configured dashboards. The Edit button allows you to change the dashboard configuration. The up and down buttons change the order of the configurations in this list and in the dashboard dropdown list in the Issues view. The delete button removes the dashboard configuration from Axivion Eclipse Plugin.

If the Use system proxy option is enabled (default), Axivion Eclipse Plugin connects to the Axivion Dashboard Servers using the Eclipse Java runtime proxy settings. Otherwise, it connects without a proxy.

Creating and editing a Axivion Dashboard Server is done in a separate dialog. Changes made in that dialog are applied when the preferences are applied, not when the dialog is closed.

The Dashboard Name can be chosen arbitrarily and is used in the dropdown list to select the current dashboard.

The Set username to "anon_auth" button sets the username to anon_auth. When the Axivion Dashboard Server is configured with a default user (see Anonymous Authentication), this username logs in as the default user without credentials.

The currently stored credentials for the username/Dashboard URL are shown in the Dashboard editing dialog. They can be deleted there, but not entered. The Dashboard password will be requested when the plugin opens an Axivion Dashboard Server connection. If the Axivion Dashboard Server supports ApiTokens, the provided password will be used to automatically generate an ApiToken. In this case, only the ApiToken is stored; the provided password is not stored or used by the plugin after the ApiToken is retrieved. Otherwise, the password is stored only if the Store Password option in the password dialog is enabled.

If the server returns an error indicating that the credentials are incorrect, Axivion Eclipse Plugin invalidates the stored credential. This means the password dialog will appear again. This prevents further dashboard access attempts to avoid account lockout (e.g., when LDAP is used and the account is blocked after five failed login attempts).

Your settings will be stored permanently in the Eclipse preference store. The password or ApiToken is stored in the Eclipse secure preferences store. Encryption is provided by Eclipse. If you have never entered a password, depending on your platform, Eclipse may ask you for a master password to protect all stored passwords (cf. Fig. Secure storage setup in Eclipse.). If so, and if you choose to provide a password hint, Eclipse will ask two questions for which you must provide the expected answers (cf. Fig. Password hints in Eclipse.).

Secure storage setup in Eclipse.

Secure storage setup in Eclipse.

Password hints in Eclipse.

Password hints in Eclipse.

When you click the Apply button on the Axivion Eclipse Plugin preference page, your preferences are saved, and Axivion Eclipse Plugin will attempt to connect to the Axivion Dashboard Server using these settings.

However, the credential (password or ApiToken) is stored unencrypted in memory and may be written to disk during swapping or hibernation.

The credential is transmitted to the Axivion Dashboard Server. Use HTTPS to ensure it is not visible during transmission over the network.

Note

Passwords are saved in the user home directory and are therefore shared between all Eclipse instances.
In all workspaces, you should configure the same settings for:
Window - Preferences - General - Security - Secure Storage
  • tab Password - group Master password providers

  • tab Advanced

After configuring access to the Axivion Dashboard Server, you can open the Issues view via Window > Show View > Other > Axivion Suite > Issues (cf. Fig. Selection of Axivion views in Eclipse.; see also Section Issues View). You can select an analysis project using the left-most combobox in the window and view the list of issues within that project. See Section Issues View for more details on the Issues view.

Selection of Axivion views in Eclipse.

Selection of Axivion views in Eclipse.

Path Mapping

Issues found by the Axivion Suite continuous integration process reference files on the build machine where the analysis was performed. Axivion Eclipse Plugin operates on the local file system of the computer running Eclipse. Consequently, paths on the build server (hereafter analysis paths) may differ from paths on the local machine (hereafter Eclipse paths). Beyond paths, the notion of projects may also differ between the Axivion Dashboard Server and Eclipse. Each source file in your Eclipse workspace belongs to an Eclipse project. Conversely, each file in the Axivion Suite continuous integration process may be part of one or more analysis projects, which may not necessarily correspond directly to an Eclipse project. Therefore, an Eclipse project and its relative path must be mapped to an analysis project and its respective relative path, and vice versa.

Path mapping in Axivion Eclipse Plugin determines the mapping between Eclipse projects and paths and analysis projects and paths. This allows the plugin to open the corresponding local file when you double-click an issue in the Issues view. The mapping also works in the opposite direction. When opening a local file in Axivion Eclipse Plugin, the path mapping is used to determine the corresponding analysis project and file. If issue marking is enabled, issues found in the latest analysis of that file are shown in the left margin of the editor.

The path mapping configuration is stored in XML files named launcher.config in your Eclipse workspace and in the .bauhaus directory in your user profile or home directory. When a path mapping is searched, the configuration in your workspace has precedence over the global configuration in your home directory. However, you can set the default location for storing new mappings in the preferences page described below. The default location for storage is the file in your workspace. You should not manually edit the path mapping in launcher.config. Instead, allow the plugin to automatically generate the path mapping as needed. In such cases, Axivion Eclipse Plugin will ask you to select the local file in a file-open dialog. If you need to manually adjust the path mapping, open the preference page Window > Preferences > Axivion Suite > Dashboard Path Mapping to configure it. The preference page will look like the one shown in Figure Path Mapping preferences..

:guielement:`Path Mapping` preferences.

Path Mapping preferences.

Select your analysis project in the combobox and click the Add new mapping button. This will add a configuration for the selected analysis project, as illustrated in Figure Path Mapping preferences for an analysis project.. Here you can enter the analysis path relating to the build server and your corresponding local path.

The analysis path is a relative path describing a directory within the analysis project (relative to the basepath of the analysis project). Usually, this field is left empty, which means the mapping entry refers to the basepath of the analysis project.

The local path also denotes a directory and corresponds to the specified analysis path. Every issue path retrieved from the Axivion Dashboard Server that matches the analysis path is redirected to your local path. It is stored as an absolute path in your file system. Clicking the ... button next to the local-path text field opens a directory chooser, allowing you to select a directory from your local file system. Note that the selected directory should be part of an Eclipse project to display the issue markers in the editor; otherwise, Eclipse will fail to open an editor and mark the issues of a file.

:guielement:`Path Mapping` preferences for an analysis project.

Path Mapping preferences for an analysis project.

The button Restore defaults resets the values to the currently saved state in the files <home>/.bauhaus/launcher.config and <workspace>/.metadata/.plugins/
com.axivion.aclipse.plugin/launcher.config.

A more detailed configuration example can be found in the Axivion Visual Studio Plugin documentation in Section Example Configuration.

If path mapping is configured correctly, double-clicking an issue will open the editor at the corresponding source location. The next chapter provides further details.

Caution

The path must exactly match how Eclipse recognizes it. For example, using symlinks on one side and the real path on the other will prevent Eclipse and Axivion Eclipse Plugin from marking the files.
The path Eclipse uses for a project or file can be found in its properties: Properties > Resource > Location.

Activation on Startup

The plugin will be activated on Eclipse startup to show markers. This can be disabled in the Startup and Shutdown preferences.

Eclipse :guielement:`Startup and Shutdown` preferences with |aclipse|.

Eclipse Startup and Shutdown preferences with Axivion Eclipse Plugin.

Disabling startup activation for Axivion Eclipse Plugin means markers are only loaded when the plugin is activated during Eclipse runtime (e.g., by opening a view, preferences page, or properties page of Axivion Eclipse Plugin).

Once the plugin is activated, it will not be deactivated when the view or page is closed.

5.3.4.2. Using the Axivion Eclipse Plugin as Dashboard Viewer

The Axivion Eclipse Plugin offers three Eclipse views:

  • Issues, which lists the issues available for a selected analysis project;

  • Issue Properties, which provides details for the issue currently selected in the Issues view.

  • Issue Counts, which shows the number of issues in an open file.

These views can be opened through Window > Show View > Other > Axivion Suite > ... (cf. Fig. Selection of Axivion views in Eclipse.). Figure Axivion views in Eclipse. shows the three views.

Axivion views in Eclipse.

Axivion views in Eclipse.

The next sections describe these views in detail.

Issues View

The Issues view (cf. Fig. The Axivion Eclipse Plugin Issues view.) allows querying new and resolved erosion issues. The user interface is very similar to the web dashboard described in Section Issue Table and Issue Deltas and the Axivion Visual Studio Plugin.

The |aclipse| :guielement:`Issues` view.

The Axivion Eclipse Plugin Issues view.

The elements in the toolbar above the table select which issues to retrieve from the Axivion Dashboard Server. The following describes them from left to right (cf. Fig. The Axivion Eclipse Plugin Issues view.):

  1. Dashboard selection: The dashboard selection dropdown allows to quickly change between several dashboards. It is displayed only when more than one dashboard is configured.

  2. Project: Allows you to select the analysis project whose issues are viewed. The combobox lists all projects available on the server, which the current user can access.

  3. plugins_local_build Start Local Build: Starts the local build. The results are stored in
    <home>/.bauhaus/localbuild.
  4. plugins_local_dashboard View Local Build Results: Switches between the results of the dashboard (global analysis on CI server) and the results of the local build.

  5. Issue Kind: Selects which type of issue to display.

  6. State: The two controls with the arrow symbols allow you to view only added issues, only removed issues, or both. The numbers indicate the number of added/removed issues in the current query result.

  7. Start version (Version): Like the web dashboard, the issue list shows the difference between two versions. Issues that exist in the start version but not in the end version are listed as removed. Issues that exist in the end version but not in the start version are listed as added. To see all issues, pick EMPTY as start version. This special version does not contain any issues, so the list will display all issues in the chosen end version. When a new analysis is available on the Axivion Dashboard Server, the list of available versions in the plugin might not update immediately. In this case, you can right-click the toolbar at the top of the Issues view and select Refresh to force the plugin to download the current list of versions from the Axivion Dashboard Server.

    As an alternative to the menu, you can also use the refresh button in the views title bar or the keyboard shortcut F5 when the Issues View has focus to update the issue list.

    Details on how to pick a version are explained below.

  8. End version (to): The end version for which the issues are to be retrieved. In Local Build mode, the start and end version controls are replaced with a dropdown which allows to quickly select the two available versions or their difference: Reference version, Locally changed issues, and All local issues.

  9. User: Specifies the user whose issues are to be shown:

    • ANYBODY: shows all issues; that is, does not filter based on the user;

    • NOBODY: shows only those issues that are not associated with any user,

    • <user_name>: shows all erosion issues associated with the given user name.

    As a normal user, you can see only your own user name as well as those of users marked with the public flag (see Section Users).

  10. Filter: Allows one to specify a globbing pattern. Only the issues associated with a file that matches the specified globbing pattern are shown. For example, the path “src/main/io.c” can be matched by *.c as well as */io.?. If left empty, all files are considered.

  11. Named Filter: Allows applying a Named Filter which overrides the currently set filters and column sorting. Named Filter management is possible in the Web UI. If a filter or sorting is changed, the dropdown switches to the last entry in the list [modified] which denotes the “unnamed filter” - meaning that the currently applied filters and sorting are not saved as a Named Filter.

    Private Names Filters are marked with the suffix [^].

    For details on filtering, see Filtering.

  12. plugins_filter_question Show filter help: Opens a browser and shows the filter help.

  13. plugins_refresh_icon Refresh: Loads all data from server again. This is needed e.g. when a project is added to the dashboard or a new analysis ran while the plugin run.

  14. plugins_button-marker Marking: This toggle button allows you to enable/disable the markers. If marking is turned on, the open editors will be decorated with issue markers at each line where an issue occurs similarly to compiler errors and warnings.

The Axivion Eclipse Plugin will automatically start a new query when any of the above options are changed. Query results are displayed in the table below the query controls. The columns displayed (cf. Fig. The Axivion Eclipse Plugin Issues view.) depend on the selected issue type. The filter row in Figure The Axivion Eclipse Plugin Issues view. shows active filters and is explained in Section Filtering. Information for matching issues is shown in the table in Figure The Axivion Eclipse Plugin Issues view..

The current start and end versions are shown in the toolbar (the two version chooser controls in Figure The Axivion Eclipse Plugin Issues view.). To change the selected version, click the version text or the button to its right. In the resulting menu, you can select a version using the slider or the version list. The list can be filtered by a substring.

Version chooser dropdown menu.

Version chooser dropdown menu.

The start version must always be earlier than the selected end version; therefore, certain version combinations are not permitted. Invalid versions cannot be selected. The slider always represents the full version range, but selecting a version outside the allowed range will reset the slider to the nearest valid version. Only valid versions are displayed in the version list.

Caution

Issue and project data retrieved from the dashboard are not refreshed automatically. To refresh the data, click the refresh button or right-click the Issues View toolbar and select Refresh. Alternatively, press F5 while the Issues View has focus.
To refresh only the currently displayed issues, click the already selected issue kind button.

Filtering

The issue list view supports filtering individual columns.

A row below the column headers (cf. Fig. The Axivion Eclipse Plugin Issues view.) allows you to add filtering criteria for each column. If you enter multiple criteria in several columns, all these filters must match an issue’s facets.

Local filtering in the issue list.

Local filtering in the issue list.

To remove a single filtering criterion, click the red icon in the respective filtering column. To remove all filtering criteria at once, right-click the table header row and select Clear all filters from the context menu.

The filtering row can be hidden or made visible by pressing F3 when the table is selected.

Sorting

The issue list can be sorted by clicking on the column headers. A single click sorts the list by that column. To sort by multiple columns, hold alt + shift while clicking on the row headers.

Table Operations

Clicking on the column headers allows you to sort all issues according to the selected column.

Right-clicking any of the header columns in the issue tables brings up the menu shown in Figure Issue table menu., which offers the following operations:

  • Clear all filters resets all column filters entered in the filtering row.

  • Hide column hides the currently selected columns.

  • Show all columns shows all hidden columns again.

  • Select Columns opens a Column Chooser (cf. Fig. Issue table column chooser.) where columns can be selected to be hidden (listed on the left under Available Columns) or shown (listed on the right under Selected Columns); additionally, the order of the columns can be determined.

Issue table menu.

Issue table menu.

Issue table column chooser.

Issue table column chooser.

Go to Dashboard

Axivion Eclipse Plugin allows you to quickly jump to the dashboard to view an issue, view the issue table, or obtain the dashboard link of an issue to share it with a colleague.

This is done by right-clicking the desired issue. In the resulting context menu, you can select the appropriate option.

This is not possible when Local Build is activated.

Open issue in dashboard context menu.

Open issue in dashboard context menu.

Note

When using the Open table in Dashboard entry with a Named Filter selected, you will be taken to an issue table with the Named Filter expanded (i.e., the exact set of issues).

Viewing Issues

There are three different ways to open an issue. The simplest and standard way is to double-click the entry in the issue table of the Issues view. Another way is provided by the Issue Properties view and described in Section Issue Properties View. The third option is to use the Eclipse standard Problems view. This option is described in Section Code Editor: Issue Markers.

If the path mapping is configured correctly, double-clicking the issue will open the source file and jump to the line containing the issue. If the issue has multiple source locations (e.g., clones, cycles, architecture violations), the plugin will prompt you to select which source location to open.

If the path mapping is not yet configured when you double-click an issue to open an editor, you will be prompted for a file name by a file chooser (cf. Fig. File selector for files not covered by the file mapping., File chooser for files not covered by the file mapping.) that allows you to select the file in your file system. The title bar of the dialog provides detailed information about what the path mapping is looking for. If the path mapping is not configured correctly, an error message will be displayed stating that the file cannot be found.

File selector for files not covered by the file mapping.

File selector for files not covered by the file mapping.

File chooser for files not covered by the file mapping.

File chooser for files not covered by the file mapping.

Because the analyzed version of the code is not necessarily the same as the local code version, the line numbers of issues may have changed. For example, an issue that was on line 100 during the analysis may now be on line 120 if 20 lines of code were added at the beginning of the file. When opening an issue, Axivion Eclipse Plugin will download the analyzed version of the file and compute the new location of the issue using the diff between the analyzed file and the current editor contents.

Issue Properties View

The Issue Properties view shows details about the single issue currently selected in the Issues view. To open this view, select Window > Show View > Other… > Axivion Suite > Issue Properties. Figure Issue Properties view showing issue details. shows an example of the Issue Properties view. The details shown depend on the issue type.

:guielement:`Issue Properties` view showing issue details.

Issue Properties view showing issue details.

Issue Counts View

The Issue Counts view gives an overview of the number of issues in the selected file. For each issue kind, the total number of issues and the number of new issues are shown.

These counts are calculated from the markers; therefore, they are not available when marking is disabled. Furthermore, as marking does not show markers on changed lines (as these issues were likely fixed), these issues also do not contribute to the issue counts in this view.

Issue Counts view showing number of issues in a file.

Issue Counts view showing number of issues in a file.

Code Editor: Issue Markers

If the path mapping is configured correctly (and markers are enabled), opening a source code file in an Eclipse editor will display the issues found by the last analysis as markers in the left editor margin. The opened file must be part of an Eclipse project in your Eclipse workspace; otherwise, the markers will not appear. To turn marking on and off, use the plugins_button-marker Marking button in the title bar of the Issues view.

Axivion issue markers behave as normal Eclipse markers. Hovering the mouse over a marker icon in the left editor margin will open a tooltip describing all issues on that line (cf. Fig. Issues in source-code editor.).

Issues in source-code editor.

Issues in source-code editor.

Because the retrieval of markers from the Axivion Dashboard Server is expensive, markers are only fetched for files in currently visible editors.

Erosion issues are normal Eclipse markers and, hence, are also shown in the standard Eclipse view Problems. The Problems view is another way to navigate to the issues. Axivion markers will be removed from it when an editor is closed.

A common workflow is to navigate from the markers in the editor’s vertical ruler to the issue details (see Section Issue Properties View). This can be done quickly by right-clicking on the marker. In the opened context menu, select the submenu Axivion Show Issue Details, and finally click on the desired issue.

Annotations (the part of the markers visible in the editor) can be configured in Preferences > General > Editors > Text Editors > Annotations. Alternatively, right-click the overview ruler (directly to the right of the editor’s vertical scroll bar) and choose Preferences... from the context menu. The visibility of each issue kind in the vertical ruler (to the left of the line numbers) and the overview ruler can be configured individually.

Eclipse annotation preferences.

Eclipse annotation preferences.

5.3.4.3. Advanced Topics

Find the Used Java

Eclipse is Java-based software and therefore requires a Java Runtime. Eclipse can be bundled with its own Java Runtime.

The location of the JRE currently used by Eclipse can be found via: Help - About Eclipse - Installation Details - Configuration. In the System Properties section, locate the entry java.home (not to be confused with JAVA_HOME).

There are several ways to specify where Eclipse can find the JRE to run:

https://wiki.eclipse.org/FAQ_How_do_I_run_Eclipse%3F#Find_the_JVM

  • Command-line argument: eclipse -vm C:\Program Files\Java\bin

  • eclipse.ini:

    -vm
    C:\\Program Files\\Java\\bin
    
  • Folder inside the Eclipse installation directory: jre

  • Environment variable PATH: javaw.exe or java

Eclipse does not use the environment variable JAVA_HOME.

HTTPS connections

To communicate securely with the Axivion Dashboard Server, Eclipse/Java must verify the server’s identity using a trust chain of X.509 certificates. This chain requires a trusted anchor (the root certificate) to be stored in Java’s certificate store.

Java includes several root certificates. However, there are situations where the Axivion Dashboard Server uses certificates not trusted by the default Java installation (e.g., a company-internal CA or a certificate generated by the Dashboard without a CA). In such cases, the root (self-signed) certificate must be added to Java’s certificate store so that Java (and thus Eclipse) trusts the certificate.

First, locate the Java installation used by Eclipse (see Find the Used Java).

Second, obtain the root certificate for the server certificate, for example, using a browser. If the Axivion Dashboard Server automatically created a certificate, the required certificate is stored in the file <dashboard-config>\cert\auto.crt.

Note

The Dashboard’s certificate store (*.p12, *.pfx, or *.jks) is not the certificate in the required format and may not contain the necessary root certificate.

To install the root certificate, use the keytool utility, which is shipped with Java and located in the bin directory of the Java installation.

keytool -importcert -cacerts -file "<path\to\certificate>" -alias <alias-name, e.g. "CA: domain">

If the installed Java version is older and does not support -cacerts, it can be replaced by the option -keystore "<java-directory>\lib\security\cacerts".

The Java certificate store is protected by a password. The default password is changeit.

The client must verify the entire certificate chain. Therefore, it is recommended that the Axivion Dashboard Server be configured to provide the full chain (rather than only its server certificate) during the TLS handshake.

Note

If the Axivion Dashboard Server does not provide the certificate chain, the intermediate certificates must be installed into the Java certificate store in addition to the root certificate.

Note

If you encounter certificate or TLS connection problems and require support from Axivion, please include the following information in your support request e-mail:

Markers and updates

Caution

After a new analysis has been performed, you may need to refresh by pressing F5 while the Issues View has focus, or by right-clicking the toolbar.

Caution

Issue markers are only displayed for files that belong to an Eclipse project. If a file is not currently part of an Eclipse project, you must create a new project (via File > New > Project) or import an existing one (via Import and following the wizard instructions) that contains the file. You may also need to update the path mapping for the Eclipse project as described in Section Path Mapping.

Secure Storage Caveats

Eclipse secure storage is used to store passwords; therefore, Eclipse is responsible for encrypting and storing the password on disk. The Axivion Eclipse Plugin uses the API provided by Eclipse and cannot resolve issues with the secure storage itself.

Observations about the secure storage when using multiple Eclipse installations on the same machine:

  • The secure storage of 32-bit and 64-bit Eclipse installations are not compatible. On Windows, however, both architectures use the same path for the secure storage location on disk. https://bugs.eclipse.org/bugs/show_bug.cgi?id=355086 (Status: CLOSED WONTFIX)

  • Newer combinations of Eclipse and Java can support more encryption schemes than older versions.

  • During each Eclipse session, the secure storage is loaded from disk only once. Subsequent accesses are served from an in-memory cache. Additionally, secure storage is rarely written to disk (only at Eclipse shutdown). To mitigate this, Axivion Eclipse Plugin calls the secure storage flush API after each change.

To mitigate interference between multiple Eclipse installations regarding the secure storage, each installation can be configured to use its own storage location on disk. This is achieved using the argument -eclipse.keyring <file path>, which can be passed via the command line or specified in the eclipse.ini file.