Sierra User Guide

How to use and configure the Sierra Eclipse client

SureLogic's Sierra offering is Eclipse Ready™ (www.eclipse.org). This offering can be installed and used with other Eclipse-based offerings.

The authors and publishers have taken care in the preparation of this documentation, but make no expressed or implied warranty of any kind and assume no responsibility for errors and omissions. No liability is assumed for incidental or consequential damages in connection with or arising out of the use of the information or programs herein.

Version 5.7.1—November 2015


Table of Contents

Preface
1. Audience
2. Contact information
1. Getting started
1.1. Introduction
1.2. Concepts
1.3. Quick start
1.3.1. Installing Sierra
1.3.2. Installing your license
1.3.3. How to scan your code examine the results
1.4. Tutorials
1.4.1. Using the Sierra Eclipse client
1.4.2. Interacting with a Sierra team server
1.4.3. Scanning code using Ant
2. Reference
2.1. The Sierra menu
2.2. The Code Review perspective
2.2.1. Switching to the Perspective
2.2.2. The Scanned Projects view
2.2.3. The Sierra Quick Search view
2.2.4. The Findings view
2.2.5. The Finding Details view
2.2.6. The Team Servers view
2.2.7. The Synchronize History view
2.2.8. The Synchronize History Details view
2.3. Preferences
2.3.1. Sierra
2.3.2. Local Team Server
2.3.3. Scan Filter
2.3.4. Server Interaction
2.4. SureLogic tool properties file
2.5. License management
2.6. Bugs and tips
2.7. Using Ant
2.7.1. sierra-scan task
2.8. Using Maven
3. Release notes
3.1. Sierra version 5.6.1
3.1.1. New and Noteworthy
3.2. Sierra version 5.6.0
3.2.1. New and noteworthy

List of Figures

1.1. Selecting Sierra features to install in your Eclipse
1.2. The menu option to install a license for Sierra
1.3. The SureLogic license management dialog
1.4. The menu option to scan your projects
1.5. Menu item to install tutorial projects into your workspace
1.6. Adding the ShowOff and SmallWorld tutorial projects to your workspace
1.7. The Sierra code review perspective examines findings about the ShowOff project
1.8. Examining the one high importance finding for the ShowOff project
1.9. Three audits have been performed on this finding
1.10. Two tool artifacts have been combined to create this finding
1.11. Status bar graph after fixing two findings in the code
1.12. Removing the ShowOff project from the Sierra findings database
1.13. Running the SmallWorld game
1.14. The Local Team Server view
1.15. The Local Team Server view showing the server logs
1.16. Preference panel for controlling the memory used by the local team server
1.17. Warning you that the local team server does not exit when Eclipse exits
1.18. The team server web portal and the Local Team Server view indicating that the team server is running
1.19. Naming the team server upon first portal login
1.20. The welcome page on the team server portal
1.21. The users page on the team server portal showing two enabled users
1.22. The settings page on the team server portal sending a test notification email
1.23. Defining the connection to the local team server within the Eclipse client
1.24. The completed Tutorial scan filter
1.25. The Tutorial scan filter is assigned to the SmallWorld project
1.26. After a Synchronize All the client knows that the Tutorial scan filter is assigned to the SmallWorld project
1.27. The welcome page after the scan of SmallWorld has been published
1.28. Findings by category for the SmallWorld scan
1.29. The portal shows the audits attributed to the zork user
1.30. After a sync local audits are attributed to the troll user
1.31. The portal shows the audits attributed to the zork and troll users
1.32. Console output from scanning SmallWorld with Ant inside Eclipse
1.33. Successful scan import
2.1. The Sierra menu
2.2. Dialog allowing the user to select which Java projects to scan
2.3. The Import Sierra Ant/Maven Scan dialog box
2.4. The Save Documentation dialog box
2.5. The Scanned Projects view
2.6. The Scanned Projects view menu
2.7. The Scanned Projects context menu
2.8. The Sierra Quick Search view
2.9. The saved searches toolbar at the bottom of the view
2.10. The Scanned Projects view menu
2.11. The Scanned Projects context menu
2.12. The Findings view
2.13. The Findings context menu
2.14. The Finding Details view Synopsis tab
2.15. The Finding Details view Audit tab
2.16. The Finding Details view Artifact tab
2.17. The Team Servers view organized by team server
2.18. The Team Servers view menu
2.19. The Team Servers view organized by project
2.20. The Team Servers context menu
2.21. The Synchronize History view
2.22. The Synchronize History view menu
2.23. The Synchronize History Details view
2.24. The Sierra preference pane
2.25. The Local Team Server preference pane
2.26. The Scan Filter preference pane
2.27. The Server Interaction preference pane
2.28. Use of the surelogic-tools.properties to exclude the test source folder of the timingframework-core project
2.29. Use of the surelogic-tools.properties to exclude packages from the timingframework-swing project
2.30. The SureLogic license management dialog
2.31. Dialog warning that the installed Sierra license is about to expire
2.32. Menu items to send bugs and tips to SureLogic
2.33. Dialog allowing the user to enter a tip to improve Sierra
2.34. Dialog allowing the user to enter a problem report about Sierra
2.35. Eclipse preferences for network connections within the IDE

Preface

1. Audience

This document is intended for Java developers who want to use the Sierra tool within the Eclipse Java IDE. We assume that the reader understands both the Java programming language and the use of Eclipse for Java development.

2. Contact information

For technical support or other questions, please contact:

5808 Forbes Avenue, Pittsburgh, PA 15217-1602

Chapter 1. Getting started

1.1. Introduction

What is Sierra? Sierra is a rule-based static analysis toolkit supporting team collaboration. It integrates widely used open source tools, such as FindBugs and PMD, into a single team-oriented tool.

Why should you use Sierra? Sierra helps you quickly uncover potential problems in your Java code. It uses static analysis to examine your code, without having to run it, and report any potential problems it uncovers to you for action. Sierra deeply integrates well tested static analysis tools, such as FindBugs and PMD, into the Eclipse environment.

Why not just use FindBugs (or PMD)? Sierra has the following advantages over just using an analysis tool directly:

  1. Persistence: Sierra remembers what findings you have audited across scans of your code. This is very helpful to avoid wasting your time examining the same findings over and over again.

  2. Multi-Tool: Sierra integrates several analysis tools into one framework. This allows you to take advantage of the best tools, without the trouble of getting them all installed and properly configured to work on your software.

  3. Eclipse: Sierra deeply integrates rule-based static analysis into Eclipse. It provides a cutting-edge Eclipse user interface designed for busy programmers.

  4. Team-Oriented: Sierra has an optional team server capability that allows you and your development team to share your analysis tool settings (so everyone scans using the same settings) and finding audit trails. The team server also support a web interface to examine metrics about your source code over time.

The next section introduces concepts and definitions that are important to understand when using Sierra. The section after that gets you started quick with the Sierra tool by describing how to install Sierra, install your license, and scan your code. If you have used FindBugs or PMD and want to get going on your own code this is your quickest route. The final section of this chapter contain a series of tutorials that describe how to use the Sierra on example Java projects.

1.2. Concepts

This section introduces concepts and definitions that are important to understand about Sierra.

When Sierra examines your code, this is called a scan. By default, a Sierra scan runs two analysis tools: FindBugs and PMD.

The output of a scan is a scan document. A scan document is an XML file that contains all the issues reported by the various analysis tools. The scan document is unfiltered and may contain hundreds of thousands of tool-reported issues. Scan documents are stored in your Sierra data directory. This directory, by default, is in your workspace under .sierra-data. (This is sometimes useful to know because you can clear out all scan data and "reset" Sierra by deleting this entire directory)

The results reported by analysis tools during a scan are called artifacts by Sierra. Sierra aggregates these results to produce findings, each of which is made up of one or more artifacts. The reason for this distinction between an artifact and a finding is two-fold: to merge the "same" artifact reported by two different tools and to track a particular code issue over time (i.e., across multiple scans). Two analysis tools may report artifacts that are essentially the same issue. For example, the line of Java code shown below would generate an artifact from both the FindBugs and PMD analysis tools that explicit construction of string objects is inefficient.

String hi = new String("hi");

It would be annoying for the user to deal with two reports for this issue, so Sierra maps similar artifacts from different analysis tools into one finding.

The second distinction between an artifact and a finding involves tracking the same code issue across multiple scans. An artifact is tied to one particular scan. A finding can exist across multiple scans. Sierra uses a matching heuristic to try and "attach" an artifact reported by a new scan to an existing finding. A new finding is only created if no match can be found. This is desirable because it allows the user to understand change, or the lack of change, in code over time with respect to the issues reported by Sierra.

Sierra distinguishes between artifacts and artifact types as well as between findings and finding types. An artifact type is often called a rule by analysis tools. Each analysis tool included in Sierra reports artifacts based upon the set of artifact types (or rules) that they contain. For example, one artifact type included in FindBugs and PMD is explicit construction of string objects is inefficient. Each artifact reported by a scan has one and only one artifact type.

A finding type is similar to an artifact type, but it describes a type of finding rather than a type of artifact. For example, Sierra contains a finding type that explicit construction of string objects is inefficient. This finding type is established by two artifact types: one from FindBugs and one from PMD. There must be an artifact type that establishes a finding type. To state this another way, there is no point to having a finding type that is not reported by an analysis tool. Each finding has one and only one finding type. Users of Sierra typically deal with finding types and rarely need to be aware of artifact types.

Sierra groups findings into categories. A category is defined by a set of finding types. Sierra groups scan findings into categories by examining the finding type of each finding and placing it into the correct categories. Categories are not required to be a partition of the set of finding categories, i.e., a finding type can be used to define two or more categories or no categories. Sierra users can create and modify categories on a Sierra team server. The team server allows categories to be defined in terms of other categories as well as by finding types. User created categories can be shared with both Eclipse users and other Sierra team servers. Sierra contains a large number of defined "stock" categories.

Armed with an understanding of what Sierra defines an artifact, a finding, and a category to be, we now return to what happens during a scan with the purpose introducing the concept of a scan filter. When a scan is performed several steps occur within Sierra. First the analysis tools are run. These tools produce a scan document. Next this scan document is loaded into a database. While the scan document is loaded, findings are matched and created and a scan filter is applied. A scan filter is the mechanism to control what finding types are deemed important to report to the user. The scan filter also controls at what level of importance each finding is reported. A scan filter is therefore a set of categories and/or finding types with an importance level. When the scan filter is applied as the scan document is loaded into the database it filters out all finding types that are not included by the scan filter. Sierra allows users to create and modify scan filters on a Sierra team server. Scan filters can be shared with both Eclipse clients and other Sierra team servers. The Sierra Eclipse client has one special scan filter, called the local scan filter, that can be edited within Eclipse. This scan filter is required if the client is not connected to a Sierra team server, e.g., stand-alone use of the Sierra Eclipse client.

Client scan model: The Sierra Eclipse client stores two scans of each project: the most recent, or current, scan and the previous scan. This model allows the client to "diff" the two scans and report to the user what has changed. In the Sierra Eclipse client, Java projects may be connected to one and only one Sierra team server. When a Java project is connected to a team server, it is possible to publish scans to that team server from Eclipse. The scan filter used for a scan run from the Sierra Eclipse client depends upon if the Java project scanned is connected to a team server or not. If the project is connected to a team server, then the scan filter defined by that team server is used. If the project is not connected to a team server, then the local scan filter is used.

