Working with Maven

 
     

    You can use the S101Headless utility with Maven.

    Simply add the following to the plugin section of your pom.xml

        <groupId>com.structure101.java</groupId>
    <artifactId>maven-structure101-plugin</artifactId>
    <version>1.1</version>

    The Structure101 Maven plugin is hosted on http://repository.structure101.com. To configure Maven to use Structure101 add the following to your pom.xml file.

            <pluginRepositories>
            <pluginRepository>
                <id>structure101plugin</id>
                <layout>default</layout>
                <url>http://repository.structure101.com</url>
                <releases>
                    <checksumPolicy>warn</checksumPolicy>
                    <enabled>true</enabled>
                    <updatePolicy>never</updatePolicy>
                </releases>
            </pluginRepository>
        </pluginRepositories>
       
            <repositories>
            <repository>
                <id>structure101</id>
                <url>http://repository.structure101.com</url>
                <releases>
                    <checksumPolicy>warn</checksumPolicy>
                    <enabled>true</enabled>
                    <updatePolicy>never</updatePolicy>
                </releases>
            </repository>
        </repositories>

    Goals Overview

    There are six Maven goals defined for Structure101.

    GoalDescription
    publish

    This goal publishes a local Structure101 project as a new snapshot in a central Structure101 repository.
    check-architecture

    It is possible to check for architecture violations (optionally only new) prior to publishing, and if any (new) violations are found, an exception can be raised to break the build and hence abort the publish to the repository. This operation is most likely to be useful when you wish to enforce the defined architecture in a continuous build environment.
    check-xs

    It is possible to check for detrimental XS changes prior to publishing, and if XS is found to be increasing, an exception can be raised to break the build and hence abort the publish to the repository.

    This operation is most likely to be useful when you wish to enforce KALOI (keep a lid on it) in a continuous build environment. KALOI promotes the idea that where a codebase has XS (or not) it is undesirable for items with XS to increase, or to be introduced, even if that codebase has a large accumulative XS value to begin with.
    report-metrics

    It is possible to output the metrics to an XML file.
    report-xs

    Output all XS offenders to an XML file.
    report-summary

    It is possible to generate a report, like the one in Structure101's Overview Perspective.

    Each goal is explained below

    Usage

    The goals of the Structure101 Maven plugin by default execute after the test phase. This can be configured in plugin configuration. However, it is required to run after the compile phase so that Structure101 can perform byte-code analysis.

    Configuring Your Structure101 Maven Plugin

    Setting up license

    The default license directory is the project directory. Although a different license directory can be specified using

    <license-directory>C:\license_directory</license-directory>

    in the plug-in configuration.

    Goal: com.structure101.java:maven-structure101-plugin:publish

    Publishes a local project to a new snapshot in a repository.

    Available arguments include:

    Configuration ParameterRequiredDefault ValueDescription
    repositoryyesnullThe path to the Structure101 Build repository root directory, e.g. c:/repository, /home/usr/x/repository, or, if remote, http://<servernameorip><:portno>/<webappcontext>/data.
    projectno${project.name}The name of the project in the repository to which this snapshot will be published (a new repository project will be created automatically if the named project does not exist)
    local-projectno${build.outputDirectory}See project-spec. Note that the classpath attribute can be optionally overridden. It is required when you have done transformation
    label nohandled by pluginA label for the snapshot, typically the version number. If specified, this must be unique within the repository project. 
    datenoSystem dateA date for the snapshot. If specified, this must be unique within the repository project. The date format is locale-specific.
    Tip: Run the publisher at the command line with no arguments, and the usage output will include an example date for your locale
    rpkeynonullSpecifies the "remote publish key". Necessary if you are publishing to a remote (web) repository that is password-protected
    overwritenofalseIf specified then the existing snapshot label (if entered) is overwritten (saving disk space)
    pom.xml configuration
                    <build>
                    <plugins>
                        <plugin>
                            <groupId>com.structure101.java</groupId>
                            <artifactId>maven-structure101-plugin</artifactId>
                            <version>0.5</version>
                            <configuration>
                            <!-- put your configurations here -->
                                <project>${project.name}</project>
                                <breakOnError>false</breakOnError>
                                <classpath>${build.outputDirectory}</classpath>
                                <date>system time</date>
                                <key></key>
                                <label>1.0.0</label>
                                <localProject>location to .java.hsp file</localProject><overwrite>true</overwrite>
                                <repository>${structure101repository}</repository>
                                <license-directory>${basedir}</license-directory>
                                <rpkey></rpkey>
                            </configuration>
                            <executions>
                                <execution>
                                    <phase>compile</phase>
                                    <goals>
                                        <goal>publish</goal>
                                    </goals>
                                </execution>
                            </executions>
                        </plugin>
                    </plugins>
                </build>
