Verify JAX Doclets in Maven builds

In few words, I have a Java REST API that is defined with Jersey.
I use Enunciate to generate a Swagger JSon file. Enunciate uses Javadoc comments (and optionally some annotations) to fill-in the REST documentation. But it also supports JAX doclets for complementary information.

A doclet that is quite useful is the @HTTP one.
This tag allows to define the return codes of a REST operation. And since it makes sense for all the operations of our APIs, I wanted to add an automatic verification at build time. I searched the web for something that could do this with Maven, and after quite a long search, I found the right Checkstyle module for that.

Here is the XML snippet to insert in your POM.

<build>
<plugins>
	<plugin>

		<groupId>org.apache.maven.plugins</groupId>
		<artifactId>maven-checkstyle-plugin</artifactId>
		<version>2.17</version>
		<executions>
			<execution>
				<id>check-rest-resources</id>
				<phase>process-sources</phase>
				<goals>
					<goal>check</goal>
				</goals>
				<configuration>
					<includes>**/I*Resource.java</includes>
					<checkstyleRules>
						
	<module name="Checker">							
		<property name="charset" value="UTF-8" />
		<module name="TreeWalker">
			<module name="WriteTag">
				<property name="tag" value="@HTTP" />
				<property name="tagFormat" value="\S" />
				<property name="severity" value="error" />
				<property name="tagSeverity" value="ignore" />
				<property name="tokens" value="METHOD_DEF" />
			</module>
		</module>
	</module>
								
					</checkstyleRules>
				</configuration>
			</execution>
		</executions>
	</plugin>
		
</plugins>
</build>

So, we use the Maven plug-in for Checkstyle.
This set of rules will only apply to classes whose name is compliant with the I*Resource pattern (this is a convention we use in our project…).

And we use the WriteTag module that verifies if a given tag is used or not in a class. The tag here is @HTTP. If we do not find it (the severity property), we raise an ERROR. If we find it (tagSeverity), we ignore it. And we apply this verification to methods only (not to classes or anything else). You should easily be able to adapt it by reading the documentation of this module.

Github pages, Kramdown, Rouge, Jekyll 3.0: the final struggle

What this is about…

Github has recently announced Github pages was moving to Jekyll 3.0. Beyond better performances, this change also implies renuncing to Redcarpet and Pygments. From now, only Kramdown will be supported as the markdown engine. And Rouge will be the only syntax highlighter to work.

I have started to do the migration.
Unlike what Github indicated, this is far from being that easy. The most difficult part is about updating your local Jekyll installation to verify it works as expected. To be clear, there are still bugs in the last github-pages gem (in its dependencies). However, this article may help you to be as close as possible waiting for the fixes.

Reset your Ruby installation

First, Jekyll 3.0 requires Ruby 2.0 or higher.
If you are on Ubuntu, you will find Debian packages and instructions on this page.

Then, you may suffer from bad interactions with your previous Jekyll install. If you want to start from a brand new point, uninstall all your gems. This can be done in a single command line.

sudo gem list | cut -d” ” -f1 | sudo xargs gem uninstall -aIx

So far, so good.
Now, the best thing to do is to follow Github instructions and let the github-pages gem download the required dependencies. Verify your have a Gemfile file in your site sources with the following content.

source ‘https://rubygems.org’
gem ‘github-pages’

You may have other gems as well.
Make sure you DO NOT HAVE a Gemfile.lock file in the same directory. If so, delete it. Otherwise, you will keep on downloading the same old gem versions.

Eventually, run sudo bundle install.
This will download github-pages with all the right gems.

Once this is done, update your _config.yml file. Mine used to start with…

encoding: utf-8
markdown: redcarpet
highlighter: pygments
redcarpet:
  extensions: ["tables", "no_intra_emphasis"]

gems: [ "jemoji" ]

Now, it looks like…

encoding: utf-8
markdown: kramdown
highlighter: rouge
kramdown:
  input: GFM
  hard_wrap: false
  syntax_highlighter: rouge

gems: [ "jemoji" ]

And that should do the trick.
OK, on February 12^th, it does not compeletly. First, there is a bug with Jekyll 3.1.1. This is why it is better to use github-pages and not installing directly the Jekyll gem. And then, there is also a bug with with the current github-pages. When using fency code blocks…

```properties
# Here in version %v_SNAP%
key = value
```

… the generated HTML is different from what pygments used to generate. Instead of generating…

<div class="highlight"><pre><code class="language-properties" data-lang="properties"><span class="c"># Here in version 0.5
</span><span class="py">key</span><span class="p"> = </span><span class="s">value</span>
</code></pre></div>
</blockquote>

… it generates…

<div class="highlighter-rouge"><pre><code><span class="c"># Here in version 0.5
</span><span class="py">key</span><span class="p"> = </span><span class="s">value</span>
</code></pre></div>
</blockquote>

The language-properties CSS class disappears.
According to this topic, this is fixed in Jekyll 3.1.2. So, let’s wait for it!

Edit from March 4^th: in fact, it is a current limitation of Rouge. See jneen/rouge#379 for more details.

REST upload to Bintray

I am feeling lazy tonight.
So, this blog post will just be about referencing keywords and pointing out to sample resources.

Bintray provides a web interface to manage repositories, versions, files and so on. It also provides a REST API which is documented on this page. This documentation is useful. However, associated examples are always helpful.

Anyway, I had to complete scripts so that they upload our releases to Bintray (essentially, our Debian packages and our Eclipse update site). So, if you are in the same case, you might be interested to see these examples about file upload at Bintray.

• Upload a ZIP file and unzip it (Eclipse update site). The upload part is at the end of the script.
• Upload Debian packages. The upload part is at the end of the script.
• Upload RPM packages (I did not write this one but I found it useful).