Team server scan model: The Sierra team server stores all uploaded scans. Scans can be uploaded from Eclipse clients or from Ant scripts. The team server allows a particular scan filter to be assigned to each Java project. A default scan filter is set for the team server and is used for any Java project that does not have an explicit scan filter set for it.

When a scan is uploaded to a team server from Eclipse or Ant, it is the scan document that is sent to the team server (not the filtered in-database version of the scan). Thus, the scan filter on the team server is applied to the uploaded scan document as it it loaded into the team server's database. This means, in some cases, that a different scan filter can be applied on the client than on the team server. For example, if an unconnected project is scanned on an Eclipse client then the local scan filter of that client is applied to that scan. If that project is subsequently connected to a team server and the scan is published (i.e., uploaded) from the client to that team server then the default scan filter for that team server is applied to the scan. In this example, two different scan filters where applied and they may not be the same. This issue can be a source of confusion, but, as described below, Sierra tries to minimize this confusion by using the server scan filter for client scans of all projects that are connected to a team server.

When a client connects a Java project to a team server, category and scan filter information is transferred down to the client. This transfer allows the connected Java project on the client to use the same scan filter it would use on the team server. This helps to keep the scan filter consistent on client connected to a team server. To keep scan results consistent it is recommend that a new scan be run after each project is connected to a team server from an Eclipse client.

Why do the client and server use different scan models? This is primarily due to the different roles they serve in the overall Sierra system. The client is intended for deep investigation of current scan findings. Users of the client are engaged in auditing findings and fixing them in their source code. There is little purpose for saving dozens of scans on the client and doing this could take up significant disk space on that client user's desktop computer. The server is intended to support team collaboration and reporting. The server needs to be able to produce longitudinal reports and therefore needs to save the results of a large number of scans.

BugLink vs. ScanLink data: A Sierra team server holds two different kinds of data: BugLink and ScanLink. BugLink data includes artifact definitions, finding type definitions, category definitions, and scan filters. ScanLink data includes scan data (findings and artifacts), audit data, code metrics data, and any other analysis results about code. Why this distinction between types of data? Because Sierra supports multiple team servers across an organization. BugLink data can be transferred between team servers and ScanLink data can't (ScanLink data is transferred between clients and a team server). Team servers can share category and scan filter definitions, but they can't share scans and audits.

All Sierra team servers hold BugLink data, but only some hold ScanLink data. This allows some team servers to be purposed as a repository for category and scan filter information within an organization without hosting the scan and audit data for any projects.

1.3. Quick start

This section will quickly get you started with Sierra. It describes how to install Sierra into your Eclipse, how to install a license file that allows you to use Sierra, and how to scan your code and examine the results.

1.3.1. Installing Sierra

Sierra installs as a feature in your Eclipse IDE. It is installed (and uninstalled) via the normal Eclipse mechanisms from an archived update site that you obtain from SureLogic.

  1. Download Sierra: Download an archived update site file that contains the Sierra feature. Contact SureLogic about how to obtain this file, however the download is typically hosted here. Please note that Java 8 support you need Eclipse Luna (4.4) or above as your Eclipse.

  2. Install Sierra In Your Eclipse: Select Help | Install New Software... to open the Install dialog. Click the Add... button. In the Add Site dialog that opens select the Archive... button and point to the Sierra archive file. Press Open and then OK. The Install dialog should appear as shown in Figure 1.1.

    Figure 1.1. Selecting Sierra features to install in your Eclipse

    Selecting Sierra features to install in your Eclipse

    Select the Sierra Eclipse Client. To try out the local team server, which is used in the tutorials, select the Sierra Local Team Server feature. Press Next and step through the wizard. Click Finish on the last screen after accepting the license agreement. You may be prompted to restart Eclipse when the installation is completed.

1.3.2. Installing your license

This section assumes that you have installed Sierra. If you see a Sierra menu item on your Eclipse main menu then you can assume Sierra has been installed properly.

You need to install a license to use Sierra. If you do not have a license file that was sent to you by SureLogic visit http://surelogic.com to obtain one. To install the license select Manage SureLogic Licenses from the Sierra menu as shown in Figure 1.2.

Figure 1.2. The menu option to install a license for Sierra

The menu option to install a license for Sierra

This will cause the Manage SureLogic Licenses dialog to appear as shown in Figure 1.3. Select either Install from File or Install from Clipboard to install your license file.

Figure 1.3. The SureLogic license management dialog

The SureLogic license management dialog

Sierra will not disrupt your Eclipse installation if a license for it is not installed, however, it will not allow you to use Sierra functionality (e.g., performing project scans). We will assume from this point on that you have installed your license. For more information see Section 2.5.

1.3.3. How to scan your code examine the results

For the impatient, this section provides a "bare-bones" description of how to scan code with Sierra and examine the results that it reports.

From the Sierra main menu select the Scan command as shown in Figure 1.4. (If this is the first time Sierra has been loaded into your Eclipse it might take a few seconds to a minute for it to initialize, please be patient.)

Figure 1.4. The menu option to scan your projects

The menu option to scan your projects

A dialog will open showing you the set of available Java projects that you can scan. Check the projects you want to scan or press the Select All button to check them all and then press the OK button to start the scan. Equivalently, you could right-click a selected set of open Java projects in the Package Explorer and from the Sierra menu select the Scan Project menu item.

You will receive notification via a balloon that the scan has been started and will run in the background. As the scan on each project completes another balloon will notify you.

After one or more scans have completed running, you can change to the Code Review perspective to examine the results. To do this, select the Open Code Review Perspective menu item from the Sierra menu. The Eclipse layout will change to show views which will help you to examine the findings the scan reported.

By default all findings are shown (up to a cutoff limit of 500, by default, which you may change). However, the Sierra Quick Search view allows you to select what findings are of interest to you. For example, if you select Project you will see your results partitioned by project. The Results view shows the list of findings you have filtered down to. Selecting a results in the Results view shows details about that individual result in the Finding Details view.

Small orange icons appear in the Java editor gutter to highlight tool findings. By default, these gutter icons only appear for findings deemed of high or critical importance. The more important the tool believes the finding to be the darker orange the icon will be. When these editor gutter marks are displayed, in particular for what importance values, can be configured in the Sierra preferences as described in Section 2.3.

If you click on a finding in the Results view or in the Java editor that finding will be shown in the Finding Details view. This view allows you to read about the finding and interact with the finding. One change that can be made is to the importance of the finding.

This section is a quick overview of how to scan your code and examine findings about your code. The next section contains a series of tutorials that describe how to use Sierra in much more detail.

1.4. Tutorials

This section contains a series of Sierra tutorials, please read through Section 1.2 before you attempt these tutorials. It is recommended that you go through these tutorials in order. It is also recommended that these tutorials be performed "hands-on" at your computer. You might want to create a new Eclipse workspace to use for these tutorials. In addition, if you run into any difficulties as you step through the tutorials please consider sending us a tip for improvement as described in Section 2.6.

1.4.1. Using the Sierra Eclipse client

This tutorial assumes that you have installed Sierra. If you see a Sierra menu item on your Eclipse main menu than you can assume it has been installed properly.

Figure 1.5. Menu item to install tutorial projects into your workspace

Menu item to install tutorial projects into your workspace

To start off, we'll run Sierra on a project called ShowOff. Select SierraInstall Tutorial Projects from the workspace menu and add all projects to your workspace as shown in Figure 1.5 and Figure 1.6.

Figure 1.6. Adding the ShowOff and SmallWorld tutorial projects to your workspace

Adding the ShowOff and SmallWorld tutorial projects to your workspace

The SierraTutorial_ShowOff project contains a single class in ShowOff.java with the Java code listed below.


public class ShowOff {

    /**
     * A simple main program to demonstrate the {@link #box(Object)} method.
     * 
     * @param args
     *            unused.
     */
    public static void main(String[] args) {
        box(new String("hello"));
        box(null);
    }

    /**
     * Prints the passed object to {@link System#out} with a text box around it.
     * 
     * @param o
     *            the object to show, may be <code>null</code>.
     */
    public static void box(Object o) {
        /*
         * If the object is null then we want to show null.
         */
        if (o == null) {
            System.out.println("null");
        }
        /*
         * Let's do a fancy "box" output for our object.
         */
        StringBuffer b = new StringBuffer(o.toString());
        b.append(" --");
        b.insert(0, "-- ");
        StringBuffer line = new StringBuffer();
        for (int i = 0; i < b.length(); i++)
            line.append("-");
        System.out.println(line.toString());
        System.out.println(b.toString());
        System.out.println(line.toString());
    }
}
	

Double check that the project compiles successfully, it should. (If not, fix any problems before you continue.)

Now run a Sierra scan on the code. To do this choose the Scan Project menu item from the Sierra menu item in the Eclipse main menu. Alternatively, you can right-click on the SierraTutorial_ShowOff project (not the Java file) in the Package Explorer and from the Sierra menu (likely way down toward the bottom) select the Scan Project menu item. Either way a Scan Project dialog should appear as shown below.

When the dialog appears check the SierraTutorial_ShowOff project and press the OK button. If this is the first time Sierra has been loaded into your Eclipse it might take a few seconds to a minute for it to initialize, please be patient.

After the scan is completed you will be prompted to change to the Code Review perspective.

You want to do this so click Yes. You can also open this perspective by selecting the Open Code Review Perspective menu item from the Sierra menu. The Eclipse layout will change to show views which will help you examine the findings the scan reported.

Figure 1.7. The Sierra code review perspective examines findings about the ShowOff project

The Sierra code review perspective examines findings about the ShowOff project

All the findings in your local database are shown when, as in the screenshot above, the filter is off. These are listed in the Findings view at the bottom-left. The view cuts off at 500 findings, but this preference can be changed. You can tell that all the findings are displayed because the text at the bottom of the list states 5 Findings. If the cutoff were in use then the text would state the list is limited to 500 by displaying Showing 500 of all possible findings. Further, this text would be underlined to indicate that it hyperlinks to the preference page for Sierra. Thus, you can increase the cutoff value if you wish.

The Sierra Quick Search view at the top of the perspective allows you to "drill-into" findings along several dimensions. It is a powerful control but is straightforward to use. For this tutorial, first click on Importance then check High. Notice that these actions change the list of findings displayed in the Results view. At this point, one findings should be listed. Select the finding shown in the Results view. Selecting this finding will bring up its information in the Finding Details view. In addition, the Java editor will highlight the offending line of code. Your screen should now look like Figure 1.8. If you get more than one finding, you probably have scanned other projects. (To delete the data from these projects see Section 2.2.2.)

Figure 1.8. Examining the one high importance finding for the ShowOff project

Examining the one high importance finding for the ShowOff project

Read the description in the Finding Details view Synopsis tab. In addition, you can click the line references in the Location portion of the tab to examine the lines of code referenced by this finding to help you understand why the tool reported it. This high importance finding is about a possible null dereference, and these lines represent code that would be executed before the null dereference. It was noticed because the box method checks if o is null but then later, regardless of the outcome of this check, dereferences it. This is clearly a problem, and if you run the code the second call from the main method indeed causes a failure in the program: the call prints null and then throws a NullPointerException to the console.

