Configuring Javadoc aggregation in Maven - maven

I'm trying to create an aggregate Javadoc site for all the modules in my project, but I can't seem to configure the plugin in a way that is satisfactory. Mainly, I can't seem to get it to aggregate the javadocs all the while detecting links and excluding certain packages. Essentially, it appears the configuration of the plugin is ignored entirely.
I have a root pom.xml that refers to a bunch of submodules and contains the following configuration:
<modules>
<module>foo</module>
<module>bar</module>
</modules>
<build>
<plugins>
<plugin>
<groupId>org.maven.apache.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<executions>
<execution>
<id>aggregate</id>
<phase>site</phase>
<goals>
<goal>aggregate</goal>
</goals>
<configuration>
<links>
<link>http://docs.oracle.com/javase/6/docs/api</link>
<link>http://static.netty.io/3.5/api</link>
<link>http://google-guice.googlecode.com/git/javadoc</link>
<link>http://docs.guava-libraries.googlecode.com/git-history/release/javadoc</link>
<link>http://fasterxml.github.com/jackson-databind/javadoc/2.0.4</link>
<link>https://developers.google.com/protocol-buffers/docs/reference/java</link>
</links>
<bootclasspath>${sun.boot.class.path}</bootclasspath>
<additionalJOption>-J-Xmx1024m</additionalJOption>
<detectJavaApiLink>true</detectJavaApiLink>
<detectLinks>true</detectLinks>
<excludePackageNames>*.testing.*</excludePackageNames>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
But when I run mvn javadoc:aggregate with this setup, I end up with a javadoc site that has no links to any of the referenced libraries and still includes all the testing classes.
I don't even see the plugin attempting to download the package-list for each declared link source.
On the other hand, generating the javadoc for each individual module works well and as expected.
What am I getting wrong?

Plugin configurations can be placed on two levels; inside the execution tag or outside of it ("global").
When the configuration is inside the execution tag it belongs to that particular execution. In your case you will have to run mvn site for it to execute since it is bound to that phase.
When the mvn javadoc:aggregate command is used it looks for the "global" configuration. In your pom there is no such configuration and thus it uses the default configuration.
Change your plugin configuration to this instead:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<configuration>
<links>
<link>http://docs.oracle.com/javase/7/docs/api</link>
<link>http://static.netty.io/3.5/api</link>
<link>http://google-guice.googlecode.com/git/javadoc</link>
<link>http://docs.guava-libraries.googlecode.com/git-history/release/javadoc</link>
<link>http://fasterxml.github.com/jackson-databind/javadoc/2.0.4</link>
<link>https://developers.google.com/protocol-buffers/docs/reference/java</link>
</links>
<bootclasspath>${sun.boot.class.path}</bootclasspath>
<additionalJOption>-J-Xmx1024m</additionalJOption>
<detectJavaApiLink>true</detectJavaApiLink>
<detectLinks>true</detectLinks>
<excludePackageNames>*.testing.*</excludePackageNames>
</configuration>
<executions>
<execution>
<id>aggregate</id>
<phase>site</phase>
<goals>
<goal>aggregate</goal>
</goals>
</execution>
</executions>
</plugin>
You can place a configuration inside the execution part to override and specialize the configuration for that execution.
BTW The <groupId> is wrong in your pom. It should be
<groupId>org.apache.maven.plugins</groupId>
and not
<groupId>org.maven.apache.plugins</groupId>

Related

Using sonar.test.exclusions with Sonarqube 6.3