<properties>
    <structure101outputDir>${project.build.directory}\structure101data</structure101outputDir>
    <structure101repository>c:\structure101repo</structure101repository>
</properties>

     

    Goal: com.structure101.java:maven-structure101-plugin:check-architecture

    As part of S101Headless it is possible to check for (optionally only new) architecture violations prior to publishing, and if any (optionally only new) violations are found, an exception can be raised to break the build. and hence abort the publish to the repository. This goal is most likely to be useful when you wish to enforce the defined architecture in a continuous build environment.

    Available arguments include:

    ArgumentRequiredDefault ValueDescription
    repositoryyesnullThe path to the Structure101 Build repository root directory (where architecture diagrams have been published to), e.g. c:/repository, /home/usr/x/repository, or, if remote, http://<servernameorip><:portno>/<webappcontext>/data.
    projectno${project.name}The name of the project in the repository (where architecture diagrams have been published to)
    local-projectno${build.outputDirectory}See project-spec.
    arch-output-file / archoutputfilenonullFile to which violations are recorded to. Stored in CSV format.
    onlyNewnofalseIf set to true, then an exception is only raised if new violations are found when compared to the latest snapshot. If false, then an exception will be raised if ANY violations are found.
    fail-build-on-violationsnofalseIf set to true it will break the build if any violation is found.
    baselinenolatest snapshotIf baseline entered, then that snapshot will be used to determine what violations are new. If not entered, then baseline will be latest snapshot.
    useBaselineTransformsnofalseIf useBaselineTransforms set to true, then the local-project will have its transforms overridden by the baseline’s (where baseline could just be latest by default).
    useBaselineExcludesnofalseIf useBaselineExcludes set to true, then the local-project will have its excludes overridden by the baseline’s.
    pom.xml configuration
                    <build>
                    <plugins>
                        <plugin>
                            <groupId>com.structure101.java</groupId>
                            <artifactId>maven-structure101-plugin</artifactId>
                            <version>0.5</version>
                            <configuration>
                            <!-- put your configurations here -->
                                <project>${project.name}</project>
                                <breakOnError>false</breakOnError>
                                <fail-build-on-violations>false</fail-build-on-violations>
                                <classpath>${build.outputDirectory}</classpath>
                                <localProject>location to .java.hsp file</localProject><overwrite>true</overwrite>
                                <repository>${structure101repository}</repository>
                                <arch-output-file>${structure101outputDir}\arch-violations.csv</arch-output-file>
                            </configuration>
                            <executions>
                                <execution>
                                    <phase>compile</phase>
                                    <goals>
                                        <goal>check-architecture</goal>
                                    </goals>
                                </execution>
                            </executions>
                        </plugin>
                    </plugins>
                </build>
<properties>
    <structure101outputDir>${project.build.directory}\structure101data</structure101outputDir>
    <structure101repository>c:\structure101repo</structure101repository>
</properties>

    Goal: com.structure101.java:maven-structure101-plugin:check-xs

    As part of S101Headless it is possible to check for detrimental XS changes prior to publishing, and if XS is found to be increasing, an exception can be raised to break the build. and hence abort the publish to the repository. This operation is most likely to be useful when you wish to enforce KALOI (keep a lid on it) in a continuous build environment. KALOI promotes the idea that where a codebase has XS (or not) it is undesirable for items with XS to increase, or to be introduced, even if that codebase has a large accumulative XS value to begin with.

    Available arguments include:

    ArgumentRequiredDefaultDescription
    repositoryyesnullThe path to the Structure101 Build repository root directory, e.g. c:/repository, /home/usr/x/repository, or, if remote, http://<servernameorip><:portno>/<webappcontext>/data.
    projectno${project.name}The name of the project in the repository to compare against.
    local-projectno${build.outputDirectory}See project-spec.
    check-xs-output-fileyesnullFile to which XS offenders are recorded to. Stored in XML format.
    baselinenocalculated internallyOptionally specify which snapshot-label to compare against (i.e. the XS offenders persisted for that snapshot).
    pom.xml configuration
                    <build>
                    <plugins>
                        <plugin>
                            <groupId>com.structure101.java</groupId>
                            <artifactId>maven-structure101-plugin</artifactId>
                            <version>0.5</version>
                            <configuration>
                            <!-- put your configurations here -->
                                <project>${project.name}</project>
                                <breakOnError>false</breakOnError>
                                <fail-build-on-violations>false</fail-build-on-violations>
                                <classpath>${build.outputDirectory}</classpath>
                                <localProject>location to .java.hsp file</localProject><overwrite>true</overwrite>
                                <repository>${structure101repository}</repository>
                                <check-xs-output-file>${structure101outputDir}\check-xs.xml</check-xs-output-file>
                            </configuration>
                            <executions>
                                <execution>
                                    <phase>compile</phase>
                                    <goals>
                                        <goal>check-xs</goal>
                                    </goals>
                                </execution>
                            </executions>
                        </plugin>
                    </plugins>
                </build>
