Automatic verification of JavaDoc with Maven - java

During refactoring it happens frequently that JavaDoc gets out-of-date. It describes method arguments which are not present any more or some new ones are missing, to give examples.
It would be fine, if there is a Maven-plugin which automatically checks the existing JavaDoc and stops the build if there are some kind of "JavaDoc-violations".
I've seen the Maven-JavaDoc-Plugin and maven-doccheck, but both seem only to be able fix existing JavaDoc automatically in case of violations instead of bailing some error or warning.
Does anyone know how if there is some Maven-plugin like this and how to archive this?

As far as I know this is currently not possible with the maven-javadoc-plugin. There is the javadoc:fix mojo for the JavaDoc plugin, but this automatically fixes problems.
I recently created a JIRA entry for this problem: MJAVADOC-374 (which is acutally a duplicate of MJAVADOC-314).
Update:
You can use Checkstyle to verify correct JavaDoc. The configuration options are described here. Use the maven-checkstyle-plugin and the check-Mojo to integrate this into your maven build.
An example maven configuration could look like this:
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>2.15</version>
<configuration>
<logViolationsToConsole>true</logViolationsToConsole>
<checkstyleRules>
<module name="JavadocMethod">
<property name="scope" value="public"/>
<property name="allowUndeclaredRTE" value="true"/>
<property name="allowMissingParamTags" value="false"/>
</module>
</checkstyleRules>
</configuration>
</plugin>
</plugins>
</build>
...
</project>

Related

How do increase the number of nested if else statements allowed by maven

I have written my code to search if a node can be reached in a graph using java. I don't to change my code. I am using maven. When I try to compile it's giving me the error below.
[INFO] There is 1 error reported by Checkstyle 8.29 with com/github/ngeor/checkstyle.xml ruleset.
[ERROR] src/main/java/dsa/graphs/Graph.java:[160,25] (coding) NestedIfDepth: Nested if-else depth is 2 (max allowed is 1).
How do I get around this. I don't want to disable checkstyle at the same time I don't want to change my code. How can I increase that number to be more than 1.
I am presuming that you have the checkstyle under com.github.ngeor package so just go to the file and change/add
<module name="NestedIfDepth">
<property name="max" value="{AS_MUCH_AS_YOU_WANT}"/>
</module>
Or if you are referencing a checkstyle that is not under your control you can also override it.
Add the checkstyle plugin to your pom:
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>3.1.1</version>
<configuration>
<configLocation>checkstyle.xml</configLocation>
<suppressionsLocation>checkstyle-suppressions.xml</suppressionsLocation>
<suppressionsFileExpression>checkstyle.suppressions.file</suppressionsFileExpression>
</configuration>
</plugin>
</plugins>
And of course you need to create checkstyle-surpressions.xml file:
<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
"-//Checkstyle//DTD SuppressionFilter Configuration 1.0//EN"
"https://checkstyle.org/dtds/suppressions_1_0.dtd">
<suppressions>
<suppress checks="NestedIfDepth"
files="Graph.java"
lines="{what_Lines_you_need}"/>
</suppressions>
This will

Testing with Arquillian, how to share Arquillian.xml?

How can the Arquillian configuration file Arquillian.xml be shared between projects and team members?
<arquillian xmlns="http://jboss.org/schema/arquillian"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://jboss.org/schema/arquillian
http://jboss.org/schema/arquillian/arquillian_1_0.xsd">
<container qualifier="jbossas-managed-wildfly-8" default="true">
<configuration>
<property name="jbossHome">C:\test\wildfly-8.1.0.Final</property>
<property name="javaVmArguments">-Djboss.socket.binding.port-offset=2 -Xmx512m -XX:MaxPermSize=128m</property>
<property name="managementPort">9992</property>
</configuration>
</container>
The problem is this points to specific locations on the the disk, and different team members use Wildfly in different locations.
In addition we must duplicate Arquillian.xml for each project that uses it.
We use Arquillian for Maven testing (which could inject the values) and JUnit tests within Eclipse (which cannot inject them).
Any ideas how to do this?
Since there is already Maven support and structure then you can make use of Maven properties and replace of place holder values. It is simple
I guess your Arquillian.xml is under src/test/resources/arquillian.xml right? Then you can replace the absolute values with properties.
<configuration>
<property name="jbossHome">${jboss.home}</property>
</configuration>
The above property can be either defined in the properties section of your pom or can be overridden during mvn executuon using -Djboss.home=C:\myPath
In order though this thing to work, you want Maven automatically for each developer when is about to package arquillian.xml to replace this place-holder ${jboss.home} with a value, that we have either defined on top in the properties section or we have passed it from the command line. This is done through the resource filtering functionality
<build>
<testResources>
<testResource>
<directory>src/test/resources</directory>
<filtering>true</filtering>
</testResource>
<testResources>
</build>
See the simple examples here