I'm currently evaluating Sonarqube 6.3 (a big upgrade from my current 5.5 instance) and I'm getting confused trying to work out the functionality of the sonar.test.exclusions setting.
There's this question: Sonar Maven Plugin: How do I exclude test source directories? which seems to indicate that it is used to exclude test files from analysis (which is what I'm after - I don't want my sonar ruleset run over my unit tests). The documentation https://docs.sonarqube.org/display/SONAR/Narrowing+the+Focus also indicates that it is used to 'exclude unit test files' (perhaps this can be expanded upon to make it clearer?)
Thing is, when I add sonar.test.exclusions with a value of **/src/test/** and then run my analysis, I'm still getting code smells and the like being found for:
Foo/src/test/java/foo/bar/BarTest.java
Foo/src/test/java/lah/LahTest.java
etc.
When I use sonar.exclusions instead, they don't show up. Why is sonar.test.exclusions not doing what I expect?
First of all: if you have a Maven project, you should use the scanner for Maven (mvn sonar:sonar). It will simplify your configuration, and will automatically register src/test/java folder as a test directory.
Now if you want to do the configuration manually, or understand what is going on under the hood, here is the explanation: SonarQube scanner work with 2 sets of files, main and test. Main source files are configured using the property sonar.sources. Test source files are configured using sonar.tests.
On top of that, you can filter some content using the sonar.[test.]exclusions properties.
In you case your problem is that Foo/src/test/java/foo/bar/BarTest.java seems to be considered as a main source file. That's why sonar.test.exclusions has no effect.
Using maven with verfication goal (mvn clean verify sonar:sonar install), I have used this configuration without problems:
...
<properties>
....
<sonar.exclusions>
**/generated/**/*,
**/model/**/*
</sonar.exclusions>
<sonar.test.exclusions>
src/test/**/*
</sonar.test.exclusions>
....
<sonar.java.coveragePlugin>jacoco</sonar.java.coveragePlugin>
<sonar.jacoco.reportPath>${project.basedir}/../target/jacoco.exec</sonar.jacoco.reportPath>
<sonar.coverage.exclusions>
**/generated/**/*,
**/model/**/*
</sonar.coverage.exclusions>
<jacoco.version>0.7.5.201505241946</jacoco.version>
....
</properties>
....
Coverage exclusion configuration, inside properties (up) and jacoco plugin configuracion:
.....
<build>
<plugins>
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>${jacoco.version}</version>
<executions>
<execution>
<id>prepare-agent</id>
<goals>
<goal>prepare-agent</goal>
</goals>
</execution>
<execution>
<id>report</id>
<phase>prepare-package</phase>
<goals>
<goal>report</goal>
</goals>
</execution>
<execution>
<id>post-unit-test</id>
<phase>test</phase>
<goals>
<goal>report</goal>
</goals>
<configuration>
<dataFile>target/jacoco.exec</dataFile>
<outputDirectory>target/jacoco-ut</outputDirectory>
</configuration>
</execution>
</executions>
<configuration>
<systemPropertyVariables>
<jacoco-agent.destfile>target/jacoco.exec</jacoco-agent.destfile>
</systemPropertyVariables>
</configuration>
</plugin>
</plugins>
</build>
....

IOException thrown when processing xsd dependencies in maven

