Tech and Tips

If you are working with OSGi, you are surely using the Maven Bundle Plugin to create your MANIFEST file and jar bundles.

After a while, it can happen that your maven build it getting slower than it should be.
In my case, the "Writing OBR metadata" part of the maven build was clearly to blame.
And this is because it is parsing and updating a file called repository.xml, which gets really big with time.

Solution:
mv ~/.m2/repository/repository.xml ~/.m2/repository/repository.xml.old

Writing documentation like release notes in Word is a pain, especially when you have it within  your project which is under version control.
Diffs between commits are impossible and you risk having 2 people editing the document at the same time and overwriting each others changes (no automatic merge possibility like you have with the code).

The idea is then to use asciidocs to write the documentation and then generate PDF documents from there with some kind of template in order to have a final document which is easy to pass around.

So comes asciidoctor to the rescue, which has a maven plugin allowing us to do everything via maven!

You need this in your pom.xml file:

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <asciidoctor.maven.plugin.version>1.5.3</asciidoctor.maven.plugin.version>
        <asciidoctorj.pdf.version>1.5.0-alpha.11</asciidoctorj.pdf.version>
        <asciidoctorj.version>1.5.4</asciidoctorj.version>
        <jruby.version>1.7.21</jruby.version>
    </properties>

    <build>
        <defaultGoal>process-resources</defaultGoal>
        <plugins>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>${asciidoctor.maven.plugin.version}</version>
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>${asciidoctorj.pdf.version}</version>
                    </dependency>
                    <!-- Comment this section to use the default jruby artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>${jruby.version}</version>
                    </dependency>
                    <!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj</artifactId>
                        <version>${asciidoctorj.version}</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <sourceDirectory>src/main/resources/ReleaseNotes</sourceDirectory>
                    <!-- Attributes common to all output formats -->
                    <attributes>
                        <sourcedir>${project.build.sourceDirectory}</sourcedir>
                    </attributes>
                </configuration>
                <executions>
                    <execution>
                        <id>generate-pdf-doc</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <!-- Since 1.5.0-alpha.9 PDF back-end can use 'rouge' as well as 'coderay' source highlighting -->
                            <sourceHighlighter>rouge</sourceHighlighter>
                            <attributes>
                                <pdf-stylesdir>${project.basedir}/src/main/resources/ReleaseNotes/themes</pdf-stylesdir>
                                <pdf-style>my-theme</pdf-style>
                                <icons>font</icons>
                                <tabsize>4</tabsize>
                                <pagenums/>
                                <toc/>
                                <idprefix/>
                                <idseparator>-</idseparator>
                            </attributes>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

If you have an image in src/main/resources/ReleaseNotes/images/image1.png and a theme in src/main/resources/ReleaseNotes/themes/my-theme.yml like this

title_page:
  align: right
  background_image: logo.jpg

page:
  layout: portrait
  margin: [2cm, 1cm, 2cm, 1cm] # top, right, bottom, left
  size: A4
base:
  font_color: #333333
  line_height_length: 17
  line_height: $base_line_height_length / $base_font_size
vertical_rhythm: $base_line_height_length
heading:
  font_color: #333333
  font_size: 17
  font_style: bold
  line_height: 1.2
  margin_bottom: $vertical_rhythm
link:
  font_color: #0e83a4
outline_list:
  indent: $base_font_size * 1.5
header:
  height: 1.5cm
  line_height: 1
  recto_content:
    center: '{document-title}'
  verso_content:
    center: '{document-title}'
footer:
  height: 1.5cm
  line_height: 1
  recto_content:
#    right: '{section-title} | *{page-number}/{page-count}*'
    right: '*{page-number}/{page-count}*'
  verso_content:
#    left: '*{page-number}/{page-count}* | {section-title}'
    left: '*{page-number}/{page-count}*'
image:
  align: center
caption:
  align: center
  font_color: #FF0000
  font_size: 10

You can then write your release notes in asciidocs format in src/main/resources/ReleaseNotes/Release_Notes.adoc, which could like like this:

= Release Notes 1.0.0
My Project
v1.0.0

// variables
:MyProj: My fancy project name


// Settings:
:sectnums:
:toc:
:toclevels: 3
:imagesdir[:imagesdir: images]




[.thumb]
image::image1.png[scaledwidth=20%]

[abstract]


== Introduction

This document contains release notes and change log for releases and patches to {MyProj}. +
 +
The document describes changes, known issues, deliverables and versions of sub components for a single version of the application. +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
,===
*Author*, Bugs Bunny
*Status*, Final
*Approved by*, Daffy Duck
*Version*, 1.0.0
*Created*,  January 14th 2016
*Last changed*, January 19th 2016
,===


<<<

== Revision History

*Only for this release* +
 +
[format="csv", options="header"]
|===
Date, Version, Description, Author
*15.01.2016*,0.1,First draft, Bugs Bunny
*15.01.2016*,0.2,Updates, Daffy Duck
|===

<<<

== Version Description


=== Deliverables (Sub components/Features)

bla bla bla...

<<<


=== Dependencies

+++<span style="color: #FF0000">Just some red text</span>+++ +

=== Comments

Comments comments +
 +
 +
*+++<span style="color: red;">WARNING: red and bold</span>+++* +

Then when you compile your project via maven, you will get a PDF document in target/generated-docs!
It should like like this.


In this example, we use asciidoctor to generate the PDF file so the syntax can be a bit different than plain asciidoc.


References:
AsciiDoc Syntax Quick Reference
http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

Chapter 10. Text Formatting
http://www.methods.co.nz/asciidoc/chunked/ch10.html