To fix this problem add a return statement after line 25 as shown below:


if (o == null) {
    System.out.println("null");
    return;
}
	

(To show line numbers in the Eclipse editor you right-click in the left-hand margin of the editor and check Show Line Numbers.)

Now save your change and scan the project again. You can start a re-scan using the Sierra main menu or by pressing the on the toolbar in the Scanned Projects view (upper-left view). The finding seems to disappear, however, the tool knows it has been fixed.

In the Sierra Quick Search clear your current search by pressing the icon in the far upper-right of the view. This clears the filter and lets all the findings through to the Results view.

You can also clear just a particular filter (and all the subsequent filters to its right) by using the in the upper-right of the filter selection box.

In this case you can use either approach because there is only one filter. Next, select Status and check Fixed to see the finding you just fixed appear back in the Results view. Sierra works hard to remember findings across scans. It does this by matching findings reported in each scan (The matching heuristic used by the tool is not perfect but will work most of the time, however, aggressive code changes might throw it off).

In the Sierra Quick Search clear your current search again by pressing the icon in the upper-right of the view (or instead of clearing the query just select Importance in the far left pane of the view which will change the current query). Select Importance and then right click on the bar chart and select Select All from the context menu. This is a quick way to select all the items listed. Select Audited and check the two items listed (Yes and No) to see all the findings from the most recent scan in the Results view.

Select the first finding shown. It warns that all classes and interfaces should belong to a named package. It is possible that a different finding is first in your list of findings if you have changed the sort order for the Findings view, if this is the case then make sure to pick the finding that says All classes and interfaces should belong to a named package rather than just picking the first finding. This is not a finding we care about for this project so we can audit it. Right-click on the finding in the Results view and via the Set Importance context menu select Irrelevant to change the importance of the finding.

This action, which we call auditing the finding, causes several things to occur. First, if you examine the counts bar chart for Audited you will note that one finding has now been audited and the others have not. If you uncheck and then check No (a checkbox under the Audited filter) you can see the other two findings in the list go away and then return. Second, in the Finding Details view the audit tab shows one audit.

Click on the audit tab (the middle tab) in the Finding Details view. The change of the finding's importance has been time-stamped and logged. Let's note that we want to use the default package using another audit. Type "The default package is OK for ShowOff." and press the Add button.

Now the finding has two audits and both are time-stamped. If you were using a Sierra team server then audits by your team would appear in this audit list as well as audits made by you. When an audit is synchronized with a Sierra team server, the name of who made the audit changes from Local to the name for that user on the team server. A team server helps your team collaborate on finding audits, however, collaboration is not the focus of this tutorial so we will continue without connecting to a Sierra team server.

We probably do not want to see findings that we have marked as Irrelevant in our list of results. So in the Sierra Quick Search click the underlined Importance "breadcrumb" (one of the underlined words at the top of the view) to scroll the view over to the importance selections.

The breadcrumbs allow easy scrolling of the view to areas that might be off the screen. Uncheck Irrelevant and then examine the state of the Results view. The one irrelevant finding is now filtered out of the set of findings shown.

Let's examine the three remaining findings. Click the first one in the Results view, All methods are static. Consider using a utility class instead, to bring it up in the Finding Details view and highlight the issue in the Java editor. This finding notes that the class may follow the utility design pattern and you should consider creating a private constructor to avoid the creation of any objects of this type. We are not concerned with this finding so audit it to be Irrelevant.

Again, select the first finding in the Results view, Avoid appending characters as strings in StringBuffer.append. This finding notes that you could append a character rather than a string. This change would result in a slight performance improvement in our code. To fix it change line.append("-") to line.append('-'). Next we want to indicate our work in the audit trail for this finding.

Figure 1.9. Three audits have been performed on this finding

Three audits have been performed on this finding

In the Finding Details view open the audit tab and click on the large stamp image in the upper-left. This creates an audit entry that states, "I examined this finding." and is a quick way to note that you examined this finding. Since we want to note that we have edited the code, type "I fixed this in the code." and then press the Add button to add a second audit.

Before we leave this finding let's set its importance to Low. In this small program such a minor performance improvement is likely not a big deal. We could just change the radio button at the left, but let's use the drop down in the upper-left of the view. Press the drop down and change the importance. Notice that this changes the views to reflect the new importance and adds a third audit entry to reflect that you made this change. The state of this finding can be seen in Figure 1.9.

Now let's examine the last finding by selecting it in the Results view, ShowOff.main(String[]) invokes inefficient new String(String) constructor. The finding should be at the bottom of the list. This finding is complaining about our use of new String("hello") in the code at line 10. Explicit use of string construction is considered bad practice in Java as it can force the Java virtual machine to make extra copies of strings.

Figure 1.10. Two tool artifacts have been combined to create this finding

Two tool artifacts have been combined to create this finding

In the Finding Details view select the artifacts tab (the last tab to the right) note that this finding has two artifacts. This finding is made up of two tool reports: one from FindBugs and one from PMD. The two artifacts that establish this finding can be seen in Figure 1.10.

In Sierra, reports from analysis tools are called artifacts. Sierra works to merge artifacts that are really about the same problem into one finding. One can think of artifacts as raw tool results and findings as what Sierra creates based upon those raw tool results. One other difference between artifacts and findings is that findings exist across scans while an artifact is connected to one and only one scan.

To fix this finding change the code from box(new String("hello")) to box("hello") and then scan the project one final time.

When the scan is completed the Findings view will update to show no findings. This indicates that no new findings have been found and the two we were working on have been fixed. Clear the search in the Sierra Quick Search view by pressing the icon and press Status to see that two findings have been fixed and two findings are unchanged as seen in Figure 1.11.

Figure 1.11. Status bar graph after fixing two findings in the code

Status bar graph after fixing two findings in the code

This tutorial has introduced basic use of the Sierra Eclipse client to audit Java code. You should now try Sierra on your own code and we encourage you to explore and make Sierra work the way you want it to.

Before we move on to the next tutorial we want to delete the ShowOff project from the Sierra database. This is done using the Scanned Projects view to the left of the Sierra Quick Search view. Select the SierraTutorial_ShowOff project and either press the icon on the view tool bar or choose Delete from the context menu as shown in Figure 1.12. A confirmation dialog will appear to confirm that you really want to delete the project. Press OK to confirm that you want to delete all the scans for the SierraTutorial_ShowOff project.

Figure 1.12. Removing the ShowOff project from the Sierra findings database

Removing the ShowOff project from the Sierra findings database

Note that the Delete All Sierra Data For This Workspace can be used to wipe the entire Sierra database. There is one Sierra database per Eclipse workspace, however, all scan documents are stored in your .sierra-data directory. If your Eclipse is closed deleting this directory clears out all Sierra data.

1.4.2. Interacting with a Sierra team server

This tutorial assumes that you have installed Sierra and have run through Section 1.4.1 the ShowOff tutorial. (For understanding only, this tutorial does not use the SierraTutorial_ShowOff project.) It also assumes that you have the Sierra Local Team Server (Optional) featured installed. This tutorial introduces you to use of a Sierra team server. The team server helps a group of programmers work together with Sierra.

If you have not added the SierraTutorial_SmallWorld project to your workspace yet, add it now by choosing SierraRun Sierra Tutorials from the workspace menu

SmallWorld is a Java text-oriented adventure game. The Colossal Cave Adventure game, produced in the 70s, was the historic first "interactive fiction" game, in which the computer would simulate and describe a situation and the user would type in what to do next, in simple English. Read through the overview.html file in the src directory for more information about this software.

To run SmallWorld in an Eclipse console run the SmallWorld class in the smallworld.textui.console package. To run SmallWorld in a graphical window run the SmallWorld class in the smallworld.textui.graphical package. The graphical window version of the game is shown in Figure 1.13.

Figure 1.13. Running the SmallWorld game

Running the SmallWorld game

Go ahead and run the game and play it for a while. The help command will tell you the commands the software understands. SmallWorld is clearly a work in progress as there is no way to win the game and there are no items to interact with in the virtual world. All you can do is move around and load and save your game. When you are done playing the game, type exit to terminate the program.

This tutorial uses a team server running on your desktop. The Sierra Local Team Server (Optional) feature contributes a Local Team Server view that allows you to start, stop, and examine the logs of a Sierra team server that you run on your desktop.

Open the Local Team Server view. You can do this one of two ways. The first approach is to reset the Code Review perspective (using the Window | Reset Perspective command from the main menu) this view will appear stacked in the top portion of the perspective and you can click the title bar to bring it to the front. The second approach is to select Window | Show View | Other... from the main menu. Then from the dialog that appears select the Local Team Server view under the Sierra category and press the OK button. The view appears as shown in Figure 1.14. (If you cannot find this view in Eclipse then it is likely that this feature is not installed. Go back to the Eclipse update site you used to install Sierra and install it.)

Figure 1.14. The Local Team Server view

The Local Team Server view

The team server controlled by this view is fully functional and can be connected to by other computers on your network using the IP address of your machine (depending, of course, upon the routing and firewall configuration on your network). The database and logs for this local team server appear in the .sierra-data/server subdirectory in your workspace. Two logs are available for you to examine. The first is the Jetty console output which shows logging output from the local server. The second is the Jetty request log which shows information about requests made from clients to the web site. Jetty is a lightweight web server implemented entirely in Java. It is used to execute the team server. If the logs panel is not visible in your view, select Show Server Logs from the view menu as shown in Figure 1.15.

Figure 1.15. The Local Team Server view showing the server logs

The Local Team Server view showing the server logs

From the same menu used to show the logs you can also access the local team server preferences. Select the Preferences... menu item. You will see Figure 1.16. This panel lets you adjust the memory used by the local team server and set the level of logging output. The default value is fine for this tutorial so press the Cancel button to exit the panel.

Figure 1.16. Preference panel for controlling the memory used by the local team server

Preference panel for controlling the memory used by the local team server

So that this tutorial can start with a fresh team server database, select Wipe Local Team Server Database from the local team server view menu (top right of the view) to delete the .sierra-data/server directory from your workspace. A dialog checks that you really want this. Confirm by pressing OK. If you already started a local team server using the Start Server, stop it before you wipe the database, however if you have never used the local team server, e.g., if you just installed Sierra, this wipe step may be safely skipped.

Go ahead and press the Start Server button on the view. A dialog will appear warning you that the life of the server process you are starting is not tied to the life of your Eclipse process. This dialog is shown in Figure 1.17. Read it and press the OK button. The traffic light will change to yellow during server start up. The first time a local team server is started may take several minutes because its database has to be created.

Figure 1.17. Warning you that the local team server does not exit when Eclipse exits

Warning you that the local team server does not exit when Eclipse exits

The traffic light will change to green when the team server is up and running (this could take a while on a slow computer). When this occurs click on the hyperlink here within the message line A team server is running. Click here to open a browser. to open a web browser within Eclipse on the team server portal login page. The views appear as shown in Figure 1.18.

Figure 1.18. The team server web portal and the Local Team Server view indicating that the team server is running

The team server web portal and the Local Team Server view indicating that the team server is running

