Mainly Spring/Java and Java JEE tips and tutorials based on what i'm working on, usually (Spring, MongoDB, Spring boot, Big Data, Cassandra etc.) or what interests me.
Occasionally some gadget tips.
It's not uncommon to need a custom packaging or assembly for a given project for some reason or another, this can be accomplished in a certain number of ways
Recently I needed an application to be packaged as the following structure :
The Assembly Plugin for Maven is primarily intended to allow users to aggregate the project output along with its dependencies, modules, site documentation, and other files into a single distributable archive.
Your project can build distribution assemblies easily, using one of the convenient, prefabricated assembly descriptors.
These descriptors handle many common operations, such as packaging a project's artifact along with generated documentation into a single ZIP archive. Alternatively, your project can provide its own descriptor and assume a much higher level of control over how dependencies, modules, file-sets, and individual files are packaged in the assembly.
Currently the plugin can create distributions in the following formats:
zip
tar
tar.gz
tar.bz2
jar
dir
war
format that the ArchiveManager has been configured
For this tutorial we will be using the dir format in order to output the project structure described above
Let's start with the easy part first, the maven assembly plugin configuration where we will tell the plugin where to find our assembly file and where to output the result of the assembly operation
Now since in our case we want all the files in the resource directory to be handled by the assembly plugin we will configure the maven resources plugin to ignore everything inside the resources folder (please note that this is an optional step and it might not apply to your project)
...
${basedir}/src/main/resources**/**
...
Once the maven part is done we can get started with the core code
If you remember we will end up with a runnable JAR file so go ahead and create a Main class like so :
package com.ufasoli.maven.custom.assembly;
/**
* User: Ulises Fasoli
* Date: 23.06.2014
* Time: 18:03
* Project : maven-custom-assembly
*/
public class Main {
public static void main(String[] args) {
System.out.println("HELLO WORLD !");
}
}
Since this is going to be a runnable JAR file we will need to configure the maven JAR plugin to generate the manifest file with our main class
4. Additional cool formatting elements and content
There are plenty of nice cheat-sheets out there that resume much better all the cool stuff you can do with (see 5. Some useful links) so I will just list here a few tips to get you started
4a. Asciidoc files inclusion or composition
Personally when writing documentation I like to create a separate file for each topic and then include them in an a big index file (you can do this otherwise if you prefer) this can easily be done using the include macro
Let's create a new Asciidoc page named topic1 and add some content to it
= Topic 1
== Intro
This page describes some information related to topic1
and now include the newly created page using the include macro
= Asciidoctor hello world
include::topic1.ad[]
After re-compiling the code you should end up with the content of the file topic1.ad inside the index.html file
4b. Table of contents (TOC)
Asciidoctor has a lot of macros and attributes that help you when writing documentation, the full list of attributes can be found here
Attributes are configured as child tags of the attributes XML tag under the maven asciidoctor plugin. To enable the table of contents while providing a TOC level we will use the toclevels attribute, since once you start writing a lot of documentation you could end up with a pretty big HTML document it's a good idea to enable the creation of anchors using the setanchors attribute
Once you configured the maven plugin it's time to add the :toc: attribute to the index.ad header
Please be aware within the the first lines of a document known as document header spacing and markup are important as they have special meaning and are handled differently by the asciidoc parsing engine
, for more information on the document header please check the documentation here
= Asciidoctor hello world
:toc:
include::topic1.ad[]
Once the documentation files generated the result should be pretty close to the one in the picture below :
Please note : Not all attributes are supported through the maven asciidoctor plugin so you have to play a bit with the maven configuration to see which ones are supported.
4c. Adding images in your documentation
Everyone knows a picture is worth 1000 words so why don't add some pretty pictures to your documentation
By default when generating the documentation files containing images the asciidoctor plugin will prefix all image paths with images/ this of course can be changed but I usually leave it with the default option
We will now add an images folder to our maven project under src/main/resources/images and put an image of your choice inside of it in my case asciidoc-logo.png
Once this is done let's add our image to our document
= Topic 1
== Intro
This page describes some information related to topic1.
Asciidoc is cool
image::asciidoc-logo.png[Asciidoc logo]
Now we have included an image in our doc file but we're not done yet, you need to instruct maven to copy our images folder to the generated-docs target folder
Code syntax highlighting is very important when writing documentation since it helps with the readability. Asciidoc currently supports 4 frameworks to handle your code highlighting
coderay
prettify
highlightjs
pygments (not currently supported by maven asciidoctor plugin)
For this tutorial let's say we will use coderay so we first need to activate the syntax highlighting in the maven POM file :
Once our maven configuration is done we can add some source code to our docs, the syntax is pretty straightforward in it's most basic form you just put [source, language] and you surround your code with ---- like so :
[source,java]
----
public class HelloWorld{
public static void main(String[] args){
System.out.println("Hello World");
}
}
----
Once your docs file regenerated you should see something like this :
4e. External links (target _blank)
Whenever I'm reading an HTML documentation containing a link I prefer it when the link opens automatically in a new tab i.e.target="_blank"
This can be achieved using link attributes however by default in Asciidoc this feature is disabled; luckily you just need one small line in your pom.xml file to enable this feature with an attribute
For some time now I have been hearing a lot aboutAsciiDoc as a mean to write documentation but never had the chance to use it...
Recently I stumbled upon AsciiDoctor and since I was about to begin working on a small project with no previous documentation I thought it was the perfect time to try it out..
Documentation is an important part of a project which more often than we would like gets put aside for a great number of reasons. One of them is that we as developpers tend not to like writing documentation...
0.Intro and scope
In this tutorial I will show you how to integrate Asciidoctor class in your Java project and get you started with a small documentation example as well as some tips such as :
Asciidoc templating using fragments
Generating a TOC (table of contents) for your documentation
Integrating images in your asciidoc files
Code syntax highlighting in your asciidoc files
Making external links (i.e. _target blank)
Please note that I assume you have some knowledge of Asciidoc so I won't delve into much detail regarding Asciidoc
1. What is AsciiDoc ?
AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.
AsciiDoc is highly configurable: both the AsciiDoc source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user.
2. What is Asciidoctor ?
Asciidoctor is a pure Ruby processor for converting AsciiDoc source files and strings into HTML 5, DocBook 4.5 and other formats. It’s published as a RubyGem and is available under the MIT open source license.
I invite you to take a look to this nice presentation by Dan Allen Discover Zen Writing with Asciidoc which gives you a good overview of AsciiDoc
3. First steps and configuration
First things first go ahead and create a simple maven module let's say a simple JAR for example using the maven archetype plugin or using you favorite IDE
Once your maven project is created go ahead and create a folder named asciidoc under src/main this is where we will be putting our Asciidoc files
Let's go ahead and create our first asciidoc file under the folder we just created let's name it index.ad and for the moment keep it simple let's just add the page title
= Asciidoctor hello world
So now with our first asciidoc file let's go ahead and configure maven to parse our documentation files and generate HTML documentation files by using the Maven Asciidoctor plugin
Now if you run a mvn clean compile you will see an index.html that will be generated under the target/generated-docs folder with an output similar to :
So that's it for the first part of this tutorial, you can find the rest tomorrow on part 2
I'm the happy owner of an Intellij Idea licence which I love, and as stated on a recent article I started learning Scala not long ago and I'm having some trouble to feel the SBT love
While playing a bit with Scala/SBT and IntelliJ I realized that the support for it is not great there are a few plugins bundled such as the SBT executor which adds some functionality, but no syntax highlighting for the .sbt files and more importantly no dependency management inside the IDE which for me is a deal breaker (Albeit since I'm pretty new to the Scala world I might be doing it wrong...)
Luckily a few day ago I found this sbt plugin nightly builds which is a new IntelliJ plugin that will add some sugar to your Scala/SBT development such as dependency management.
You will find all the installation instructions in the link above as well as information on the plugin features
Now as stated on the website this plugin is still Alpha so there are still some rough edges and quircks. I for example had the
Error occurred during initialization of VM
Could not reserve enough space for object heap
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.
Consult IDE log for more details (Help | Show Log)
By default all maven projects have a version number that you increase upon releases whether it's a minor or major release.
When you are in a scenario in which you continuously deliver application (for example on a staging server) it's probably a good idea to have some unique build identifier so as to know the exact version that is deployed on the server
Luckily the guys over at codehaus have an app plugin just for that .
This plugins will generate a build identifier each time you compile your maven project and make this identifier available through a maven variable ${buildNumber}
The plugin can generate build numbers in 3 ways :
SCM (my personal favorite)
Sequential build number
Timestamp
Personally I prefer the SCM approach since it's coupled with your commits, and I will here I will be showing how to do that
First you will have to configure the maven scm plugin with your details, otherwise you'll end up with error messages like :
Failed to execute goal org.codehaus.mojo:buildnumber-maven-plugin:1.2:create (default) on project simple-webapp: Execution default of goal org.codehaus.mojo:buildnumber-maven-plugin:1.2:create failed: The scm url cannot be null. -> [Help 1]
Here I'm configuring the plugin with 3 worth noting options
doCheck : Check for locally modified files. If true build will fail if local modifications have not been commited
doUpdate : Update the local copy of your repo. If true the plugin will update your local files with the remote modifications before building
shortRevisionLength : shortens the git revision to the number of characters specified in the tag (5 in our case)
Once everything is configured you will be able to access the ${buildNumber} variable in your pom (even though your IDE might complain that the variable cannot be resolved don't worry it will be there when you package your project)