asciidoctor-maven-examples/asciidoctor-pdf-example at master · asciidoctor/asciidoctor-maven-examples
https://github.com/asciidoctor/asciidoctor-maven-examples/tree/master/asciidoctor-pdf-example

asciidoctor/asciidoctor-pdfhttps://github.com/asciidoctor/asciidoctor-pdf

asciidoctor-pdf/theming-guide.adoc
https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc

AsciiDoc Writer’s Guide
http://asciidoctor.org/docs/asciidoc-writers-guide/

Asciidoctor User Manual
http://asciidoctor.org/docs/user-manual/

Asciidoctor Documentation
http://asciidoctor.org/docs/

Differences between Asciidoctor and AsciiDoc
http://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/

AsciiDoc Writer’s Guide
http://asciidoctor.org/docs/asciidoc-writers-guide/

Sonatype Nexus is an artifact repository manager very much used when maven is your build tool for a java project. You can use it as a proxy for other repositories but also to host your own artifacts.

By default in Nexus, all repositories are reachable via the anonymous user.

Here is what to do to configure your Nexus server so that (at least) some of your repositories will require credentials to access them.

First you have to prevent the anonymous user to have access to all the repositories:

1. Create a new Privilege that gives access to you public group (or individual repositories) NOTE: Assigning access to a group is equivalent to assigning these privileges to all of the repositories in the group.
   1. Login to nexus as an administrator.
   2. Click on Privileges in the left menu.
   3. Click Add.
   4. Use the following values:
      1. Name: M2 Public Repositories (Group)
      2. Description: Access to Public Repositories (Group)
      3. Repository: Public Repositories (Group)
      4. Repository Target: All (Maven2)
   5. Save.
2. Repeat the previous step for all you public groups and/or respositories.
3. Create a new Role and assign this new privilege to it.
   1. Click on Roles in the left menu.
   2. Click Add.
   3. User the following values:
      1. Role Id: repo-public-read
      2. Name: Repo: All Public Repositories (read)
      3. Description: Read only access to all public repositories.
      4. Session Timeout: 60
      5. Selected Roles / Privileges: M2 Public Repositories (Group) - (read)
      6. NOTE: Include all of the roles you created in the first step.
   4. Save.
4. Remove the Grant Read all role from the Anonymous user and add the new role.
   1. Click on Users in the left menu.
   2. Click on the anonymous user.
   3. Remove the role 'Repo: All Repositories (read)'
   4. Add the role 'All Public Repositories (read)'
   5. Save.

Once you have done this, you need to create users to access all the non public repositories.

1. You first create a privilege for your given repo (Security->Privileges then Add)
2. Then a role (add the view and read part of the privilege created above)
3. And finally a user and assign him the role just create
4. Repeat this for as many times as you have repos. If you want to have several users for one repo, then just repeat 3.

The final step is to configure the client side with the proper settings in .m2/settings.xml and in the project pom.xml. like this:
settings.xml

<servers>
   <server>
       <id>myserver</id>
       <username>mrx</username>
       <password>pwd</password>
   </server>
<servers>

pom.xml

<repositories>
   <repository>
       <id>myserver</id>
       <name>myserver</name>
       <url>http://server:8081/nexus/content/repositories/your_repo</url>
   </repository>
</repositories>

Now your repository should be accessible with user and password only.


Some links:
Managing Security with Nexus
Depend on a password protected nexus repository
Can I make a repository private without disabling anonymous access?

As a follow-up of my previous post, I generated a Seam 2.1.2 project via seamgen and tried to make it work in the maven structure I made earlier.
The biggest problem was with the config files and have richfaces properly working. But I managed and the tar of the project is here.

The files I had to change where persistence.xml, pages.xml, web/pom.xml, web.xml and components.xml.

Now download it, unpack, copy your Java classes and webapp generated by seamgen where they belong, run "mvn clean install package" and you should be able to deploy the .ear file without any problems (given that you have the corresponding *ds.xml file)

Since I am playing with Maven and Seam, I had to manage to create a Seam 2.0 project which can be built with Maven (Seam 3.0 will be fully mavenized).

So here is what I found...
All you need to know is here:
http://seamframework.org/Documentation/IsThereAMaven2ProjectTemplateForSeamApplications

The first link (http://kasper.eobjects.dk/2009/04/seam-ejbs-and-ear-packaging-in-maven.html) works out of the box and uses sub-projects for the different modules (and Eclipse is ok with that!) but I am a bit unsure regarding the test part. It should work fine from the command line though.

The second link (http://www.smies.com/blog/?p=30) seems to have the test part built in but I have not tested it yet. It also uses a flat structure for the project which is a bit less nice...

So after a bit of work, I improved Kasper's setup so that the project now has a persistence unit defined (remember to add a proper *ds.xml file in your deploy folder) and is also able to do some sort of hot-deploy. You can get the tar file here.


For the hot-deploy part, I used something described here (http://relation.to/Bloggers/FastAndIncrementalPackagingInJBossTools) which copies files automatically upon changes from your workspace to your deploy folder (or any other folder of your choosing) according to some rules so you can filter the files you do not want.
This JBoss Tools might be interesting in other cases as well...

So to have the hot-deploy working, I configured the Project archives like this:
- one exploded archive for the ear
- one exploded archive for the jar, exploded inside the ear above
- one exploded archive for the war, exploded inside the ear above, and with 2 file sets (one taking all from web/src/main/webapp (aka the xhtml files) and the other taking all from web/target/JMSeamExample-web-1.0 minus **/*.*html (basically only the libs)).
An explanatory picture can be found here.

If one changes a Java class, the best is to right click on the project in Project archives and choose "Build full" to force a redeploy. Otherwise for xhtml files it happens by itself.
I know it is not has seamless as with the out of the box seam-gen integration but it is not too bad.