Now, rather than using the internal Eclipse browser, open your favorite web browser (that supports JavaScript). Enter http://localhost:13376/sl/ to bring up the team server portal. Alternatively, you may also copy and paste the URL shown in the view to the right of the Network URL: label. This URL should also work from other machines on your local network. Sierra tries to determine your machine's external IP address, however, sometimes it mistakenly gets the loop-back one (in which case you should examine the output of the ifconfig for Linux/Mac or ipconfig /all for Windows to determine your machine's IP address). You do not need to know your machine's external IP address for this tutorial.

A new team server only has one account: admin with adminadmin for its password. Enter this information and press the Log In button. Because this is the first time any user has logged into the portal you are asked to give it a name. The name is used to identify this team server from other team servers. Typically you will want to use a name that makes sense for your organization, such as engineering or QA. For this tutorial, enter local desktop and then press Set Server Name as shown in Figure 1.19.

Figure 1.19. Naming the team server upon first portal login

Naming the team server upon first portal login

At this point the welcome page for the team server portal should appear as shown in Figure 1.20.

Figure 1.20. The welcome page on the team server portal

The welcome page on the team server portal

The welcome page shows information about the project scans that have been published to the server as well as the contributions of the users of this server. Because no project scans have been published and no users have contributed any audits our welcome page is a bit sparse.

Click on the Manage Site link in the upper-right of the page (just to the left of Log Out) to open the site management page. Select the Users tab to open the user management page. This page lets you add and manage the users of this server. We want to create two new users and disable the default admin user. To add a new user click on Create a New User link near the top of the page. In the dialog that appears enter a new user using the following information:

Dialog promptEntry
User Name:infocom
Password:zork
Confirm Password:zork
Administrator:Check this option

Repeat the process to create a troll user using the following information:

Dialog promptEntry
User Name:troll
Password:troll
Confirm Password:troll
Administrator:Leave this option unchecked

The user management screen also lets users that have the administrative role change the name, role, status, and password of any user. Users without the administrative role can only change their password.

We want to change the name of the user infocom to zork which is easier for us to remember. Click on infocom in the table to enable an in-place edit of this user name. Change it to zork and press the Enter key.

Select the Log Out link in the upper-right-hand corner of the page and log back in as the zork user. Go back to the users panel. (Note that you might need to refresh pages or restart your browser when you log in as a different user.)

The status of a user is either enabled or disabled. An enabled user can login to the server portal a disabled user cannot. Users are not deleted from a team server they are just disabled. This keeps the source of all audit information about findings on the server consistent.

Go back to the user management screen by clicking on the Manage Site link in the upper-right of the page (just to the left of Log Out) to open the site management page. Select the Users tab to open the user management page. We no longer need the default admin user so change its status to Disabled using the drop-down menu. If the list of disabled users gets long you can uncheck the Show disabled users setting on the table. Uncheck this setting now and your browser should match Figure 1.21.

Figure 1.21. The users page on the team server portal showing two enabled users

The users page on the team server portal showing two enabled users

Click on the Settings tab to open the settings panel. This panel allows you to see the name of the server, the version of the software, and the current and available versions of the database schema as shown in Figure 1.22. The current and available versions of the database schema should always be the same number unless a schema upgrade failed for some reason. If this should occur it is a software bug and should be reported to SureLogic.

This page also allows you to change the name of the server, as well as to configure it to email any errors it encounters to an administrator. You can fill in the new server name (e.g. local desktop), and click on Update Site Settings. Likewise, you can fill in the information required and send a test email to try out your configuration. (This is optional for this tutorial but recommended for a production server.)

Figure 1.22. The settings page on the team server portal sending a test notification email

The settings page on the team server portal sending a test notification email

Log your browser out of the team server by pressing Log Out in the upper-right of the browser.

At this point let's go back to your Eclipse. Go to the Code Review perspective. Select Sierra | Configure Team Servers from the Eclipse main menu. This will open the Team Servers view. This is the view where connections from the Eclipse client to team servers are defined. We will now define a connection to the local team server we are running. To do this click on the button in the view toolbar, or choose New... from the view menu, or click on the underlined setup a server in the view contents.

The New Sierra Team Server Location dialog will appear. This dialog lets you provide information about the team server that you want to connect with. To connect to our local team server fill in the following:

Dialog promptEntry
Host:localhost (the default value)
Port:13376 (the default value)
Context:/sl/ (the default value)
Protocol:http (the default value)
User:zork
Password:zork
Save Passwordchecked (the default value)
Enable automatic synchronizationunchecked (the default value)

The panel should look like Figure 1.23. If it does you can press the OK button. If someone else on another computer wants to connect to your local team server then they cannot use localhost as the host. They will need to enter the IP address of your machine. The rest of the connection settings should be the same, except, of course, that they should probably have a different user name and password. Next we will connect the SmallWorld project to this server.

Figure 1.23. Defining the connection to the local team server within the Eclipse client

Defining the connection to the local team server within the Eclipse client

A project can be connected to one and only one team server at a time. You can disconnect and reconnect the project to another team server, however, all the local data in your Eclipse client will be deleted when you perform the disconnect. The reason for this is that once you start sharing scans and audit information with that server your local data becomes coupled with the data of that team server.

The client does allow you to edit the properties of a server connection to reference another team server. This works if the name or IP address of that server was changed (for any reason) on your network. It also works if the server database you were connecting to was moved from one server to another. It also works if your user name or password need to be updated (as we shall demonstrate later in this tutorial using the troll user). Sierra checks on each client-server command that the client and servers databases are the expected ones.

To connect the SmallWorld project to the local server right-click on the server name and select Connect Projects... from the context menu.

Check the SierraTutorial_SmallWorld project in the dialog that appears and press the OK button.

Your Team Serversview will look like the image below.

To see the image above ensure that Show By Team Server is checked in the view menu as shown below.

A very useful feature of a team server is that it can store the scan filter for your team. A scan filter defines the types of results your team has deemed to be completely without merit. These results are filtered out of the scan. For more information about setting up a scan filter see Section 2.3.3. To send your scan filter to the server right-click on the server name and select the Send Local Scan Filter As... menu item from the context menu.

A dialog appear prompting you for a name to save the scan filter with on the server as shown below. Enter Tutorial and press Send to continue.

The local server now has a copy, the same scan filter as your client. (If you wish, you can look to see this copy of the scan filter in the Team Server under the Scan Filters portion of your local team server, it will be called Tutorial.)

Other members of your team get the scan filter settings from the team server. We don't need to download them since we just uploaded them, however, for practice we will. To download and use the Tutorial scan filter stored on the local server you right-click on the scan filter name and select Copy to Local Scan Filter from the context menu as shown below. A dialog will warn that this will replace the scan filter currently on your client. Press Yes to continue.

The reason it is important to keep the scan filter consistent between your clients and your server is that if you have different scan filters you can see different Sierra results. For example, if the server filters out findings about null pointers and your client does not then you will see more findings on the client than you do on your server. To understand why this is true you need to understand a bit about how scans work.

A project scan (via Eclipse or via Ant as described later in this document) creates a scan document file. You can see these files in the .sierra-data/scans directory under your workspace directory. For the SmallWorld project you will see the SierraTutorial_SmallWorld.sierra.gz scan document file. This file contains the tool reports about the SierraTutorial_SmallWorld project. When a scan is loaded into the client database your local scan filter is applied. When you publish your SmallWorld scan to your server the scan document file is sent to the server, which allows the server to apply its scan filter.

When you connect a project to a server, as we have done with SmallWorld. That project stops using the local client scan filter and starts using the one assigned to it by the team server. If you drill into the SmallWorld project in the Team Servers view you can see that SmallWorld is assigned Scan filter: Defaults for local server. This assignment is done on the portal.

We will now edit the Tutorial scan filter on the web portal and assign it to the connected SierraTutoral_SmallWorld project. In your web browser log back into the portal as the zork user (password zork). Select the Scan Filters tab and then select the Tutorial scan filter in the list at the left. This scan filter is defined in terms of finding types, let's define it with just a few focused categories. To do this we will first delete the scan filter and then build it from scratch. Press the Delete link at the upper-right to delete the scan filter (confirm if asked, Are you sure?). Next, press the Create a Scan Filter button at the upper-left and enter Tutorial and press Create. The new scan filter will be created.

Select the now empty Tutorial scan filter in the list at the left. Select the Edit link a the upper-right to edit the Tutorial scan filter. Select the Add Category link. In the dialog that opens select Correctness and Performance as shown below.

Next press OK to add the two categories to the scan filter.

Change the importance of the categories using the drop-down menus as follows:

NameImportance
CorrectnessCritical
PerformanceHigh

The importance set on the scan filter is used to set the importance of findings only when they are first created. The scan filter priority will not change the priority of any finding that previously existed and was matched with a finding from a previous scan.

Finally, press the Save link to finish setting up this scan filter. The result should look like the screen shown in Figure 1.24.

Figure 1.24. The completed Tutorial scan filter

The completed Tutorial scan filter

We now need to assign this scan filter to the SmallWorld project. To do this click on the Projects tab. Select the SierraTutorial_SmallWorld project in the list to the left. To change the scan filter assigned to this project select the (Change) link on line where the scan filter for this project is listed. In the dialog that appears select the Tutorial scan filter and press OK. The result should look like the screen shown in Figure 1.25.

Figure 1.25. The Tutorial scan filter is assigned to the SmallWorld project

The Tutorial scan filter is assigned to the SmallWorld project

We need to synchronize our Eclipse client with the changes we have made. To do this select the Synchronize All command from the Sierra menu or click the icon in the Team Servers view. This will synchronize with the local server and you should see the scan filter for SmallWorld change as shown in Figure 1.26.

Figure 1.26. After a Synchronize All the client knows that the Tutorial scan filter is assigned to the SmallWorld project

After a Synchronize All the client knows that the Tutorial scan filter is assigned to the SmallWorld project

At this point run a scan of the SierraTutorial_SmallWorld project. To do this select Sierra | Scan Project from the Eclipse main menu and check only the SierraTutorial_SmallWorld project and press the OK button. Wait for the scan to complete.

We can now publish this scan of SmallWorld to the local server. Select Sierra | Publish Latest Scan from the Eclipse main menu. Check the SierraTutorial_SmallWorld project and press the OK button. This client operation is the first of two ways to publish a scan to a team server. The second way to publish a scan to a team server is to use Ant.

After the publish has completed, select the Welcome tab in your web browser. The welcome pages should now look like Figure 1.27. It is possible that you might need to refresh your browser to get the page to reflect the changes caused by the scan publish.

Figure 1.27. The welcome page after the scan of SmallWorld has been published

The welcome page after the scan of SmallWorld has been published

The welcome page on the server now contains data about the SmallWorld scan we just published. You can see the counts of findings for SmallWorld in the Latest Scan Results chart and the Projects Published To This Portal table. Using Findings Quick Search view you can verify that these counts are consistent with the data in your client (Filter by the project SierraTutorial_SmallWorld then show the Importance counts).

Use the Sierra Quick Search view select all the findings from SierraTutorial_SmallWorld that are within the Performance finding category. There should be three findings as shown in Figure 1.28.

Figure 1.28. Findings by category for the SmallWorld scan

Findings by category for the SmallWorld scan

Note that in Sierra categories are not a partition of the finding types. It is possible for a finding type to be in one or more categories, in which case there is overlap.