<properties>
    <structure101outputDir>${project.build.directory}\structure101data</structure101outputDir>
    <structure101repository>c:\structure101repo</structure101repository>
</properties>

    Goal: com.headway.java:maven-structure101-plugin:report-metrics

    Output the metrics to an XML file.

    Available arguments include:

    ArgumentRequiredDefault ValueDescription
    local-projectno${build.outputDir}See project-spec.
    report-metrics-output-fileyesFile to which metrics are recorded to. Stored in XML format.
    pom.xml configuration
                    <build>
                    <plugins>
                        <plugin>
                            <groupId>com.structure101.java</groupId>
                            <artifactId>maven-structure101-plugin</artifactId>
                            <version>0.5</version>
                            <configuration>
                            <!-- put your configurations here -->
                                <project>${project.name}</project>
                                <breakOnError>false</breakOnError>
                                <fail-build-on-violations>false</fail-build-on-violations>
                                <classpath>${build.outputDirectory}</classpath>
                                <localProject>location to .java.hsp file</localProject><overwrite>true</overwrite>             
                                <report-metrics-output-file>${structure101outputDir}\report-metrics.xml</report-metrics-output-file>
                            </configuration>
                            <executions>
                                <execution>
                                    <phase>compile</phase>
                                    <goals>
                                        <goal>report-metrics</goal>
                                    </goals>
                                </execution>
                            </executions>
                        </plugin>
                    </plugins>
                </build>
<properties>
    <structure101outputDir>${project.build.directory}\structure101data</structure101outputDir>
    <structure101repository>c:\structure101repo</structure101repository>
</properties>

    Goal: com.headway.java:maven-structure101-plugin:report-xs

    Output the XS offenders to an XML file.

    Available arguments include:

    ArgumentRequiredDefault ValueDescription
    local-projectno${build.outputDirectory}See project-spec.
    report-xs-output-fileyesnullFile to which metrics are recorded to. Stored in XML format.
    pom.xml Configuration
    <build>
                    <plugins>
                        <plugin>
                            <groupId>com.structure101.java</groupId>
                            <artifactId>maven-structure101-plugin</artifactId>
                            <version>0.5</version>
                            <configuration>
                            <!-- put your configurations here -->
                                <project>${project.name}</project>
                                <breakOnError>false</breakOnError>
                                <fail-build-on-violations>false</fail-build-on-violations>
                                <classpath>${build.outputDirectory}</classpath>
                                <localProject>location to .java.hsp file</localProject><overwrite>true</overwrite>
                                <report-xs-output-file>${structure101outputDir}\report-xs.xml</report-xs-output-file>
                            </configuration>
                            <executions>
                                <execution>
                                    <phase>compile</phase>
                                    <goals>
                                        <goal>report-xs</goal>
                                    </goals>
                                </execution>
                            </executions>
                        </plugin>
                    </plugins>
                </build>
<properties>
    <structure101outputDir>${project.build.directory}\structure101data</structure101outputDir>
    <structure101repository>c:\structure101repo</structure101repository>
