2.3. Maven Project

The following Maven plugins and their goals can be used within the PerfCake project when you work with the PerfCake's source code.

2.3.1. Project Structure

There is a parent project composed of three child Maven modules. There is a Bill Of Materials that defines all dependencies used with PerfCake, the PerfCake Agent which installs into the application under inspection and needs to be compiled with an older Java version because of compatibility reasons, and the main core of PerfCake.

Because of the split into multiple child modules, there is a need to run mvn install -DskipTests to install the parent module into your local repository when working on the devel Git branch.

The modules are as follows.

  • perfcake-bom Bill Of Materials with dependencies definitions.

  • parfcake Core PerfCake module, contains all the code needed to build the product.

  • perfcake-agent JVM Agent to be used when running target application (application under inspection) with memory monitoring. This module is compiled with an older Java version (1.5).

2.3.2. Maven Profiles

Use the following Maven profiles to achieve desired results.

  • production Generates output classes without debugging information. This produces smaller results and is intended for binary distributions. This must be used during the release procedure.

  • sign Automatically adds digital signatures of build artifacts during the install phase. Needs properly configured GPG agent.

Profiles for controlling test groups can be found in section Section 2.5, “Test Development” .

2.3.3. Standard Maven Goals

We try to minimalize the necessity for running standard Maven goals in a different manner or in a way they are not originally intended to. We also try to make sure all of these goals work with the parent project but this is not always possible. In case you realize the goal does not work in the parent directory, try switching to the perfcake module. So far we use the following goals.

  • clean Cleans the compiled artifacts and reports. Basically deletes the target directory.

  • compile Compiles the whole project including tests.

  • test Executes all the tests. See section Profiles for controlling test groups can be found in section Section 2.5, “Test Development” for Maven profiles that control test groups.

  • install Install project artifacts into the local Maven repository. This is needed when working in the devel Git branch with snapshot versions.

  • package Packages the distribution jar files.

  • exec:exec Works only in the perfcake module. Runs PerfCake, parameters are passed using -Dparam=value . Never use exec:java directly as Maven will comply about missing configuration (the configuration is passed in from exec:exec ).

  • site Works only in the perfcake module. Generates the Maven HTML site. Consumes output of other plugins like JaCoCo. If the other consumables should be part of the generated site, they must be ready before calling this goal.

2.3.4. Documentation

It is possible to generate JavaDoc for individual Maven modules as well as a single aggregated package for all of them.

  • javadoc:javadoc Generates documentation for the current Maven module.

  • javadoc:aggregate Generates aggregated documentation package when executed in the parent project.

2.3.5. Code Style with Checkstyle

With checkstyle there is a (limited) possibility to check your code formatting that it aligns according to this guide. There are some issues in checkstyle that report false positives. In this case you can use the following format of a comment to ignore a warning for th the given line.

Example 2.1. Ignoring a chackstyle warning

  1 ...
  2       // follow the exact format of the comment: "// @checkstyle.ignore(<warn1>|<warn2>) - <comment>
  3       final long results[] = new long[CYCLES]; // @checkstyle.ignore(ArrayTypeStyle) - A bug in checkstyle.
  4 ...

You can see the output with each build and also by calling mvn checkstyle:check. Checkstyle is configured to just display warnings and not fail the build. A report is created when the site goal is executed. To get just this report call mvn checkstyle:checkstyle.

The resulting report can be found in the target/site/checkstyle.html directory.

2.3.6. License

PerfCake is licensed under Apache License 2.0 and the license text can be found in LICENSE.txt file. license-maven-plugin is used to check that each file has the appropriate header.

  • license:check-file-header Checks the current status of the license header in project files. This goals claims to modify the files but noothing is done in fact. The output is a bit misleading.

  • license:update-file-header Performs the actual update of file headers. Note that we recognize the true license by two hard space characters at the end of some blank lines. Carefully configure your IDE to preserve these.

2.3.7. JaCoCo Code Coverage

JaCoCo is configured to use a Java Agent so no class instrumentation is neede. The agent is automatically switched on for running tests. The only goal needed is report generation (jacoco:report) which must be done together or after test execution.

The resulting report can be found in the target/site/jacoco directory.

2.3.8. FindBugs Report

We use FindBugs to warn us about bad code practices. To obtain the report execute the findbugs:findbugs goal. FindBugs works with the compiled classes, so for a fresh report, the compile target must be invoked.

To inspect the code on the fly, run the findbugs:gui tool. Please note that it only shows the data from the previous analysis run.

2.3.9. Digital Signatures

To sign the artifacts created by the package goal, one need to run the gpg:sign goal. The resulting signatures accompany the files in the target directory.

2.3.10. Distribution

To create the archived distributions we offer for download at our website, simply run the assembly:single goal. Its output can be found in the target directory as usually.

2.3.11. Transformation of Scenarios

It is possible to automatically transform scenarios from previous versions of PerfCake into the newest one. There are XSTL stylesheets included and they can be used by invoking the xml:transform goal and specific profile (see below).

There are properties that can be used to control the transformation. They are described in the following table.

It is currently possible to automatically migrate from version 2 to 3, and from version 4 to 5. The Maven profiles are correspondingly named 2-to-3, and 4-to-5. The migration is started by invoking:

$ mvn xml:transform -P 2-to-3 -Dtransform.scenarios.dir=<source scenarios dir> \
      -Dtransform.scenarios.outputDir=<target scenarios dir>

Both directories must exist before starting the migration. All XML scenarios found in the directories are transformed.

Property nameDescriptionRequiredDefault value
transform.scenarios.dirAn input directory where the XML plugin will look for the scenarios to transform.Yes-
transform.scenarios.outputDirAn output directory where the transformed scenarios will be placed.No${project.build.directory}/scenarios

Table 2.1. XML plugin properties