Check both the categories in Sierra Quick Search view to see the three findings. The finding about changing the anonymous inner class SmallWorld$1 to named static class we consider unimportant for this program. Change the importance of this findings to Irrelevant using either the context menu in the Results view or the Finding Details view.

One of the findings suggests that the f_description field can be declared static. Looking at the code of this class it is clear that this field can be removed from the class, i.e., the string literal could simply be returned from the getDescription() method. This can be deemed a minor problem. First, change the importance of this finding to low and enter an audit that states:

Remove this field and simply return the string literal "Our Hero" from the getDescription() method.

The view will appear as shown below. Note the audits are by Local prior to a synchronize with the team server.

You have now made a few audits that you can share with the team server. To do this select Sierra | Synchronize All from the Eclipse main menu. After this command completes, note that the name the audit is attributed to changed from Local to zork because we synchronized under the user zork to the local server.

If you refresh the welcome page in your web browser it will look like Figure 1.29. The charts and graphs have been updated to show the contributions made by the zork user. Also we can see that the SmallWorld project now has 3 findings (1 critical, 1 low, and 1 irrelevant) and 3 audits on 2 findings.

Figure 1.29. The portal shows the audits attributed to the zork user

The portal shows the audits attributed to the zork user

In the Eclipse client mark the two performance findings as being examined by me (a command in the context menu as shown below) or make an ad hoc audit on each finding. Notice that these new audits are attributed to Local not to zork. This is because we have not synchronized these audits with the server.

To illustrate this point let's attribute these audits to the troll user not to the zork user.

Go to the Team Servers view in Eclipse, right-click on the local server and select the Properties... menu item as shown below.

In the dialog that appears change the user name and password to troll and press the OK button.

Now synchronize with the server again by pressing the icon in the toolbar of the Team Servers view (or by selecting Sierra | Synchronize All from the Eclipse main menu). The new audits will change to the troll user as shown in Figure 1.30.

Figure 1.30. After a sync local audits are attributed to the troll user

After a sync local audits are attributed to the troll user

If you refresh the welcome page in your web browser it will look like Figure 1.31. The charts and graphs have been updated to show the contributions made by the troll user. There are five audits by two users about two SmallWorld project findings.

Figure 1.31. The portal shows the audits attributed to the zork and troll users

The portal shows the audits attributed to the zork and troll users

To complete this tutorial go back to the Local Team Server view and press Stop Server to shutdown your local team server.

You can opt to leave the local team server running, however, realize that it is listening on your local network.

This tutorial has introduced basic interaction of the Sierra Eclipse client with a Sierra team server. You should now try using the Sierra team server on your own code and we encourage you to explore and make Sierra work the way you want it to.

1.4.3. Scanning code using Ant

This tutorial will demonstrate how to use the Sierra Ant tasks to scan the SmallWorld project in a script and load the resulting scan document into your Eclipse. The Sierra Ant task is used to automate scans as part of a QA or nightly build process. This tutorial assumes you have run the previous tutorial. You may skip the previous tutorial but you will need to load the SierraTutorial_SmallWorld project into your workspace.

First you will need to download and unzip the Sierra Ant task from this location on the SureLogic web site. This will create a sierra-ant directory on your machine at the location you unzip the file.

In the SmallWorld project create a file at the root of the project called sierra-ant-scan.xml with the below contents.

<?xml version="1.0" encoding="UTF-8"?>
<project name="SierraTutorial_SmallWorld" default="scan" basedir=".">

  <!-- (CHANGE) path to the unzipped SureLogic Ant tasks -->
  <property name="sierra.ant.home" location="C:\\Users\\Tim\\sierra-ant" />

  <!-- (COPY) SureLogic Ant task setup stuff -->
  <path id="sierra-ant.classpath">
    <dirset  dir="${sierra.ant.home}" includes="lib/com.surelogic.*" />
    <fileset dir="${sierra.ant.home}" includes="lib/**/*.jar" />
  </path>
  <taskdef name="sierra-scan" classname="com.surelogic.sierra.ant.SierraScan">
    <classpath refid="sierra-ant.classpath" />
  </taskdef>

  <path id="tf.classpath">
    <fileset dir="${basedir}" includes="**/*.jar" />
  </path>

  <target name="scan">
    <javac srcdir="${basedir}/src"
           destdir="${basedir}/bin"
           source="1.7"
           includeantruntime="false">
       <classpath refid="tf.classpath" />
    </javac>

    <!-- Make sure 'bin' is populated with class files for FindBugs -->

    <sierra-scan srcdir="${basedir}/src"
                 destdir="${basedir}/bin"
                 source="1.7"
                 includeantruntime="false"
                 sierraanthome="${sierra.ant.home}"
                 projectname="SierraTutorial_SmallWorld">
       <classpath refid="tf.classpath" />
    </sierra-scan>
  </target>
</project>

You will have to modify the setting for sierra.ant.home to reference where you located the sierra-ant directory on your machine.

Within Eclipse run this as an Ant task by selecting the XML file and selecting Run As | Ant Build. Output from the running task will appear in the console as seen in Figure 1.32.

Figure 1.32. Console output from scanning SmallWorld with Ant inside Eclipse

Console output from scanning SmallWorld with Ant inside Eclipse

You should be able to see from the console output that the project was scanned, and a file containing the results was written to disk. In our example, the output file is located in the SierraTutorial_SmallWorld directory and is called SierraTutorial_SmallWorld.2015.06.30-at-14.29.01.442.sierra-scan.zip. You can change the output directory by adding a sierrascandir attribute to the task.

We can import this scan into Eclipse when we are ready to look at the results. To do this we choose SierraImport Ant/Maven Scan.... The tool will then notify you once the scan has finished importing.

Figure 1.33. Successful scan import

Successful scan import

This tutorial has introduced the use of the Sierra Ant task. You now know how to use the Ant tasks to add Sierra to your QA process or nightly build. Reference documentation for the Sierra Ant tasks is found in Section 2.7.

Chapter 2. Reference

2.1. The Sierra menu

Figure 2.1. The Sierra menu

The Sierra menu

The Sierra menu appears as an item on the Eclipse workspace main menu. This menu provides direct access to common Sierra commands. The menu is divided into five sections. The top section contains commands that are useful in a stand-alone client. The second section (from the top) contains commands that communicate with one or more Sierra team servers. The third section contains to import and export data. The fourth section contains commands to report problems about or suggest improvements to Sierra directly to SureLogic. The bottom section allows access to the license management dialog.

The commands on the Sierra main menu are:

  1. ScanThis command starts a full scan on the selected set of projects. The scans are run in background jobs and progress can be seen in the Eclipse Progress view and (by default) via balloon notifications. A dialog is opened to allow the user to select which Java projects to scan as seen in Figure 2.2.

    Figure 2.2. Dialog allowing the user to select which Java projects to scan

    Dialog allowing the user to select which Java projects to scan


    If one or more projects are selected in the Package Explorer view then these projects will be checked when the dialog opens. (If only one Java project is open in the workspace then that project will also be checked by default.) If you do not want this dialog to appear when you have selected projects in the Package Explorer view then uncheck Show this dialog even when projects are selected in the Package Explorer before you press the OK button.

  2. Re-Scan ChangesThis command starts a partial scan on only those Java types in the project that have been recompiled since the last scan. If little has been changed in a project then this choice will be quicker than running a full scan. For the purpose of finding differences, only those types that are scanned are changed. A dialog is opened to allow the user to select the set of projects to run this command on that operates just like the Scan Project command.

  3. Open Code Review PerspectiveThis menu choice opens the Code Review perspective. This perspective is useful for examining and auditing analysis findings. This perspective may also be opened via the normal Eclipse menus and toolbars for perspectives. This perspective is described in Section 2.2

  4. Configure Team ServersThis menu choice opens and gives the focus to the Sierra Servers view. This view is used to manage connections to Sierra team servers. This view may also be opened via the normal Eclipse menus and toolbars for views.

  5. Synchronize AllThis menu choice synchronizes audits for all the projects connected to all Sierra team servers. All BugLink data is synchronized as well. This command has the same effect as selecting each connected project and selecting the Synchronize Project menu item.

  6. Synchronize ProjectThis command sends all local audits to the Sierra team server the selected project is connected to. It also downloads all audits (made by other users) from the server to this client. A dialog is opened to allow the user to select the set of projects to run this command on that operates just like the Scan Project command. All BugLink data is synchronized as well.

  7. Publish Latest ScanThis command sends the scan results from the last full scan to the Sierra team server that the project is connected to. Note that only full scans can be published to a team server. A dialog is opened to allow the user to select the set of projects to run this command on that operates just like the Scan Project command.

  8. Disconnect This command disconnects the selected project from the Sierra team server it is currently connected to. This action causes all local information about the project to be deleted (so a new scan will have to be run on the project). The disconnected project may then be connected to a different Sierra team server. A dialog is opened to allow the user to select the set of projects to run this command on that operates just like the Scan Project command.

  9. Import Ant/Maven Scan…This command lets the user load a Sierra scan made with the Ant task or Maven. For more information on using Ant please see Section 2.7. The dialog shown in Figure 2.3 is opened to allow the user to select the scan Zip file to load into the Eclipse workspace.

    Figure 2.3. The Import Sierra Ant/Maven Scan dialog box

    The Import Sierra Ant/Maven Scan dialog box

  10. Save Documentation As…This command copies the sierra-html-docs.zip to the disk. A dialog, shown in Figure 2.4, is opened to let the user to specify the directory the Zip file should be placed within. This command is useful if you want to open the Sierra documentation in your web browser. This file contains HTML versions of all the Sierra documentation also in your Eclipse help system. Many tool users prefer using a browser for Sierra documentation rather than the build-in Eclipse help system (each of search, and so on).

    Figure 2.4. The Save Documentation dialog box

    The Save Documentation dialog box

  11. Install Tutorial ProjectsThis command opens a dialog to allow the user to import one or more tutorial projects into their workspace and open the Sierra help to the step by step tutorials. For more information please see Section 1.4.

  12. Send Tip for ImprovementThis command opens a dialog to allow entry of a suggestion by the user to improve the Sierra tool. For more information please see Section 2.6.

  13. Send Problem ReportThis command opens a dialog to allow entry of a problem report by the user about the Sierra tool. For more information please see Section 2.6.

  14. Manage SureLogic LicensesThis command opens the SureLogic license management dialog. This dialog allows the user to install, view, and uninstall licenses for Sierra and other SureLogic tools. For more information see Section 2.5.

2.2. The Code Review perspective

The Code Review perspective organizes the Eclipse workbench to show views which will help you examine and interact with tool findings. It also provides access to views supporting interaction with one or more Sierra team servers.

This perspective is useful for beginning use of the Sierra Eclipse client. Its "canned" organization can help you to understand the capabilities of the tool. Advanced users may want to reconfigure the screen layout and save a custom perspective or add one or more of the Sierra views to the Java perspective.

Each of the views shown in the screenshot above is discussed in the following sections. These views include

2.2.1. Switching to the Perspective

The Code Verification perspective can be enabled in several ways:

  • By selecting SierraOpen Code Review Perspective.

  • By choosing to switch to the perspective when scanning a project:

  • By selecting WindowOpen PerspectiveOther…, and then choosing Code Review from the Open Perspective dialog box. Or by using any other standard Eclipse mechanism to switch perspectives, such as clicking the the perspective’s icon () in the shortcut bar.