Debug Arquillian tests in IntelliJ

I have Java EE project in which I use Arquillian tests with JUnit on JBoss 7 (Windows). Tests are working fine however I cannot debug them.
From what I've googled (https://community.jboss.org/wiki/WhyDontBreakPointsWorkWhenDebugging) I understand that Arquillian tests are being run in separate VM therefore IntelliJ cannot debug them. I need IntelliJ to connect to that machine remotely over socket but I dont know how to do it.
I found this thread: Debugging with Arquillian in IntelliJ - Managed Container However I dont know how to get it work.
Also I stepped over this thread: http://devnet.jetbrains.com/message/5253623?tstart=0 so I filled hopefully appropriet surefire part in my pom.xml but it didnt help:
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.4.3</version>
<configuration>
<debugForkedProcess>true</debugForkedProcess>
<skip>false</skip>
</configuration>
</plugin>
Could anyone guild me please how to debug tests in such configuration?
First of all depend on the container type you are using - managed, remote or embedded. See also https://docs.jboss.org/author/display/ARQ/Containers. For the latter the tests are running in the same JVM and you can for example debug your test directly in the IDE.
The Surefire configuration is in this case not important, because you want to debug in your IDE (unless you are executing maven goals from within your IDE).
For managed and remote containers you need to debug the actual container. For this to wrok you have to pass the right JVM options to the remote container, so that you can open a remote debugging session. One way of doing this is via arquillian.xml:
http://jboss.org/schema/arquillian/arquillian_1_0.xsd">
<!-- Need to set the default protocol and use resource filtering, because of https://issues.jboss.org/browse/ARQ-579 -->
<defaultProtocol type="Servlet 3.0"/>
<engine>
<property name="deploymentExportPath">target/artifacts</property>
</engine>
<container qualifier="incontainer">
<configuration>
<property name="jbossHome">${jbossTargetDir}</property>
<property name="javaVmArguments">-Xmx1024m -XX:MaxPermSize=512m -Xnoagent -Djava.compiler=NONE -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005</property>
<property name="allowConnectingToRunningServer">true</property>
</configuration>
</container>
The important part in the example above being the javaVmArguments.
I can run Arqullian tests by either Maven or by IntelliJ. I use embedded container. The most important thing is to configure the JBoss home at arqullian.xml nor just at the Maven configuration to IntelliJ know where the JBoss home is.
<arquillian xmlns="http://jboss.org/schema/arquillian"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://jboss.org/schema/arquillian
http://jboss.org/schema/arquillian/arquillian_1_0.xsd">
<engine>
<property name="deploymentExportPath">testing/target/artifacts</property>
</engine>
<container qualifier="jbossas-managed" default="true">
<configuration>
<!-- JBoss embedded does not use this property
<property name="javaVmArguments">-java.util.logging.manager=org.jboss.logmanager.LogManager -Xmx512m -XX:MaxPermSize=256m -Djava.util.logging.manager=org.jboss.logmanager.LogManager</property>
-->
<property name="jbossHome">target/wildfly-8.1.0.Final</property>
<property name="modulePath">target/wildfly-8.1.0.Final/modules</property>
<property name="allowConnectingToRunningServer">true</property>
</configuration>
</container>
IMPORTANT for debugging and running test in IntelliJ:
From some reason you must specify the logging manager to be able run embedded JBoss. For Maven it is easy and you can set it to configuration:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<!-- Fork every test because it will launch a separate AS instance -->
<forkMode>always</forkMode>
<systemPropertyVariables>
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
</systemPropertyVariables>
<redirectTestOutputToFile>false</redirectTestOutputToFile>
</configuration>
</plugin>
But the IntelliJ does not care about these plugin configuration at Maven and you must set it directly at the test case configuration. I did not find better solution. The embedded container does not care about Java VM configuration in arqullian.xml.
Here is always possibility to debug throught remote debugging. I like to do it at IDE. For me it is more confortable way. When you want to enable remote debugging you must set configuration to JAVA_OPT for embedded container nor at arqullian.xml.