I have a problem while processing .xsd file during my maven build.
I use jaxb2 plugin but I have to download external dependiencies from my .xsd files. The problem is that these dependencies (.xsd) are from enviroment which is unstable and very often my build fails because maven cannot download xsd file. How to configure jaxb plugin to force him to try download xsd few times to prevent build failure?
Part of my pom.xml configuration:
<plugins>
<plugin>
<groupId>org.jvnet.jaxb2.maven2</groupId>
<artifactId>maven-jaxb2-plugin</artifactId>
<configuration>
<strict>false</strict>
<extension>true</extension>
<args>
<arg>-Xfluent-api</arg>
<arg>-XtoString</arg>
<arg>-Xsetters</arg>
<arg>-XenumValue</arg>
</args>
<plugins>
<plugin>
<groupId>net.java.dev.jaxb2-commons</groupId>
<artifactId>jaxb-fluent-api</artifactId>
<version>${jaxb.fluentapi.version}</version>
</plugin>
<plugin>
<groupId>org.jvnet.jaxb2_commons</groupId>
<artifactId>jaxb2-basics</artifactId>
<version>0.9.3</version>
</plugin>
</plugins>
<bindingDirectory>src/main/resources/jaxb</bindingDirectory>
<bindingIncludes>
<include>bindings.xml</include>
</bindingIncludes>
<schemas>
<schema>
<fileset>
<!-- Defaults to schemaDirectory. -->
<directory>${project.basedir}/src/main/resources/orbeons</directory>
<!-- Defaults to schemaIncludes. -->
<includes>
<include>*.xsd</include>
</includes>
</fileset>
</schema>
</schemas>
</configuration>
<executions>
<execution>
<phase>generate-resources</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<executions>
<execution>
<id>add-source</id>
<phase>generate-sources</phase>
<goals>
<goal>add-source</goal>
</goals>
<configuration>
<sources>
<source>${project.basedir}/generated-sources/orbeons</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
Author of the maven-jaxb2-plugin here.
You have two parts here: managing the downloads of external resources and compiling the schemas, rewriting "external" links to local files.
The first (managing downloads) is not in the scope of the maven-jaxb2-plugin, the second is supported with
catalogs.
In short, you can create a catalog file like this:
REWRITE_SYSTEM "http://www.w3.org" "w3c"
Or this:
REWRITE_SYSTEM "http://schemas.opengis.net" "maven:org.jvnet.ogc:ogc-schemas:jar::!/ogc"
And use this file to "rewrite" absolute links to local files or resources within Maven artifacts:
<configuration>
<catalog>src/main/resources/catalog.cat</catalog>
</configuration>
As for the first part, I don't think managing downloads with retries, continuations and all other stuff should be in the scope of the JAXB2 Maven plugin.
ps. You don't need build-helper-maven-plugin/add-source with maven-jaxb2-plugin, source directory is added automatically.
Apparently the maven-jaxb2-plugin does not support such a feature. (And neither does the maven-download-plugin nor even the maven-dependency-plugin).
Three solutions come into my mind at the moment (plus two and a half inspired by LIttle Ancient Forest Kami's comment) [Numbers reflect the precedence of what I would do]:
Use a CI tool (Jenkins, etc.) that supports retry on job failure. [1]
Handmade:
Use the GMavenPlus plugin with a script ... [2]
Use the Maven AntRun plugin with a script ... [3]
Use the Exec Maven plugin with a program ... [5]
... that performs the download and retry and bind it to the generate-resources phase in your project's POM.
Create a Maven plugin with appropriate parameters (url, outputDirectory, retryCount) that uses the maven-download-plugin and performs the retry. Bind its goal to the generate-resources phase in your project's POM. [4]
Create a check-download Maven project that uses the maven-download-plugin bound to the generate-resources phase to download the .xsd. [6]
Create a shell script that contains the following (in pseudo code):
download:
counter++
<check-download project>/mvn generate-resources
if error and counter < maxRetryCount goto download
if not error
<your project>/mvn ...
else
display appropriate error message
There is also a question Maven download retry? from 2005. Unanswered.

Build a site zip with Maven

actually, I generate a maven site containing the documentation of my project. It works very well, in fact if works so well that my customers wants to get that site as a deliverable (for obvious documentation purpose).
How can I tell Maven to build a zip of the whole site and deploy it to my artifacts manager (Nexus)? I've tried several things, but if I understand correctly, deploying artifacts and generating the site are using different livecycle, and the site generation occurs after the deployment of the artifacts..
I could obviously get the generated site from the location it's deployed during site-deploy, but I would greatly appreciate an automatic and centralized way...
PS: giving access to the customer to our internal site is NOT an option.
Here is a working solution delegated to a Maven profile to isolate the behavior (and speed-up normal builds), but which could also be integrated in the default build if required (although not recommended).
<profiles>
<profile>
<id>site-zip</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.4</version>
<executions>
<execution>
<id>pack-site</id>
<phase>prepare-package</phase>
<goals>
<goal>site</goal>
<goal>jar</goal>
</goals>
<configuration>
<attach>false</attach>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>com.coderplus.maven.plugins</groupId>
<artifactId>copy-rename-maven-plugin</artifactId>
<version>1.0.1</version>
<executions>
<execution>
<id>rename-file</id>
<phase>prepare-package</phase>
<goals>
<goal>rename</goal>
</goals>
<configuration>
<sourceFile>${project.build.directory}/${project.build.finalName}-site.jar</sourceFile>
<destinationFile>${project.build.directory}/${project.build.finalName}-site.zip</destinationFile>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>1.10</version>
<executions>
<execution>
<goals>
<goal>attach-artifact</goal>
</goals>
<phase>package</phase>
<configuration>
<artifacts>
<artifact>
<file>${project.build.directory}/${project.build.finalName}-site.zip</file>
<type>zip</type>
<classifier>site</classifier>
</artifact>
</artifacts>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
What the profile is actually doing:
Configuring an execution of the Maven Site Plugin, attached to the prepare-package phase and running the site and jar goals (as also suggested by #khmarbaise).
Renaming the file from jar to zip via the Copy Rename Maven Plugin
Attaching the zip to the build via the Build Helper Maven Plugin and its attach-artifact goal
As such, running
mvn clean install -Psite-zip
Will also install in your local Maven cache the zipped site. The deploy phase would do the same on your target Maven repository then.
Note that the Maven Site Plugin and the Copy Plugin must be declared in the order above to follow the required flow within the same phase.
Also note that if zip is not a strong requirement, you can then just skip the Copy and Build Helper executions and only use the Maven Site execution. By default the jar created providing the site is already attached to the build (and hence it will be installed and deployed automatically). In order to have the zip, we had to disable this behavior (<attach>false</attach>) and re-attach it via the Build Helper plugin.
The generated zipped has automatically a classifier, which is site in this case.
You can use the maven-site-plugin.

Execute maven plugin goal on specific modules

I have the following situation:
masterpom.xml:
...
<modules>
<module>sample-module</module>
</modules>
...
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>versions-maven-plugin</artifactId>
<version>2.1</version>
<inherited>true</inherited>
<executions>
<execution>
<id>update-parent</id>
<phase>pre-clean</phase>
<goals>
<goal>update-parent</goal>
</goals>
<configuration>
<parentVersion>4.4.2.1</parentVersion>
</configuration>
</execution>
</executions>
</plugin>
...
I would like to execute the versions-maven-plugin's update-parent goal on every module listed between <modules> and </modules>.
How can I do that? This configuration that I already tried doesn't work, because the modules do not inherit from masterpom.xml (they have a different parent which shouldn't be modified).
I also tried running the plugin from the command line:
mvn versions:update-parent "-DparentVersion=[4.4.2.1]"
but the changes will not be limited to the modules I want.
EDIT: running the plugin from the command line at the appropriate location seems to work. I still don't know how to produce the same effect by specifying options inside the POM.

Why doesn't NetBeans IDE see the generated sources?

I have a Maven-built web-app that uses JPA 2.0 at the back end. The JPA provider is EclipseLink 2.3.2.
When I build the project (and it deploys runs successfully) it builds the JPA meta-model in the directory
${basedir}/target/generated-sources/annotations/
Yet the IDE doesn't see the classes defined there. Little red dots with an exclamation point everywhere. Yet I can navigate to those files in the Projects window and open the generated source files.
Does this happen to anyone else and does anyone know of a way to fix it?
UPDATE:
As a work-around I have discovered that I can exit NetBeans, delete the NetBeans cache directory, then restart. This forces NetBeans to rebuild the cache and then the classes become visible again. Should I submit a bug to the NetBeans bug tracker? I can't come up with a test case to make it happen, but it does fairly often.
If you go to project properties/sources there is a note about this: you need to generate sources under
${basedir}/target/generated-sources/FOOBAR
where FOOBAR is the name of your plugin.
After reading #jeqo answer, I tested if, by manually renaming:
"${project.build.directory}/generated-sources/annotations" to ".../generated-sources/hibernate-jpamodelgen"
would make a difference to Nebeans (I'm using v8.2 on ubuntu 16.04).
Everything worked like a charm.
I then modified the pom file as follows:
1) removed the "org.hibernate: hibernate.jpamodelgen" dependency.
2) configured the maven-compiler-plugin as follows:
<plugin>
<groupId>>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.6.1</version>
<configuration>
<compilerArgument>-proc:none</compilerArgument>
</configuration>
</plugin>
These two steps is to make sure that the hibernate-jpamodelgen does
not run on auto-pilot just by adding it in the project dependency
list. Please refer to JPA Static MetaModel Generator doc.
3) added the following plugin with configuration
<plugin>
<groupId>org.bsc.maven</groupId>
<artifactId>maven-processor-plugin</artifactId>
<version>3.2.0</version>
<executions>
<execution>
<id>process</id>
<goals>
<goal>process</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<processors>
<processor>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</processor>
</processors>
<defaultOutputDirectory>${project.build.directory}/generated-sources/hibernate-jpamodelgen/</defaultOutputDirectory>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-jpamodelgen</artifactId>
<version>5.2.9.Final</version>
</dependency>
</dependencies>
</plugin>
This config is directly from the Hibernate JPA Static Metamodel Generator documentation page except for the following line:
<defaultOutputDirectory>${project.build.directory}/generated-sources/hibernate-jpamodelgen/</defaultOutputDirectory>
This line simply generates the metamodel in the directory named after the maven plugin name. From this point, I got all Netbeans references working at design time as if the generated classes were in the src directory subtree.
Hope this helps,
J
Sometimes Netbeans has troubles refreshing. Perhaps clean and rebuild the project and restart Netbeans?
Today I did more experiments on this topic because it is so annoying for me as well. Finally I have realized it is only a problem related how NetBeans deal with indexing classes. This is not a problem of the target directory name and not a problem of the project. It is only NetBeans' mistake. So I have created an issue as well hopefully NetBeans Team can bring the final solution soon. You can see my ticket here https://issues.apache.org/jira/browse/NETBEANS-4191
In my environment the NetBeans 11.3 (x64) with openJDK 1.8.0_242-b08 and apache-maven 3.6.3 version is used under Windows 10 (1607).
But until the final solution arrives here is what I did as a workaround solving the symbol not found problem.
I have added a profile section to my pom file:
<profile>
<id>nb-modelgen-fix</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
<version>3.0.0</version>
<executions>
<execution>
<id>modelgen-touch-files</id>
<phase>install</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<target>
<touch>
<fileset id="model.elements" dir="src/main/java" includes="**/*.java">
<containsregexp expression="(#Entity|#MappedSuperclass|#Embeddable)" casesensitive="yes" />
</fileset>
</touch>
</target>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
I am using the following simple solution to generate the metamodel classes in my project:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<annotationProcessors>
<annotationProcessor>
org.eclipse.persistence.internal.jpa.modelgen.CanonicalModelProcessor
</annotationProcessor>
</annotationProcessors>
<compilerArgs>
<arg>-Aeclipselink.persistenceunits=MY-PU</arg>
</compilerArgs>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
And of course a maven-build-helper adding the generated source folders to the project:
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>3.1.0</version>
<executions>
<execution>
<id>add-source</id>
<phase>generate-sources</phase>
<goals>
<goal>add-source</goal>
</goals>
<configuration>
<sources>
<source>${project.build.directory}/generated-sources/annotations</source>
<source>${project.build.directory}/generated-sources/wsimport</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
And also I have created a file in the same place where the pom.xml is located called nbactions.xml with the following content (to activate this profile in NetBeans IDE only)
<?xml version="1.0" encoding="UTF-8"?>
<actions>
<action>
<actionName>rebuild</actionName>
<packagings>
<packaging>*</packaging>
</packagings>
<goals>
<goal>clean</goal>
<goal>install</goal>
</goals>
<activatedProfiles>
<activatedProfile>nb-modelgen-fix</activatedProfile>
</activatedProfiles>
</action>
</actions>
What it does? When you execute the "Clean and Build" action in NetBeans IDE it activates a task (implemented easily with maven-antrun-plugin) which just a simple touch on all JPA annotated with #Entity, #MappedSuperClass or #Embeddable theese are the sources for the metamodel generations. I have attached this task to the install phase but it worked as well in other phases as well. It lookes that this way NetBeans wake up and makes for the missing indexes for the metamodel classess.
You can read more on this in my NetBeans' issue ticket.
I hope this can save time for anybody else.
If you are using jaxws then make sure you add a <sourceDestDir> node to the <configuration> section of the jaxws plug-in "artifact" in the appropriate pom. For example:
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>jaxws-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>dojaxws</goal>
</goals>
<configuration>
<sourceDestDir>${project.build.directory}/generated-sources/jaxws</sourceDestDir>
....
</configuration>
</execution>
</executions>
<configuration>
<wsdlDirectory>src/main/resources/com/mystuff/ws</wsdlDirectory>
<bindingDirectory>src/jaxws/binding</bindingDirectory>
<target>2.0</target>
</configuration>
</plugin>
As explained above and as noted by netbeans, you must use the generate-sources path appended with the "plug-in" name. Hopefully the above clears up what "plug-in name" means and how exactly one is supposed to get jaxws to put the generated sources where netbeans need them to be. Clearly the "configuration" section will be different for each plugin... The node <sourceDestDir> is needed for jaxws, other plugins may use something else.
For me it worked after I added <endorsed.dir>${project.build.directory}/endorsed</endorsed.dir> to the <properties> of the pom.xml, e.g.:
<properties>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
<endorsed.dir>${project.build.directory}/endorsed</endorsed.dir>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<jakartaee>8.0</jakartaee>
</properties>
But I have no explanation why.

Resources