2.2.2. The Scanned Projects view

The Scanned Projects view, as shown in Figure 2.5, lists the projects that have been scanned by the tool. It allows you to quickly re-scan one or more projects and can be used to delete scans from your disk.

Figure 2.5. The Scanned Projects view

The Scanned Projects view

Each row in the table represents a scan. The table displays the following columns:

  • Project. The name of the project.

  • Scan Time. The time the most recent scan occurred.

  • Prior Scan Time. The time of the scan immediately prior to the most recent scan, or blank if none.

  • Exclusion Specification (surelogic-tools.properties). The exclusions for source folders and packages from the surelogic-tools.properties file located at the project's root. This file is optional and its format is described in Section 2.4.

The view’s toolbar has two command icons:

  •  This button "re-scans" the selected projects. This allows you to easily start a new scan on a set of projects that you have previously scanned.

  •  This button deletes scans for the selected project from the disk.

Figure 2.6. The Scanned Projects view menu

The Scanned Projects view menu

The view’s menu has three commands; see Figure 2.6:

  • Re-ScanThis button "re-scans" the selected projects. This allows you to easily start a new scan on a set of projects that you have previously scanned.

  • DeleteThis button deletes scans for the selected project from the disk.

  • Delete All ScansThis button deletes all your scans from the disk. This action deletes the entire Sierra database of results from your disk. It my take some time, and the tool shows a progress bar after you confirm you really want to perform this action.

Figure 2.7. The Scanned Projects context menu

The Scanned Projects context menu

The view’s context menu has two commands; see Figure 2.7:

  • Re-ScanThis button "re-scans" the selected projects. This allows you to easily start a new scan on a set of projects that you have previously scanned.

  • DeleteThis button deletes scans for the selected project from the disk.

2.2.3. The Sierra Quick Search view

The Sierra Quick Search view, as shown in Figure 2.8, allows you to select a set of findings to examine based upon a set of filters. If no filter is defined all findings are let through. The resulting list of findings is shown in the Findings view described in Section 2.2.4.

Figure 2.8. The Sierra Quick Search view

The Sierra Quick Search view

Each choice in this view allows you to define a filter on the findings. First you choose what you want to filter. Second you check what you want to allow through that level of the filter to the next. Many levels of filtering can be defined in this view. To clear out one level press the icon within a filter. To clear out the entire filter press the icon at the upper-right of the view.

The filters supported by this view are as follows:

  1. Audited — Partitions findings into the set of findings that have been audited by a programmer and the set of findings that have not been audited by a programmer.

  2. Audits — Partitions findings based upon the number of times they have been audited by a programmer. A 0 indicates that no audits have been performed.

  3. Finding Category — Separates findings by the category their finding type is part of. Categories are defined by a set of finding types. Because a finding type can be included in more than one category, and thus a finding can be in more than one category, this does not strictly partition findings.

  4. Finding Type — Partitions findings by their finding type.

  5. Importance — Partitions findings by their assigned importance. Importance is one of: critical, high, medium, low, and irrelevant.

  6. Java Type — Partitions findings by the Java class that the (primary) code location the finding is about occurs within.

  7. Java Package — Partitions findings by the Java package that the (primary) code location the finding is about occurs within.

  8. Project — Partitions findings by the Java project that the (primary) code location the finding is about occurs within.

  9. Status — Partitions findings by the status of the finding compared to the last scan. New indicates that the finding was not in the last scan (or that there is no last scan). Unchanged indicates that the finding was in the last scan. Fixed indicates that the finding was in the last scan, but is not in the current scan.

  10. Tool — Partitions findings by the tool that reported the finding. If more than one tool reported the finding (i.e., it has multiple artifacts from different analysis tools) then multiple tools is indicated.

  11. Tool Artifacts — Partitions findings based upon the number of analysis tool artifacts reported about them. A 1 indicates that one analysis tool artifact supported the finding, a 2 indicates that two analysis tool artifacts supported the finding, and so on.

The view’s toolbar has two command icons:

  • ( __ | __ | __ ) BreadcrumbsLocated to the upper-left of the view a series of underlined titles allows you to animate the view to that filter. This is useful as the filter becomes large and complex and no longer fits on the screen.

  • Clear Current SearchThis button clears the entire filter from the view. It causes the Findings view to show all scan findings.

Figure 2.9. The saved searches toolbar at the bottom of the view

The saved searches toolbar at the bottom of the view

The view also has a toolbar at the bottom which allows searches to be remembered, named, and managed; see Figure 2.9:

  • Open SearchLets you select a named search from the complete list of saved searches. The selected search is loaded up in the view and the current search is discarded.

  • Save Search AsBrings up the dialog below to allow you to name the current set of filters defined in the view as a search.

  • Delete Saved SearchThis brings up the dialog shown below to allow you to delete a search that you previously saved.

  • Saved Searches: ( __ | __ | __ )This list allows you to directly click on a named search to bring it up in the view. If this list gets too long you can use the Open Search toolbar item described above.

Figure 2.10. The Scanned Projects view menu

The Scanned Projects view menu

The view’s menu has two commands; see Figure 2.10:

  • Import Searches... This button imports an XML file containing saved searches into this workspace. Beware that any searches you have that match a name in the XML file will be overwritten with the search in the XML file.

  • Export Searches... This button allows you to export all your saved searches to an XML file. This file can then be loaded into another Eclipse workspace, such as an Eclipse installation used by a colleague or one on another computer used by you.

Figure 2.11. The Scanned Projects context menu

The Scanned Projects context menu

The view’s context menu has three commands; see Figure 2.11:

  • Select AllThis menu item checks all filter items in the list — causing all possible findings to be allowed through the filter.

  • Deselect AllThis menu item unchecks all filter items in the list — causing no findings to be allowed through the filter.

  • Sort By Finding CountWhen this menu item is checked then then the listed filter items are sorted by how many findings each item contains. When this menu item is not checked the listed filter items are sorted alphabetically.

2.2.4. The Findings view

This view displays a list of findings. If a filter is defined by the Sierra Quick Search view then this view lists the findings that pass through that filter.

The Findings view, as shown in Figure 2.12, lists the set of findings reported by the tool. If no filter is defined all findings are let through, otherwise findings which make it through the filter are listed.

Figure 2.12. The Findings view

The Findings view

Each row in the table represents a finding. The table displays the following columns:

  • Summary. A short description of the finding.

  • Tool. The tool, such as FindBugs, that reported the finding.

  • Project. The Eclipse project the finding is within.

  • Package. The Java package the finding is within.

  • Type. The Java type, such as a class or interface, the finding is within.

  • Line. The line number the finding is about.

  • Importance. The tool, or Sierra-user audited, importance of the the finding.

  • Finding Type. The tool-defined type of the finding, such as Avoid using short.

Each column may be sorted by pressing on the column title. If too many findings are displayed a warning appears at the bottom of the view. This warning is a hyperlink to the preferences if you wish to increase the maximum number of findings displayed.

Figure 2.13. The Findings context menu

The Findings context menu

The view’s context menu has three commands; see Figure 2.13:

  • Set ImportanceThis menu item allows you to directly set the importance of a group of selected findings. This can be quicker than doing it one by one using the Finding Details view.

  • Mark As Examined By MeThis menu item "stamps" that you examined the finding. This information becomes an audit on the selected findings visible to your team members..

  • Filter Findings Of This Type From Future Local ScansThis menu item filters out findings of this type, via your scan filter, in future scans.

  • Export... Exports the list of findings into a file. Two different formats are supported as shown in the dialog below. This dialog allows you to choose the export format and the destination file.

2.2.5. The Finding Details view

The Finding Details view, as shown in Figure 2.14, displays information about and allows you to audit one particular finding. The finding displayed in this view corresponds to the selection in the Findings view.

Figure 2.14. The Finding Details view Synopsis tab

The Finding Details view Synopsis tab

The Synopsis tab primarily provides an overview of the finding. This overview includes a summary, importance judgment, audit count, reporting analysis tool, location in the code, and a detailed description.

You can quickly change the importance judgment of this finding from this tab using the drop-down menu at the upper-right of the view. An example of performing this action is shown in the image below.

You can also press the icon to create a quick audit that states that you have examined the finding.

Figure 2.15. The Finding Details view Audit tab

The Finding Details view Audit tab

The Finding Details view Audit tab is shown in Figure 2.15. This view lists the detailed audits made by your team members about this Sierra finding. You can also press the icon to create a quick audit that states that you have examined the finding. You can change the importance judgment of the finding using the radio control to the right of the tab. You can also enter a comment and add it to the stream of audits about this finding. When you synchronize with your team server, all the members of your team will see your audits.

Figure 2.16. The Finding Details view Artifact tab

The Finding Details view Artifact tab

The Finding Details view Artifact tab is shown in Figure 2.16. An artifact is a report from an analysis tool run during a scan. Sierra creates a finding from one or more artifacts. In the example shown above, the finding was created from two artifacts, one from PMD and one from FindBugs. The tab shows information about what the tool reported and the location the tool referenced in its report.

Described further in Section 1.4.1.

2.2.6. The Team Servers view

The Team Servers view, as shown in Figure 2.17, provides a tree that shows the Sierra Eclipse client's connections to Sierra Team Servers on the network. The view shows what projects are connected to particular team servers and what scan filters exist and are in use. This view has a shortcut icon that allows all information to be synchronized with the set of known Sierra Team Servers..

Figure 2.17. The Team Servers view organized by team server

The Team Servers view organized by team server

The view’s toolbar has two command icons:

  •  This button performs a synchronize with all servers and connected projects. It is the same as choosing Synchronized All from the Sierra menu.

  •  This defines a new connection to a running team server. When it is pressed the dialog below appears for you to fill out all the connection information about the team server. Please see the tutorial in Section 1.4.2 about interacting with a team server for some concrete examples of defining a connection.

Figure 2.18. The Team Servers view menu

The Team Servers view menu

The view’s menu has five commands; see Figure 2.18:

  • New... This defines a new connection to a running team server. When it is pressed the dialog below appears for you to fill out all the connection information about the team server. Please see the tutorial in Section 1.4.2 about interacting with a team server for some concrete examples of defining a connection.

  • Show by Team ServerThe tree displayed in the Team Servers view has two possible organizations. Selecting this radio choice organizes the tree by team server as shown in Figure 2.17.

  • Show by ProjectThe tree displayed in the Team Servers view has two possible organizations. Selecting this radio choice organizes the tree by project as shown in Figure 2.19.

    Figure 2.19. The Team Servers view organized by project

    The Team Servers view organized by project


  • Synchronize AllThis menu choice performs a synchronize with all servers and connected projects. It is the same as choosing Synchronized All from the Sierra menu.

  • Preferences... Selecting this menu choice opens the preference page for team server connections. This preference page is described in Section 2.3.4. The server interaction preference pane allows control over automatic synchronization with Sierra Team Servers. To enable automatic interaction with a server, right-click on a team server in the Team Servers view and check Use Automatic Synchronization.

Figure 2.20. The Team Servers context menu

The Team Servers context menu