</properties>

    Goal: com.structure101.java:maven-structure101-plugin:report-summary

    it is possible to generate a report, like the one in the Overview perspective.

    Available arguments include:

    ArgumentRequiredDefault ValueDescription
    local-projectno${build.outputDirectory}See project-spec.
    name no${project.name}Project name (only if 2 above)
    output-dir nonaBy default, the report will be generated in your user directory. You can change this with the outdir argument
    overwrite nofalseOverwrite existing files
    xml nofalseTo write XML file in addition to HTML, use the xml argument
    notips notrueTo exclude notes and tips from report (HTML only) use the -notips switch (same as deselecting "show notes and tips" in the overview perspective).
    pom.xml Configuration
                    <build>
                    <plugins>
                        <plugin>
                            <groupId>com.structure101.java</groupId>
                            <artifactId>maven-structure101-plugin</artifactId>
                            <version>0.5</version>
                            <configuration>
                            <!-- put your configurations here -->
                                <project>${project.name}</project>
                                <breakOnError>false</breakOnError>
                                <fail-build-on-violations>false</fail-build-on-violations>
                                <classpath>${build.outputDirectory}</classpath>
                                <localProject>location to .java.hsp file</localProject><overwrite>true</overwrite>
                                <output-dir>${structure101outputDir}</output-dir>
                            </configuration>
                            <executions>
                                <execution>
                                    <phase>compile</phase>
                                    <goals>
                                        <goal>report-summary</goal>
                                    </goals>
                                </execution>
                            </executions>
                        </plugin>
                    </plugins>
                </build>
<properties>
    <structure101outputDir>${project.build.directory}\structure101data</structure101outputDir>
    <structure101repository>c:\structure101repo</structure101repository>
</properties>

    Sample pom.xml

                <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
                <modelVersion>4.0.0</modelVersion>
                <groupId>com.structure101</groupId>
                <artifactId>TestPlugins</artifactId>
                <packaging>jar</packaging>
                <version>1.0-SNAPSHOT</version>
                <name>TestPlugins</name>
                <dependencies>
                    <dependency>
                        <groupId>junit</groupId>
                        <artifactId>junit</artifactId>
                        <version>3.8.1</version>
                        <scope>test</scope>
                    </dependency>
                </dependencies>

                <build>
                    <plugins>
                        <plugin>
                            <groupId>com.structure101.java</groupId>
                            <artifactId>maven-structure101-plugin</artifactId>
                            <version>0.5</version>
                            <configuration>
                            <!-- put your configurations here -->
                                <project>${project.name}</project>
                                <archoutputfile>${structure101outputDir}\arch.xml</archoutputfile>
                                <baseline></baseline>
                                <breakOnError>false</breakOnError>
                                <checkXsOutputFile>${structure101outputDir}\check-xs.xml</checkXsOutputFile>
                                <classpath>${build.outputDirectory}</classpath>
                                <date>system time</date>
                                <failBuildOnViolation>false</failBuildOnViolation>
                                <key></key>
                                <label>1.0.0</label>
                                <localProject>location to .java.hsp file</localProject>
                                <mem>256</mem>
                                <name></name>
                                <notips>false</notips>
                                <offendersOutputFile>${structure101outputDir}\offender.cva</offendersOutputFile>
                                <onlyNew>false</onlyNew>
                                <outdir>${structure101outputDir}</outdir>
                                <outputdir>${structure101outputDir}</outputdir>
                                <overwrite>true</overwrite>
                                <projectMetricOutputFile>${structure101outputDir}\report-metric.xml</projectMetricOutputFile>
                                <repository>${structure101repository}</repository>
                                <reppath></reppath>
                                <rpkey></rpkey>
                                <scriptfile></scriptfile>
                                <simulate></simulate>
                                <xml>true</xml>
                            </configuration>
                            <executions>
                                <execution>
                                    <phase>compile</phase>
                                    <goals>
                                        <goal>publish</goal>
                                        <goal>check-architecture</goal>
                                        <goal>check-xs</goal>
                                        <goal>report-metrics</goal>
                                        <goal>report-summary</goal>
                                        <goal>report-xs</goal>
                                        <goal>retropublish</goal>
                                    </goals>
                                </execution>
                            </executions>
                        </plugin>
                    </plugins>
                </build>

                <pluginRepositories>
                    <pluginRepository>
                        <id>structure101plugin</id>
                        <layout>default</layout>
                        <url>http://repository.structure101.com</url>
                        <releases>
                            <checksumPolicy>warn</checksumPolicy>
                            <enabled>true</enabled>
                            <updatePolicy>never</updatePolicy>
                        </releases>
                    </pluginRepository>
                </pluginRepositories>

                <repositories>
                    <repository>
                        <id>structure101</id>
                        <url>http://repository.structure101.com</url>
                        <releases>
                            <checksumPolicy>warn</checksumPolicy>
                            <enabled>true</enabled>
                            <updatePolicy>never</updatePolicy>
                        </releases>
                    </repository>
                </repositories>
                <properties>
                    <structure101outputDir>${project.build.directory}\structure101data</structure101outputDir>
                    <structure101repository>c:\structure101repo</structure101repository>
                </properties>
            </project>