Supporting i18n in GWT

Till now, our web application supports only English. Now we have to provide support for Italian as well. There is GWT module for some functionality. To support the Italian language I have added below line in the file "APP_Module.gwt.xml"
<extend-property name="locale" values="it"/>
I have also placed "XXX_it.properties" file under the source code where the properties file for en is kept.
Setting the locale in the jsp by following line:
<meta name="gwt:property" content="locale=${locale}">
Now, the issue is how to compile the code. I am debugging the application but it is not hitting the client code of GWT presented under WEB-INF/src.
I am very new to GWT. Please suggest how can I compile the code or there is no need of compilation. It will automatically take the changes done in "APP_Module.gwt.xml" and there is some other issue. How can I see logs of GWT?
To add support for locales to GWT application, you need to do the following in your xxx.gwt.xml:
under <module> add this to include the support:
<inherits name="com.google.gwt.i18n.I18N" />
and this to configure it:
<extend-property name="locale" values="en,it"/>
<set-property-fallback name="locale" value="en"/>
Add all your property files under some package like this:
src/main/resources/foo/bar/client/i18n/MyMessages.properties
src/main/resources/foo/bar/client/i18n/MyMessages_it.properties
Then you need to tell GWT to compile them into classes. This is example from a pom.xml file (if you don't use maven, you will have to use a different way, but you still need to configure it).
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>gwt-maven-plugin</artifactId>
<version>1.3.1.google</version>
<executions>
<execution>
<goals>
<goal>i18n</goal>
<goal>generateAsync</goal>
<goal>compile</goal>
</goals>
</execution>
</executions>
<configuration>
<i18nMessagesBundles>
<resourceBundle>foo.bar.client.i18n.MyMessages</resourceBundle>
</i18nMessagesBundles>
</configuration>
</plugin>
Then you need to recompile the code. In maven mvn compile. And that's all, you will have your messages in generated sources folder ready to use.
For seeing the logs of gwt you can use gradlew gwt also you can use it to compile the code too.

In the Eclipe PMD plugin, can I reference the standard ruleset files?

I would like my eclipse PMD plugin configuration to access the same standard ruleset files as the maven-pmd-plugin.
You can configure the maven pmd plugin to use a custom set of rule sets like this:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<version>2.5</version>
<configuration>
<rulesets>
<!-- Two rule sets that come bundled with PMD -->
<ruleset>/rulesets/braces.xml</ruleset>
<ruleset>/rulesets/naming.xml</ruleset>
<!-- Custom local file system rule set -->
<ruleset>d:\rulesets\strings.xml</ruleset>
<!-- Custom remote rule set accessed via a URL -->
<ruleset>http://localhost/design.xml</ruleset>
</rulesets>
</configuration>
</plugin>
but in the eclipse plugin you can only switch on / turn off individual rules or specify a single ruleset file. Is there perhaps a way that ruleset file can include several others? Or do I have to aggregate that file automatically from the rulesets I want to use?
You can include other rulesets in a PMD ruleset file, e.g.
<ruleset ...>
...
<rule ref="rulesets/basic.xml"/>
...
<rule ref="rulesets/strings.xml">
<exclude name="AvoidDuplicateLiterals"/>
</rule>
...
</ruleset>
This is actually an excerpt from our own ruleset file, so it is proven to work :-)
As you can see, you can exclude/include individual rules from your ruleset, or even reconfigure them. One caveat: you must not mix rules for different languages in a single ruleset. I.e. in our case, we had to create separate rulesets for Java and JSP.
I learned the tricks myself from this page.

Categories