The view’s context menu has five commands; see Figure 2.20:

  • Scan ProjectThis menu choice starts a full scan on the selected project. The scans are run in background jobs and progress can be seen in the Eclipse Progress view and (by default) via balloon notifications. This is the same as the Scan Project command on the Sierra menu.

  • Re-Scan Changes in ProjectThis menu choice starts a partial scan on only those Java types in the selected project that have been recompiled since the last scan. If little has been changed in a project then this choice will be quicker than running a full scan. For the purpose of finding differences, only those types that are scanned are changed. This is the same as the Re-Scan Changes in Project command on the Sierra menu.

  • Synchronize ProjectThis menu choice performs a synchronize of the selected project with its connected team server. It is the same as choosing Synchronized Project from the Sierra menu.

  • Publish Latest ScanThis menu choice sends the scan results from the last full scan to the Sierra team server that the selected project is connected to. Note that only full scans can be published to a team server. This is the same as the Publish Latest Scan command on the Sierra menu.

  • DisconnectThis menu choice disconnects the selected project from the Sierra team server it is currently connected to. This action causes all local information about the project to be deleted (so a new scan will have to be run on the project). The disconnected project may then be connected to a different Sierra team server. This is the same as the Disconnect command on the Sierra menu.

2.2.7. The Synchronize History view

Figure 2.21. The Synchronize History view

The Synchronize History view

The Synchronize History view, as shown in Figure 2.21, provides a table that lists each synchronize that has been done with a Sierra Team Server. The table lists when the synchronize occurred, what server was involved, and a summary of the audit data passed back and forth. Selecting a row in this table brings up the Synchronize History Details view.

Each row in the table represents a finding. The table displays the following columns:

  • Occurred. The date and time when the connection with the team server occurred.

  • Server. The name of the team server which Eclipse connected.

  • Summary. A synopsis of what was sent and what was received from the team server during the connection.

Each column may be sorted by pressing on the column title. Selecting a row in the table brings up the Synchronize History Details view which provides more information about the event and links to particular Sierra findings involved.

Figure 2.22. The Synchronize History view menu

The Synchronize History view menu

The view’s menu has two commands; see Figure 2.22:

  • Omit Empty Synchronize EventsThis toggle allows you to filter out synchronize events that simply connected and did not transfer any audit information. This can be helpful to remove clutter from the view table.

  • Preferences... This button opens the preference page for team server connections. This preference page is described in Section 2.3.4. The server interaction preference pane allows control over automatic synchronization with Sierra Team Servers. To enable automatic interaction with a server, right-click on a team server in the Team Servers view and check Use Automatic Synchronization.

2.2.8. The Synchronize History Details view

Figure 2.23. The Synchronize History Details view

The Synchronize History Details view

The Synchronize History Details view, as shown in Figure 2.21, provides details linking to particular audits for a synchronize with a Sierra Team Server. A synchronize event is selected in the Synchronize History view that focuses the information shown in this view.

The findings underlined in the detail report, when selected, bring up the Finding Details view in the Audit tab. This allows you to examine the audits.

2.3. Preferences

The Sierra Eclipse client has many preferences. These preferences are configurable by the user through preference panels. There are three of these panels and each in described in the sections below.

To open the Eclipse preferences select Window | Preferences... from the Eclipse main menu. Sierra should be visible in the outline on the left of the dialog that appears. If you type Sierra in the text box to the upper-left of the dialog then the outline will be filtered to only shown the Sierra preference pages.

2.3.1. Sierra

Figure 2.24. The Sierra preference pane

The Sierra preference pane

This preference page is used to configure the appearance of and many general settings about the Sierra Eclipse client.

The settings that may be configured are described below:

The Data directory sets where Sierra stores scan data and logs. In addition, the server subdirectory of the data directory is used to store all data for the Local Team Server. All Sierra data goes into the data directory except the local Database which is stored under the current Eclipse workspace. This location is relative to your workspace and cannot be changed. It is listed here so you can find it (if you need to delete/clear out all your Sierra data).

The Appearance group contains the following settings:

  1. Maximum number of findings listed in 'Findings' view: This setting limits the number of findings that the Findings Quick Search view will show. This setting ensures that Eclipse doesn't run out of memory trying to display a gigantic set of analysis findings.

    The default value for this setting is 500, however, it can be raised up to the point that Eclipse performance becomes unacceptable to you (this value can be large if you have a fast computer and allocate a lot of memory to Eclipse). A warning is shown in the Findings view if a list of findings is cutoff with a hyperlink to this preference page.

  2. Show 'balloon' notifications for scan start and completion. This setting controls if balloon notifications pop up when a scan is run.

    The default value for this setting is checked (notifications are shown).

  3. Prompt to change to the Code Review perspective on scan completion. This setting controls a dialog is opened to prompt the user to consider changing to the Code Review perspective when a scan has completed.

    The default value for this setting is checked (the user is prompted).

  4. If no prompt, automatically change to the Code Review perspective. If the previous setting is false (no user prompt) then this setting controls if the perspective is automatically changed to the Code Review perspective when a scan has completed.

    The default value for this setting is checked (the perspective is changed).

  5. Allow the user to select the set of projects to scan even when projects are selected (in the Package Explorer). This setting controls if the dialog is shown to allow the user to select projects when the user performs a scan or publish. If this setting is checked then the dialog always appears even if projects are selected in the Package Explorer. If this setting is not checked then the dialog will only appear when no projects are selected in the Package Explorer.

    The default value for this setting is checked.

  6. Show markers for findings in the Java editor (requires Eclipse restart). This setting turns on or off the * markers that highlight tool findings in the gutter of the Java editor. This setting must be checked for the next setting to be taken into account by Sierra.

    The default value for this setting is checked (markers are shown).

  7. Only show markers for findings in the Java editor at or above: If the previous setting is checked then this setting selects the importance threshold for showing markers in the gutter of the Java editor.

    The default value of this setting is High meaning that only findings of High or Critical importance are highlighted in the gutter of the Java editor.

The Code Scanning settings are used when code scans are performed by Sierra from within Eclipse. This group contains the following settings:

  1. Maximum VM memory allowed for scans: Code scans run in a separate Java VM. This preference controls the maximum memory used by code scan processes.

    The default value for this setting is 1024 MB. The maximum value for your computer is shown in the dialog. This maximum value for this setting is difficult to determine and is different on each computer configuration due to technical limitations in Java VM implementations. Sierra calculates this maximum for your computer configuration as best it can and limits your setting based upon the results of this calculation. However, it is possible, in rare cases, that too large a value for your computer configuration could be set. In this case the scan will abort right away and you should get an indication of what the problem is.

  2. Save all modified resources automatically prior to starting a scan. This indicates that any unsaved resources in the workspace are automatically saved prior to a scan without prompted the user.

    The default value for this setting is unchecked (the user is prompted to save resources prior to a scan starting).

2.3.2. Local Team Server

Figure 2.25. The Local Team Server preference pane

The Local Team Server preference pane

The Local Team Server preference pane allows you to control the maximum memory used by and the logging level of the local team server.

The Memory Use setting controls the memory used by the Local Team Server process. The Local Team Server runs in a separate Java VM. The Local Team Server is executed within the Jetty web container. Jetty is a lightweight web server implemented entirely in Java.

The default value for this setting is 1,024 MB. The maximum value for your computer is shown in the dialog. This maximum value for this setting is difficult to determine and is different on each computer configuration due to technical limitations in Java VM implementations. Sierra calculates this maximum for your computer configuration as best it can and limits your setting based upon the results of this calculation. However, it is possible, in rare cases, that too large a value for your computer configuration could be set. In this case the server startup will hang at the yellow light forever and if you restart Eclipse will become the red light. You should see an error in the Jetty console log on most Java VMs.

The Logging setting sets the minimum threshold at or above which server log messages are output to the Jetty console log. This log can be viewed in the Local Team Server view.

The default value for this setting is INFO.

2.3.3. Scan Filter

Figure 2.26. The Scan Filter preference pane

The Scan Filter preference pane

The Scan Filter preference pane allows fine control over what analysis rules are loaded into the Sierra database during a partial or full scan. This preference pane reflects the local scan filter used only for unconnected projects. If a project is connected to a team server then it uses the scan filter assigned to it by that team server.

Individual finding types can be checked or unchecked. If a rule is checked it is included when a scan is run. If it is unchecked it is excluded when a scan is run.

The local scan filter may be shared among a development team using a Sierra team server. In the Team Servers view you can select a server and on its context menu select Send Local Scan Filter As... to send your local scan filter settings to that server. You will be prompted for a name for the scan filter (all scan filters on a team server are explicitly named). You can also select any named scan filter on a team server and on its context menu select Copy to Local Scan Filter to download that scan filter setting from that server and overwrite your local settings.

2.3.4. Server Interaction

Figure 2.27. The Server Interaction preference pane

The Server Interaction preference pane

The server interaction preference pane allows control over automatic synchronization with Sierra Team Servers. To enable automatic interaction with a server, right-click on a team server in the Team Servers view and check Use Automatic Synchronization.

If automatic synchronization is turned on for a server then the settings in this preference pane control the interaction with that server.

Period between team server interactions: This sets the time in minutes between automatic synchronization of a server.

Policy for handling server failures: This setting sets what to do if it is not possible to communicate with a particular server. A value of Ignore logs the problem but does not notify the user. A value of Pop-up a balloon logs the problem and puts up a balloon notification to the user for a short period of time (this is the default setting). A value of Pop-up a dialog logs the problem and pops up a dialog (which must be dismissed) to notify the user.

Retry threshold (# of consecutive failures before switching into manual mode): If the number of failed attempts to contact the server during one Eclipse session exceeds this number then no further attempts are made.

2.4. SureLogic tool properties file

It is possible to exclude particular Eclipse source folders or Java packages from a scan. This feature can be useful to exclude test or obsolete code from scans.

To do this you create a surelogic-tools.properties file at the root of an Eclipse Java project. Two properties are recognized

  • scan.exclude.source.folderThis property excludes one or more source folders of a project from scans. The source folder is referenced by its name relative to the root of the project. More than one source folder can be specified using a comma separated list.

  • scan.exclude.source.packageThis property excludes the contents of one or more packages from scans. Packages may be listed explicitly using a comma separated list. A * can be used within a package name as a wildcard to match several packages.

The example shown in Figure 2.28 excludes the test source folder of the timingframework-core project.

Figure 2.28.  Use of the surelogic-tools.properties to exclude the test source folder of the timingframework-core project

Use of the surelogic-tools.properties to exclude the test source folder of the timingframework-core project

The example shown in Figure 2.29 excludes any package in the timingframework-swing project that's name starts with org.jdesktop.swing.animation.demos. For this example that matches two packages: org.jdesktop.swing.animation.demos and org.jdesktop.swing.animation.demos.splineeditor.

Figure 2.29.  Use of the surelogic-tools.properties to exclude packages from the timingframework-swing project

Use of the surelogic-tools.properties to exclude packages from the timingframework-swing project

Some further examples of excluding code within an Eclipse Java project from a scan are shown in the table below.

ExampleDescription
scan.exclude.source.folder=test Excludes a source folder named test located at the root of the project folder from scans.
scan.exclude.source.folder=test1,test2,test3 Excludes three source folders from scans: test1, test2, andtest3.
scan.exclude.source.package=com.surelogic.tests,com.surelogic.demos Excludes two packages from scans: com.surelogic.tests and com.surelogic.demos.
scan.exclude.source.package=*test* Excludes any package from scans that contains test as part of its name.
scan.exclude.source.package=*.test.* Excludes any package from scans that is a sub-package of a test package, but not the elements of the test package itself.
scan.exclude.source.package=*test*,com.surelogic.demos Excludes any package from scans that contains test as part of its name as well as the com.surelogic.demos package.

2.5. License management

Sierra is commercial software and a license is required to use it. Licenses are obtained from SureLogic and expire after some period of time. Lack of a license will prohibit you from running scans. It is still possible to examine data from prior scans (which can be useful if your license expires). Selecting Manage SureLogic Licenses from the Sierra menu brings up the license management form as seen in Figure 2.30. (It is also possible to bring this dialog up from the main Sierra preferences pane by pressing the Manage SureLogic Licenses button.) For Sierra to operate properly either a Sierra or All Tools license must be installed.

Figure 2.30. The SureLogic license management dialog

The SureLogic license management dialog

By default license installation requires internet access. SureLogic can, in special cases, provide licenses that do not require internet access. Further use of the product does not require internet access. If a manual uninstall is done, before license expiration, internet access is also required. SureLogic tracks the number of times a particular license is installed and uninstalled. We stress that Sierra does not, unlike other plug-ins such as MyEclipse, "talk-back" to SureLogic each time Eclipse is started.

The installed license expires after a period of time (clearly visible to the user) and a new license has to be installed to continue to use Sierra.

Licenses can be installed more than once. Thus, one license can be used for all of an organization or SureLogic can issue one per location or one per organizational entity.

If the Sierra Eclipse plug-in does not have a valid license it will not effect the Eclipse installation that Sierra is installed into. The IDE will load and function normally, but when Sierra functions are executed they will fail noting the lack of a license. Serviceability functions of the tool (e.g., sending problem reports to SureLogic, installing and uninstalling licenses) function properly without a license. The unlicensed Sierra plug-in can be uninstalled or disabled within Eclipse.

When you receive a license file from SureLogic it is installed via this dialog. To install the license select the row in the license table that matches the type of license. For example, if you have been sent a Sierra license select the Sierra row in the license table. Next press the Install License button. You will be prompted for the location of your license file. The tool checks with SureLogic and reports that your license has been installed and returns showing information about the installed license. The license file is not examined by the tool after the installation is completed unless you install the file again (after an uninstall).

To uninstall a license, select the row in the license table and press the Uninstall License. You will be asked if you are sure you want to uninstall the license. If you confirm the uninstall then the license is removed. This may take a minute as SureLogic is informed that your license has been uninstalled.

When a license is nearing expiration the tool warns the user with the dialog shown in Figure 2.31.

Figure 2.31. Dialog warning that the installed Sierra license is about to expire

Dialog warning that the installed Sierra license is about to expire

When a license does expire it disappears from the dialog. The tool is considered unlicensed at that point. To fix this situation install a new license (it is not required to install a new version of Sierra).

2.6. Bugs and tips

Sierra allows any user to send problem reports and suggestions to SureLogic from the main menu. Selecting Send Tip for Improvement or Send Problem Report allows a tip or problem report to be send to SureLogic directly within Eclipse as shown in Figure 2.32. These menu choices bring up dialogs that allow the user to control exactly what information is sent to SureLogic. In addition, the user can preview the exact text that will be sent over the internet.

Figure 2.32. Menu items to send bugs and tips to SureLogic

Menu items to send bugs and tips to SureLogic

The Send Tip for Improvement command opens a dialog to allow entry of a suggestion by the user to improve the Sierra tool as seen in Figure 2.33. The dialog allows the user to control exactly what information is sent to SureLogic. In addition, the user can preview and edit the exact text that will be sent. If you have no Internet connection you can print or save the text of your problem report (to fax or email).

Figure 2.33. Dialog allowing the user to enter a tip to improve Sierra

Dialog allowing the user to enter a tip to improve Sierra

The Send Problem Report command opens a dialog to allow entry of a problem report by the user about the Sierra tool as seen in Figure 2.34. The dialog allows the user to control exactly what information is sent to SureLogic. In addition, the user can preview and edit the exact text that will be sent. If you have no Internet connection you can print or save the text of your problem report (to fax or email).

Figure 2.34. Dialog allowing the user to enter a problem report about Sierra

Dialog allowing the user to enter a problem report about Sierra

Messages sent from these dialogs go over HTTP to SureLogic. If a proxy is used on your network then it is critical to configure Eclipse to use it. To do this open the Eclipse Preferences and examine the Network Connections under the General preferences. This dialog allows you to configure Eclipse for your network as shown in Figure 2.35.

Figure 2.35. Eclipse preferences for network connections within the IDE

Eclipse preferences for network connections within the IDE

2.7. Using Ant

The Sierra Ant task can scan a project and produce Sierra results. It is, by design intended to be similar to the javac Ant task. This task results in a Zip file that can be loaded into Eclipse using the Import Ant/Maven Scan... on the Sierra menu. Once loaded into Eclipse the Sierra scan results can be examined just like any other scan.

The Ant tasks are not included within the Eclipse plugin (to save space) but can be downloaded here on the SureLogic website.

The special attributes are given below, note that other javac task attributes work as well. The idea is for you to copy or "clone" your javac task and modify it just a bit (with the attributes below) to be a Sierra scan task.

Note that you must run this task in a Java 7 VM (it can analyze any code).

The below code shows and example of adding the Sierra tasks into Ant.

2.7.1. sierra-scan task

This task scans code and produces a scan file on the disk. This task is, for convenience, very similar to the javac task. The new attributes are:

AttributeDescriptionRequired
projectname This attribute sets the name of your project when the scan is loaded into Eclipse. This value is also used to name the resulting Zip file. projectname="SierraTutorial_SmallWorld" Yes
sierraanthome This attribute sets set this to the location of the bits for the Sierra Ant task (where you unzipped them). Typically you copy the pattern illustrated in the Ant script below and set this path as the property "sierra.ant.home" so that it can be used to specify the task classpath as well as the value of this attribute. e.g.,<property name="sierra.ant.home" location="C:\\Users\\Tim\\sierra-ant" /> ... sierraanthome="${sierra.ant.home}" Yes
sierrascandir This attribute sets a directory to create the scan Zip file within. If it is not set then output is written to the current directory. This may be useful if you want to gather results in a particular location on your disk. sierrascandir="C:\\Users\\Tim\\myscans" No, output defaults to the current directory.
surelogictoolspropertiesfile This attribute sets the location of a surelogic-tools.properties file to be read to control the scan. This file can control aspects of the Sierra scan (please see Section 2.4. If this attribute is not set the tool looks for a surelogic-tools.properties file in the current directory and uses that if it is found. surelogictoolspropertiesfile="C:\\Users\\Tim\\surelogic-tools.properties" No, if not set the tool looks for a surelogic-tools.properties file in the current directory (a useful default if you place the Ant script and the properties file at the root of a Java project). If found then that file is used, if not then no properties are used.

Below is an example Ant script for SierraTutorial_SmallWorld. This is described in further detail in Section 1.4.3.

<?xml version="1.0" encoding="UTF-8"?>
<project name="SierraTutorial_SmallWorld" default="scan" basedir=".">

  <!-- (CHANGE) path to the unzipped SureLogic Ant tasks -->
  <property name="sierra.ant.home" location="C:\\Users\\Tim\\sierra-ant" />

  <!-- (COPY) SureLogic Ant task setup stuff -->
  <path id="sierra-ant.classpath">
    <dirset  dir="${sierra.ant.home}" includes="lib/com.surelogic.*" />
    <fileset dir="${sierra.ant.home}" includes="lib/**/*.jar" />
  </path>
  <taskdef name="sierra-scan" classname="com.surelogic.sierra.ant.SierraScan">
    <classpath refid="sierra-ant.classpath" />
  </taskdef>

  <path id="tf.classpath">
    <fileset dir="${basedir}" includes="**/*.jar" />
  </path>

  <target name="scan">
    <javac srcdir="${basedir}/src"
           destdir="${basedir}/bin"
           source="1.7"
           includeantruntime="false">
       <classpath refid="tf.classpath" />
    </javac>

    <!-- Make sure 'bin' is populated with class files for FindBugs -->

    <sierra-scan srcdir="${basedir}/src"
                 destdir="${basedir}/bin"
                 source="1.7"
                 includeantruntime="false"
                 sierraanthome="${sierra.ant.home}"
                 projectname="SierraTutorial_SmallWorld">
       <classpath refid="tf.classpath" />
    </sierra-scan>
  </target>
</project>

2.8. Using Maven

A Maven task for Sierra is still under development. A workaround is to use Ant within Maven as discussed here and here.

Chapter 3. Release notes

For each release of the Sierra system there are new and noteworthy features to try out, and known limitations to avoid or workaround. These are presented in the sections below for each released version of Sierra.

3.1. Sierra version 5.6.1

This section describes the 5.6.1 version of Sierra.

3.1.1. New and Noteworthy

This section describes new and noteworthy features in this version of Sierra.

  1. Reorganization of Sierra menu — To make the Sierra menu simpler to use we have reorganized it. Items are better grouped by use. This was driven, in part, by several changes to the tool are discussed below. The top section contains commands to operate Sierra in Eclipse. The second section contains commands to setup or interact with a team server. The third section contains commands that import or export files. The fourth section contains commands to send feedback to SureLogic and run the Sierra tutorials. The last section contains a command to open a dialog to manage your tool license.

  2. Improved Ant task — Several changes to the Sierra Ant task are included in this version. If you use the Ant task you'll have to make some changes to your scripts. If not, the improvements made in this tool release may make the task useful in your development environment. A summary of the changes is listed below.

    1. The task is no longer included in the Eclipse distribution. It must be downloaded here on the surelogic website. The reason for this change is to reduce the Eclipse tool distribution size. When adding the Ant task, Sierra doubles in size, with Ant and Maven it is 3X the download size. Now folks can download only what they need.

    2. The task has been simplified. It is still similar to the Ant javac task but now has simpler setup.

    3. Output from the Ant task is a Zip file that can be loaded into Eclipse. The name of the file encodes the information needed to load it into Eclipse.

    4. The sierra-publish task has been removed. This task has been removed as SureLogic considers how to better support command-line use of Sierra. Please let us know if you rely upon this capability (we do not think this task has ever been widely used).

    This approach is also intended to be supported in Maven but the Maven plugin for Sierra is not yet complete. Further we plan to use the Ant and Maven to support predicates on the tool results (e.g., all annotations are consistent with the code). This future work will enable automated use of Sierra in a "back office" automated build.

  3. HTML version of this documentation packaged with the tool — You can choose the Save Documentation As... menu item shown in the image below to save a sierra-html-docs.zip file on your disk. Inside this Zip file is the HTML version of this documentation that you can open in your browser. Some users prefer this format because they can display it in the browser of their preference.

  4. Updated analysis tools — PMD has been updated to version 5.3.3.

3.2. Sierra version 5.6.0

This section describes the 5.6.0 version of Sierra.

3.2.1. New and noteworthy

This section describes new and noteworthy features in this version of Sierra.

  1. Updated analysis tools — FindBugs has been updated to version 3.0.1. PMD has been updated to version 5.2.3.