@mgreau :: Blog

[Talk] Migrate Maven CI jobs to Pipeline as code with Jenkins 2 and Docker

Maxime Gréau — Wed, 01 Mar 2017 00:00:00 GMT

This is the talk I gave at DevopsDDay 2016 and Docker Meetup Nantes 2017 about Jenkins 2, Maven, Pipeline as Code and Docker. It was the opportunity to revisit the problems that we have had and the solutions adopted, and some best practices around Maven builds in Docker containers, all managed by the Jenkins Pipeline as Code pattern:

Embedded Video

Recorded @ DevopsDDay 2016

Embedded Slides

Migrate Maven CI jobs to Pipeline as code with Jenkins 2 and Docker from DevopsDDay 2016 & Docker Meetup 2017

Summary of the presentation

Click, click, click… The clicks in the Jenkins UI to handle all the Maven jobs haunt you even at night? You want to manage them with the same process that you use for source code?

If I tell you that you can manage all your Maven builds with 3 lines of Groovy in a Jenkinsfile, it’s cool, isn’it?

exoCI {
    dockerImage = ‘exoplatform/ci:jdk8-maven32’
}

With this case study you will understand why and how we have upgraded more than 300 Jenkins “standard Maven jobs” to Pipelines on our eXo Platform CI instance.
This talk is an opportunity to revisit the problems that we have had and the solutions adopted, and some best practices around Maven builds in Docker containers, all managed by the Jenkins Pipeline as Code pattern.

Convert AsciiDoc to HTML/PDF & publish to GitHub Pages with Travis CI and Asciidoctor Docker containers

Maxime Gréau — Mon, 28 Mar 2016 00:00:00 GMT

Purpose

This blog post presents a simple way to automatically convert your AsciiDoc content to HTML and PDF, then publish those files to a public website on each commit.

There are many way to do it, maybe you have already used Jekyll or other static site generator like that. The real benefit of this one is that the workflow is done thanks to only one Travis CI configuration file.

The High-Level View
You have all your AsciiDoc sources files on one branch, all the generated files on another branch and just one configuration file.
All resources explained in this post are listed below:

AsciiDoc files and .travis.yml configuration file on asciidoc-to-ghpages project master branch
HTML and PDF files on asciidoc-to-ghpages project gh-pages branch
Files published at https://mgreau.com/asciidoc-to-ghpages/

Table of Contents

Overview
Prerequisites
Prepare your GitHub project
- Add files to your GitHub project
- Create a Token for Travis CI
Travis CI Configuration
Published files (HTML & PDF)

Overview

The following diagram gives you a quick overview of all interactions between GitHub, Travis CI, Docker and Asciidoctor.
Travis CI makes it possible because it allows you to run any Docker container. This isolates your build from the machine running on Travis CI and allows you to use an Asciidoctor environment that has been prepared for you.

Figure 1. Convert your AsciiDoc content to HTML & PDF, then publish those files to GitHub Pages courtesy of Travis CI running Asciidoctor via the provided Docker container(s).

Prerequisites

This post assumes that:

you know AsciiDoc and Asciidoctor
you have a GitHub account and a GitHub project configured to publish content from the gh-pages branch
- if it’s not the case you can read the GitHub tutorials about GitHub Pages
you have a Travis account linked to your GitHub account
- if it’s not the case, you can read the Travis CI Guide for beginners

Prepare your GitHub project

Add files to your GitHub project

The first step is to push some files to your master branch. The following GitHub project gives you a sample AsciiDoc content using images and include directive.

AsciiDoc to GitHub Pages demo project (master branch)

All samples come from this OpenDevise GitHub repository, thanks to Dan Allen.

All files available on this demo project are explained below:

Example 1. Files listed on master branch

+ images
   |- tiger.png     (1)
+ includes
   |- include.adoc  (2)
.gitignore
.travis.yml    (3)
demo.adoc      (4)
LICENSE
README.adoc    (5)

1	Image used in AsciiDoc content
2	AsciiDoc content included in the `demo.adoc` content
3	Travis configuration and scripts to build and publish the project, this file is explained in the Travis part.
4	Sample AsciiDoc file to convert
5	Documentation for the GitHub project, then converted to index.html file for the website

Create a Token for Travis CI

Travis CI will push files on a dedicated branch of your GitHub project, so you need to create a token to allow Travis CI to do it.
As you can see on the following screenshot, you just need to access to your GithHub Personal Settings page and click on the Generate token button, then check the public_repo scope:

Figure 2. GitHub Configuration: Create a token used by Travis CI

Travis CI Configuration

Connect Travis CI to your GitHub project

Once your AsciiDoc project is available on the master branch, you need to access to your Travis CI Dashboard and do some quick configuration so that Travis CI can build your project:

First, on your Travis Profile page, you need to Flick the repository switch on for your GitHub project:

Figure 3. Travis CI Configuration: Activate Travis CI on the project

You can’t see your project on the list? Click on the Sync account button (top right) and it should be ok.

Then, as shown below, go to the Project Settings tabs and configure it:
1. Check some options on General Settings
  1. check the Build only if .travis.yml is present option
  2. check the Build pushes option
2. Create some Environment Variables that will be used in .travis.yml file:
  1. GH_USER_NAME : your GitHub username
  2. GH_USER_EMAIL : your GitHub account email
  3. GH_TOKEN: the token created on previous step
    
    Uncheck the Display value in build log option
  4. GH_REF : the URL to your github project

Figure 4. Travis CI Configuration: Project Settings

.travis.yml: Travis CI Configuration and Scripts

The .travis.yml file is the most important file here ;)
Indeed, in this file, you tell to Travis CI how to process your AsciiDoc files and where to publish the generated files.
Those scripts will be executed after each update on master branch.

file .travis.yml

sudo: required

services:
  - docker                  (1)

before_install:            (2)
  - mkdir -p output
  - docker pull asciidoctor/docker-asciidoctor

script:
  - docker run -v $TRAVIS_BUILD_DIR:/documents/ --name asciidoc-to-html asciidoctor/docker-asciidoctor asciidoctor -D /documents/output *.adoc      (3)
  - docker run -v $TRAVIS_BUILD_DIR:/documents/ --name asciidoc-to-pdf asciidoctor/docker-asciidoctor asciidoctor-pdf -D /documents/output *.adoc    (4)

after_error: (5)
  - docker logs asciidoc-to-html
  - docker logs asciidoc-to-pdf

after_failure:
  - docker logs asciidoc-to-html
  - docker logs asciidoc-to-pdf

after_success:      (6)
  - cd output ; mv README.html index.html ; cp -R ../images images
  - git init
  - git config user.name "${GH_USER_NAME}"
  - git config user.email "{GH_USER_EMAIL}"
  - git add . ; git commit -m "Deploy to GitHub Pages"
  - git push --force --quiet "https://${GH_TOKEN}@${GH_REF}" master:gh-pages > /dev/null 2>&1

1	Tell Travis CI that you want to use Docker
2	Create the needed output directory and download the official Asciidoctor Docker image from DockerHub
3	Convert AsciiDoc files to HTML to the `/documents/output/` path with a Docker container
4	Convert AsciiDoc files to PDF to the `/documents/output/` path with another Docker container
5	Display logs from containers if a problem occured
6	Initialize a git project in the `output/ sub-directory in order to push the generated files and images to the gh-pages branch

Travis Build Logs

Travis CI gives you access to each build logs.
You can see in realtime, what is going on when AsciiDoc files are processed by Asciidoctor on each Docker container (one for HTML output and one for PDF output here)

Figure 5. Travis CI Build

Published files (HTML & PDF)

Finally, when the Travis CI Build has succeeded, you can view the generated files at:

https://mgreau.com/asciidoc-to-ghpages/
- Demo HTML
- Demo PDF

Example 2. Files listed on gh-pages branch

+ images            (1)
   |- tiger.png
demo.html         (2)
demo.pdf          (3)
index.html    (4)
README.pdf

1	The images folder is copied so that images are published to GitHub Pages Website
2	The HTML output file
3	The PDF output file
4	The `README.html` is renamed to `index.html` in order to have a homepage file for the Website

You can see below a screenshot with both demo.html and demo.pdf files.

Figure 6. HTML and PDF files published on GitHub Pages converted from the same AsciiDoc content by Asciidoctor

I hope this post was useful and it helped you understand how to combine Travis CI and Docker to automatically convert content written in AsciiDoc and publish the output to GitHub Pages on each commit.
There are a lot of other ways to do it, I’d love to have your feedbacks about it, so feel free to add a comment.

[Talk] Improve your Java Environment with Docker @ HanoiJUG 2015

Maxime Gréau — Thu, 05 Nov 2015 00:00:00 GMT

Our Session with Thomas Delhoménie about how to Improve your Java Development Environment with Docker at Hanoi JUG 2015 with a Java EE 7 / Angular / WildFly / Redis / MySQL Application with Docker containers:

Improve your Java Environment with Docker from HanoiJUG

Description:

Dockerize your Java Development Environment with Machine & Compose

Developers, Docker Compose is the key to be efficient with your development environment!

Whatever the project and the technologies behind it, all developers should be able to work on it quickly without losing time to setup their development environment.

Today, we really think that Docker, with Machine & Compose, have changed the way to work on developer side.

And now, as a developer, you are able to develop quickly with an environment closest to the production environment.

We will show you how you can develop, build, debug and run your Java, Web, multi-databases applications easily thanks to Docker.

#docker4Dev: Copy Docker images from one docker machine to another

Maxime Gréau — Wed, 26 Aug 2015 00:00:00 GMT

Overview

In this post, you will see how to copy images from one docker machine to another by using docker-machine scp command available since docker-machine 0.3.0. It may be useful if you have no Internet access neither local docker registry installed.

if you are already familiar with docker-machine, you can jump ahead and start reading how to copy images.
if you want to see it in action right know, you can watch the terminal session video recorded with Asciinema (01:25, speed x3)

About this post

Language EN / Timereading 10 mn

Today I really think that Docker is not only a revolution for Ops and DevOps teams, but also on the Development environment side and that’s just a beginning.

That’s why I have a lot of docker machines created on my laptop in order to organize my several development environments. But the fact is that you frequently want to use an image on a machine that is already present on another existing docker machine. And if you are offline or if you Internet connection is slow, you can’t execute a 'docker pull' command, so how to deal with that?

Figure 1. Copy Docker images from machine to machine with scp

Table of Contents

Install Docker Machine
- Installation via Docker Toolbox
- Installation via Command line
Copy image from machine to machine
- Commands explained
- See it in action: Terminal Session demo
Export an image from a machine and load it to another machine thought your host

Install Docker Machine

Installation via Docker Toolbox

Two weeks ago, Docker announced a new installer for Mac OS X and Windows called Toolbox.

Toolbox installs everything you need to get Docker running in development: the Docker client, Compose (Mac only), Kitematic, Machine, and VirtualBox.

Even if, under the hood, Machine still uses Boot2Docker, now containers are managed by Machine.

You can find all informations about Toolbox at the following URLs:

ToolBox blog post: ANNOUNCING DOCKER TOOLBOX
ToolBox install packages

Installation via Command line

If you still want to install Docker machine without Toolbox, you can execute the following commands:

$ curl -L https://github.com/docker/machine/releases/download/v0.4.1/docker-machine_linux-amd64 > /usr/local/bin/docker-machine  (1)
$ chmod +x /usr/local/bin/docker-machine (2)

1	Download the latest docker-machine binary according to your target platform
2	Apply executable permissions to the binary

Then whatever the choice you made for installing it, you should be able to execute the docker-machine help command to see the scp command on the list:

$ docker-machine help
...
Version: 0.4.1 (e2c88d6)  (1)
...
Commands:
  active		Print which machine is active
  ...
  scp			Copy files between machines  (2)
  ...
  help, h		Shows a list of commands or help for one command

1	Docker Machine 0.4.1 released on August, 14, 2015
2	The scp command is available since docker-machine 0.3.0

Copy image from machine to machine

Unfortunately, for now it is not possible to do it with one command. Indeed, the machine scp command is used to copy the export image file between machines, so, before that, the docker machine ssh command is used to manage file on the source machine and at the end on the target machine.

The docker machine scp usage is based on the machine names, and is similar to the default scp syntax.

Commands explained

$ docker-machine ls --filter=state=Running  (1)
NAME                ACTIVE   DRIVER       STATE     URL                         SWARM
default                      virtualbox   Running   tcp://192.168.99.102:2376       (2)
devnation-2015      *        virtualbox   Running   tcp://192.168.99.104:2376       (3)
docker4dev-ee7-js            virtualbox   Running   tcp://192.168.99.105:2376       (4)


$ docker-machine ssh devnation-2015 docker images | grep node  (5)
node                             latest              20a32f7a591c        8 weeks ago         711.5 MB
node                             0.12.4              f9ba67676f8f        9 weeks ago         711.8 MB

$ docker-machine ssh docker4dev-ee7-js docker images | grep node  (6)

$ docker-machine ssh devnation-2015 "docker save -o /tmp/node.tar node:0.12.4" (7)
$ docker-machine scp devnation-2015:/tmp/node.tar docker4dev-ee7-js:/tmp/node.tar (8)
$ docker-machine ssh docker4dev-ee7-js "docker load -i /tmp/node.tar"  (9)
$ docker-machine ssh docker4dev-ee7-js docker images | grep node       (10)
node                0.12.4              f9ba67676f8f        9 weeks ago         711.8 MB

1	display all running machines
2	default machine created when you launch the terminal shortcut provided by Toolbox
3	the source machine containing the node:0.12.4 image to copy
4	the target machine
5	display all images related to node on the source machine
6	check that there is no image related to node on the target machine for now
7	export the node image to a TAR file on the source machine
8	copy the TAR file from the source machine to the target machine via scp command
9	load the node image to the docker local registry of the target machine
10	check that the node image is now available on the target machine

See it in action: Terminal Session demo

All commands described above have been executed on my laptop and thanks to Asciinema, they have been recorded too:

Export an image from a machine and load it to another machine thought your host

An other way to do the same thing, without using the scp command, is to:

export directly the TAR file to your host with the docker client connected to the source machine
and then load this file to the target machine with the docker client connected to the target machine

$ docker-machine ls  (1)

NAME                           ACTIVE   DRIVER       STATE     URL                         SWARM
default                        *        virtualbox   Running   tcp://192.168.99.102:2376
devnation-2015                          virtualbox   Running   tcp://192.168.99.104:2376


$ eval $(docker-machine env devnation-2015)  (2)
$ docker images | grep alpine                (3)
alpine                           3.1                 fa60145ca189        11 weeks ago        5.033 MB
alpine                           3.2                 8697b6cc1f48        11 weeks ago        5.242 MB


$ docker save  -o /tmp/alpine-3.2.tar alpine:3.2  (4)
$ ls /tmp/alpine*
/tmp/alpine-3.2.tar

$ docker-machine create -d virtualbox docker4dev-ee7-js  (5)
$ eval $(docker-machine env docker4dev-ee7-js)           (6)
$ docker images                                        (7)
REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
$ docker load -i /tmp/alpine-3.2.tar                   (8)
$ docker-images                                        (9)
REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
alpine              3.2                 8697b6cc1f48        11 weeks ago        5.242 MB

1	display all machines
2	point the docker client to the source machine
3	display all images related to alpine on source machine
4	export the alpine:3.2 image from the source machine to the host
5	create a new machine with the virtualbox driver
6	point the docker client to the target machine
7	check that the target machine does not contain image
8	load the alpine:3.2 image from the host to the docker registry of the target machine
9	check that the alpine:3.2 is now available on the target machine

How do you do this? Do you use a local docker registry reachable by all machines?
I’d love to have your advices.

[Talk] AsciiDoc : Create and Publish everywhere from anywhere

Maxime Gréau — Mon, 22 Jun 2015 00:00:00 GMT

My slides from DevNation 2015 at Boston in June.

Agenda Asciidoctor @ DevoxxFR et t-shirts à gagner

Maxime Gréau — Wed, 08 Apr 2015 00:00:00 GMT

Dans quelques heures c’est le début de Devoxx France 2015 !
Alors que toute l'équipe organisatrice est encore au travail (déjà bravo à eux d’ailleurs), il est temps de préparer votre programme personnalisé pour ces 3 jours de geeks.

Table of Contents

Asciidoctor : the big boss is here !
Agenda
Des T-Shirts à gagner !

Asciidoctor : the big boss is here !

Dans ce billet, je vous propose une synthèse des événements DevoxxFR relatifs à Asciidoctor. Comme vous le savez, Dan Allen le lead du projet Asciidoctor est présent cette année, c’est donc le bon moment pour apprendre du guru d’Asciidoctor :). Vous pourrez rencontrer également Sarah White, Guillaume Scheibel et moi-même.

Si vous ne nous reconnaissez pas, nous aurons sûrement des t-shirts Asciidoctor sur nous :)

Agenda

Mercredi 08 Avril 2015

Tools In Action @ 18h40 - 19h10

Et si on arrêtait de se prendre la tête avec la documentation

Guillaume Sheibel
@gscheibel

Et si on arrêtait de se prendre la tête avec la documentation

Salle Neuilly 253 Lab
18h40 - 19h10

Jeudi 09 Avril 2015

Keynote @ 10h30

Reading and Writing in 20 Years

Dan Allen
@mojavelinux

Reading and Writing in 20 Years

Amphi Bleu
10h30 - 10h50

BOF Asciidoctor

Dan Allen
@mojavelinux

Guillaume Sheibel
@gscheibel

Maxime Gréau
@mgreau

Vendredi 10 Aril 2015

Conférence @ 14h05 - 14h55

Write in AsciiDoc, Publish Everywhere!

Dan Allen
@mojavelinux

Maxime Gréau
@mgreau

Write in AsciiDoc, Publish Everywhere!

Salle Neuilly 252 AB
14h05 - 14h55

Des T-Shirts à gagner !

Nous aurons des beaux t-shirts à manches longues à gagner pendant ces 3 jours à Devoxx France donc surtout ne loupez pas les événements Asciidoctor :)

Figure 1. T-shirts Asciidoctor @ Devoxx France (Edition limitée)

Pour ma part, c’est mon premier Devoxx France, je compte bien en profiter au maximum (même si j’ai la pression jusqu’au vendredi am :) )

See you au Palais des Congrès !

How Asciidoctor uses Arquillian and Docker to verify that AsciidoctorJ works in WildFly AS

Maxime Gréau — Tue, 03 Mar 2015 00:00:00 GMT

Language EN / Timereading 10 mn

Overview

This post explains how we execute Arquillian tests for AsciidoctorJ to a Docker container, so we’ll talk about:

docker-asciidoctorj, the dedicated github project on Asciidoctor organization
the Asciidoctor organization on Docker Hub,
Arquillian Cube, the Arquillian extension that can be used to manage Docker containers from Arquillian.
the WildFly docker image from JBoss

It’s been a while since I wrote here but like many technical bloggers (I guess), I have a lot of blog posts on draft mode. And I have a lot to write about 2014 which was an AMAZING year : indeed, thanks to the Asciidoctor project and Java EE 7 / WildFly technologies, I gave 2 talks at DevNation, San Francisco to speak about Open Source projects:) and I reviewed a book.
But I’ll blogged about this awesome experience soon.

So, what’s this post about : Docker? Asciidoctor? Arquillian?

Figure 1. The power of Arquillian & Docker for AsciidoctorJ integration tests

You have just read the title and you said:

"Oh no, Not another post about Docker!",

and I want to answer

"Well, it’s 2015, is it possible to write a blog post without mentioning Docker ?"

To be serious, it’s more a blog post about the AsciidoctorJ project and how Docker helps us to easily check that it’s possible to execute AsciidoctorJ in a Java EE application server like WildFly.
So it’s not a post about Docker itself but more a use case where Docker is the key to the ease of tests…OK you’re right, it’s about Docker:)

Table of Contents

Asciidoctor on the JVM with AsciidoctorJ
AsciidoctorJ in a Java application server
- How to make it work?
- Make it easy thanks to the power of Arquillian & Docker
AsciidoctorJ in your favorite Java application server?
Conclusion : Asciidoctor on DockerHub

Asciidoctor on the JVM with AsciidoctorJ

I guess that I don’t need to introduce Asciidoctor (started in 2012) now that it became so popular thanks to the awesome work done by Dan Allen and the community.
Well, if you don’t know, Asciidoctor is a fast text processor and publishing toolchain for converting AsciiDoc content to HTML5, PDF, DocBook 5 (or 4.5) and other formats. Asciidoctor is written in Ruby, packaged as a RubyGem and published to RubyGems.org.

Figure 2. Asciidoctor convert AsciiDoc files to several formats

AsciidoctorJ is the official library, started by Alex Soto, for running Asciidoctor on the JVM. Using AsciidoctorJ, you can convert AsciiDoc content or analyze the structure of a parsed AsciiDoc document from Java and other JVM languages.

Figure 3. Asciidoctor on the JVM with AsciidoctorJ

AsciidoctorJ in a Java application server

So here we have a problem.
The problem is that if you want to include AsciidoctorJ in your Java application, it doesn’t work easily.
Indeed, AsciidoctorJ is based on JRuby and there are some classloader troubles with JRuby as you can read in those different discussions: PR118, Issue 102 and this thread on the asciidoctor discussion list.
If you tried to include it without success, you should have seen the message below:

Caused by: org.jruby.exceptions.RaiseException: (LoadError) no such file to load -- asciidoctor

How to make it work?

The solution is to create a new JBoss module with all AsciidoctorJ dependencies and then depend on this module in the target application.
The module.xml file, which describes the Asciidoctor JBoss module, includes the following JARs:

Example 1. Asciidoctor JBoss module descriptor

So you can follow all those manual steps describe in the documentation to configure your WildFly installation.

Make it easy thanks to the power of Arquillian & Docker

OK well, we have a solution but there are several manual steps to follow and it’s not efficient to do all those steps to test each new version of AsciidoctorJ or WildFly. Fortunately, the Arquillian Cube extension came into being! :)

Arquillian Cube extension to the rescue!

Arquillian Cube is a very nice project developed by Alex Soto, Aslak Knutsen and the Arquillian community.
With Arquillian Cube you can control the lifecycle of Docker images as part of the test lifecycle, either automatically or manually.
This gives you the chance to scale up from a integration/functional test level all the way up to the system test level.

This project gives you a lot of possibilities, if you want know more about all those features you can read this news on the arquillian website or the documentation on the github project.

Pull the official Docker image, execute tests and see the output

To quickly test the project, just follow the steps below:

git clone https://github.com/asciidoctor/docker-asciidoctorj.git && cd docker-asciidoctorj
mvn clean test -Pwildfly82
ls /tmp/documents

Prerequisites

Ensure that Java, Maven and Docker are installed.
If you are using boot2docker, you can pass some configuration to the Maven command like this:

mvn clean test -Pwildfly82 -Ddocker.serverProtocol=https  -Ddocker.serverIp=192.168.59.103 -Ddocker.serverPort=2376

If you need help, you can read the Arquillian Cube documentation about boot2docker configuration.

Thanks to Arquillian Cube, the Maven command will do the following steps:

Download the AsciidoctorJ WildFly Docker image asciidoctor/asciidoctorj-wildfly from the DockerHub registry
Install this image in your local registry
Start a container
Connect to WildFly
Deploy app and Execute tests
Disconnect from WildFly
Copy the generated files from the container location to the host location
Stop the container
Destroy the container

Figure 4. Steps done thanks to Arquillian Cube

Tests executed with Maven

[INFO]
[INFO] ------------------------------------------------------------------
[INFO] Building Docker AsciidoctorJ 1.0.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO]

 -------------------------------------------------------
 T E S T S
 -------------------------------------------------------
Running org.asciidoctor.ConverterServletTest
Mar 01, 2015 10:31:47 PM org.jboss.arquillian.container.impl.MapObject populate
WARNING: Configuration contain properties not supported by the backing object org.jboss.as.arquillian.container.remote.RemoteContainerConfiguration
Unused property entries: {host=127.0.0.1, target=wildfly:8.2.0.Final:remote}
Supported property names: [managementAddress, password, managementPort, managementProtocol, username]
Mar 01, 2015 10:32:39 PM org.xnio.Xnio 
INFO: XNIO version 3.2.0.Beta4
Mar 01, 2015 10:32:39 PM org.xnio.nio.NioXnio 
INFO: XNIO NIO Implementation Version 3.2.0.Beta4
Mar 01, 2015 10:32:39 PM org.jboss.remoting3.EndpointImpl 
INFO: JBoss Remoting version (unknown)
Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 65.087 sec - in org.asciidoctor.ConverterServletTest

Results :

Tests run: 3, Failures: 0, Errors: 0, Skipped: 0

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Those tests are very simple for now, they will convert the same AsciiDoc file (sample.adoc) to a one PDF file and one HTML file.

Figure 5. same sample.adoc file converted to PDF and HTML5 files by AsciidoctorJ on WildFly

docker-asciidoctorj project in detail

The project docker-asciidoctorj was created to test different versions of AsciidoctorJ, AsciidoctorJ PDF and others, quickly in the same environment.
Some of the most important files of the project are described on the following lines.

The project layout is as follows:

Example 2. project structure

+ dockerfiles
   |+ wildfly82
      |- Dockerfile   (1)
+ src/main/java
   |+ org.asciidoctor
      |- AsciidoctorProcessor.java    (2)
      |- ConverterServlet.java   (3)
+ src/main/resources
   |+ adoc
      |- sample.adoc   (4)
+ src/test/java
   |+ org.asciidoctor
      |- ConverterServletTest.java   (5)
+ src/test/resources
   |+ wildfly
      |- MANIFEST.MF   (6)
   |- arquillian.xml   (7)
pom.xml

1	The Dockerfile used to build Docker image with AsciidoctorJ in WildFly 8.2
2	Java Bean which converts AsciiDoc file to HTML or PDF file
3	Java Servlet which uses the converter
4	Sample AsciiDoc file to convert
5	Tests to process AsciiDoc to HTML/PDF with AsciidoctorJ
6	MANIFEST file used to depend on AsciidoctorJ WilFly AS module ( Dependencies: org.asciidoctor )
7	Arquillian XML file to configure Docker containers

The whole Dockerfile is described below:

Example 3. Dockerfile

FROM jboss/wildfly:8.2.0.Final  (1)
MAINTAINER Maxime Gréau 

# Create a WildFly admin user to deploy app with CLI
RUN /opt/jboss/wildfly/bin/add-user.sh -up mgmt-users.properties admin Admin#70365 --silent  (2)

# Set env variables for versions  (3)
ENV ASCIIDOCTORJ_VERSION 1.5.2
ENV ASCIIDOCTORJ_PDF_VERSION 1.5.0-alpha.6
ENV ASCIIDOCTORJ_EPUB3_VERSION 1.5.0-alpha.4
ENV JRUBY_VERSION 1.7.16.1

# Handle asciidoctor-backends  (4)
ENV ASCIIDOCTOR_BACKENDS /opt/jboss/asciidoctor-backends
RUN mkdir -p ${ASCIIDOCTOR_BACKENDS}

# Create the AsciidoctorJ module
RUN mkdir -p ${JBOSS_HOME}/modules/org/asciidoctor/main
ENV ASCIIDOCTORJ_MODULE /opt/jboss/wildfly/modules/org/asciidoctor/main

# Output directory to store generated files
ENV OUTPUT_DIRECTORY /tmp/documents
RUN mkdir -p ${OUTPUT_DIRECTORY}

# Set the ULR_BASE env variable to download artifacts
ENV URL_BASE https://repo1.maven.org/maven2/

ADD module.xml ${ASCIIDOCTORJ_MODULE}/module.xml     (5)

RUN cd ${ASCIIDOCTORJ_MODULE} \  (6)
&& curl -O ${URL_BASE}org/asciidoctor/asciidoctorj/${ASCIIDOCTORJ_VERSION}/asciidoctorj-${ASCIIDOCTORJ_VERSION}.jar \
&& curl -O ${URL_BASE}org/asciidoctor/asciidoctorj-pdf/${ASCIIDOCTORJ_PDF_VERSION}/asciidoctorj-pdf-${ASCIIDOCTORJ_PDF_VERSION}.jar \
&& curl -O ${URL_BASE}org/asciidoctor/asciidoctorj-epub3/${ASCIIDOCTORJ_EPUB3_VERSION}/asciidoctorj-epub3-${ASCIIDOCTORJ_EPUB3_VERSION}.jar \
&& curl -O -m 900 ${URL_BASE}org/jruby/jruby-complete/${JRUBY_VERSION}/jruby-complete-${JRUBY_VERSION}.jar \
\
&& (curl -LkSs https://api.github.com/repos/asciidoctor/asciidoctor-backends/tarball | tar xfz - -C ${ASCIIDOCTOR_BACKENDS} --strip-components=1)

WORKDIR ${OUTPUT_DIRECTORY}
VOLUME ${OUTPUT_DIRECTORY}  (7)

CMD ["/opt/jboss/wildfly/bin/standalone.sh", "-b", "0.0.0.0", "-bmanagement", "0.0.0.0"]  (8)

1	This image is based on the official WildFly 8.2 image
2	Add an admin user, used in arquillian.xml file to deploy application
3	Define variables for AsciidoctorJ core versions
4	Add backend files (templates) used to generate HTML5 presentations from AsciiDoc for example
5	Initialize the Asciidoctor JBoss Module with module.xml file
6	Add all AsciidoctorJ dependencies to the JBoss Module Ascciidoctor
7	Define a volume where the converted files will be copied
8	Start a WildFly instance with asciidoctor module

The arquillian.xml file is explained here:

Example 4. arquillian.xml with containers configuration


...

        ${docker.serverVersion}  (1)
        ${docker.serverProtocol}://${docker.serverIp}:${docker.serverPort} (2)
        ${arquillian.cube.autostart}
        true
        
            wildfly82_dockerfile:        (3)
              buildImage:
                dockerfileLocation: dockerfiles/wildfly82   (4)
                noCache: true
                remove: true
              exposedPorts: [8080/tcp, 9990/tcp]
              await:
                strategy: polling
                sleepPollingTime: 50000
                iterations: 5
              beforeStop:
                - copy:
                    from: /tmp/documents
                    to: /tmp
              portBindings: [8081->8080/tcp, 9991->9990/tcp]
            wildfly82:                                          (5)
              image: asciidoctor/asciidoctorj-wildfly:latest   (6)
              await:
                strategy: polling
                sleepPollingTime: 50000
                iterations: 5
              beforeStop:                      (7)
                - copy:
                    from: /tmp/documents
                    to: /tmp
              portBindings: [8081->8080/tcp, 9991->9990/tcp]
        
    

     (8)
       
            dockerServerIp (9)
            admin        (10)
            Admin#70365
       
   
   
       
            dockerServerIp
            admin
            Admin#70365

1	The docker server version which expose the REST API required by Arquillian
2	URL to connect to Docker (Maven properties with default values)
3	Container configuration to use with a Dockerfile
4	Path where Arquillian will find the Dockerfile to use to build the image
5	Container configuration name
6	The official asciidoctor image to use for the tests
7	Before stopping the container, Arquillian Cube will copy the generated files from container location to the host location
8	Container configuration to work with the Docker image presents in the registry
9	dockerServerIp will be auto resolved for all docker envs (boot2docker..)
10	Arquillian use this admin user defined in the Dockerfile to communicate with WildFly

Thanks to the JBoss Module we can create an instance of the Asciidoctor class without problem :

Example 5. Process AsciiDoc: AsciidoctorProcessor.java

....
@Named
public class AsciidoctorProcessor {

	private Asciidoctor asciidoctor;

	@Inject
	private Logger logger;

	@PostConstruct
	public void init() {
    asciidoctor = Asciidoctor.Factory.create();  (1)
	}

	public Path convertToHTML(final String inputFilename) throws Exception {
    asciidoctor.convert(getResourceAsString(inputFilename),  (2)
            parameters(getOutputDir(), "sample.html", "html5"));
    return FileSystems.getDefault().getPath(getOutputDir() + "sample.html");
	}

	public Path convertToPDF(final String inputFilename) throws Exception {
        String outputFilename = "sample.pdf";
        asciidoctor.convert(getResourceAsString(inputFilename),
                parameters(getOutputDir(), outputFilename, "pdf"));
        return FileSystems.getDefault().getPath(getOutputDir() + outputFilename);
	}

	private Map parameters(String outputDir,    (3)
			  String outputFilename, String backend) {
		    return options().backend(backend).safe(SafeMode.UNSAFE)
				      .headerFooter(true).inPlace(true)
				      .toFile(new File(outputDir + outputFilename)).asMap();
  }

        public static final String getOutputDir() {
            return System.getenv("OUTPUT_DIRECTORY") + "/";   (4)
        }
    ...

1	Create the Asciidoctor instance to be able to process AsciiDoc
2	Convert the sample.adoc file (present in the classpath) to a sample.html file
3	Configure options and attributes to process the AsciiDoc
4	This environnment variable OUTPUT_DIRECTORY is defined in the Dockerfile (/tmp/documents)

The following test for PDF converter is pretty simple:

Example 6. Convert AsciiDoc to PDF: ConverterServletTest.java

    @Test
    public void should_convert_to_pdf(@ArquillianResource URL base) throws IOException {
        URL url = createURL(base, "convert", "pdf", "sample.adoc");
        assertThat(getResponse(url), is("PDF : true"));
    }

Customize, build with Docker and use your own Docker image

You can customize the existing Dockerfile, then build the image with Docker and finally use this image with Arquillian when you execute the test:

Clone this project:

git clone https://github.com/asciidoctor/docker-asciidoctorj.git

Customize the dockerfiles/wildfly82/Dockerfile

Build the Docker image

cd docker-asciidoctorj
docker build -t asciidoctor/asciidoctorj-wildfly dockerfiles/wildfly82/

Example 7. Docker images

mgreau@mgreau-osxubuntu:~/git/asciidoctor/docker-asciidoctorj$ docker images
REPOSITORY                          TAG           IMAGE ID       CREATED        VIRTUAL SIZE
asciidoctor/asciidoctorj-wildfly    latest        80e19c9457fc   2 minutes ago  982.5 MB
jboss/wildfly                       8.2.0.Final   24c5b96027df   3 months ago   951.3 MB
---

Execute the Maven command below:
```
mvn clean test -Pwildfly82
```

Until the Docker image is present in your registry, you just have to execute the Maven command.

All in one with Arquillian: Build the Docker image and execute tests in a container

You can do the same thing but with only one Maven command! Indeed, Arquillian Cube will build the Docker image for you and then execute tests in the container:

Clone this project:

git clone https://github.com/asciidoctor/docker-asciidoctorj.git

Customize the dockerfiles/wildfly82/Dockerfile
Execute the Maven command
```
mvn clean test -Pwildfly82_dockerfile
```

AsciidoctorJ in your favorite Java application server?

It seems that the JRuby classloader problem is solved by the use of JBoss Modules components.
However if you want to quickly test AsciidoctorJ in your favorite Java application server like TomEE or others…just follow the steps below:

Fork the GitHub repository docker-asciidoctorj
Create a file named Dockerfile inside a subfolder of dockerfiles directory, following the named convention {appservername}{version}
Update the src/test/resources/arquillian.xml file to add a docker container configuration
Update the pom.xml to add Maven profiles related to the application server (dependencies…)
Execute tests (maybe create a dedicated test) and see the results
If tests passed, then you could write documentation and send a PR

If you try it, I’d love to have your feedbacks, so feel free to add a comment below, on the discussion list or on the GitHub project.
We are waiting for PR :)

Conclusion : Asciidoctor on DockerHub

The good news here is that the Asciidoctor project now have an easy way to test if the future versions of AsciidoctorJ will be compatible with this architecture.
But the most important thing is that Asciidoctor now has its own official registry for Docker images, with, for now, 2 officials images :

asciidoctor/docker-asciidoctor (created by Guillaume Scheibel)
asciidoctor/asciidoctorj-wildfly

And I’m so proud to have moved my first project to the Asciidoctor github organization and to be one of the Docker Hub administrator for Asciidoctor!

Have fun with Asciidoctor, Arquillian and Docker :)

JBoss EAP 4.3 / 5.1 / 6.2 - Java EE supported standards in each EAP releases

Maxime Gréau — Tue, 10 Dec 2013 00:00:00 GMT

Language EN / Timereading 5 mn

This post presents, as a diagram, all Java EE standards supported in each JBoss EAP version :

This diagram was updated in December 2013 (fixes and addition of (*) information)
Thanks to Arun Gupta for the fixes
The following data are based on official documentation from Oracle (JSR) and Red Hat (EAP).

You can click on each component to access the Java Specification Requests (JSRs) details or move to the complete lists.

7V1tc+I4Ev41qbrbqqGsF0v2R4aEvZ3aqU1t5m72qwMOeJZgzphNZn/9Sn7DLYlXGeN4wlRlQAYbWo+7n251q2/I6Pn15yRYzT/H03Bxg53p6w25vcHYcxzxVw58VwZmSTTNh1AxsImm4RoMpXG8SKMVHJzEy2U4ScHYU7yAJ1sFs1AbeJgEC330azRN58WXw2w7/p8wms3LyyDm50fW6ffyHNPwKdgs0g/ZEM4PvzrFmfKX34uXmJbnXYLr/x3Hz2AgCdfR3/A7PkXFlygE9xgn0zABQ4to+WddSOTuhoySOE7zZ8+vo3AhZ6WUeP6x8Y6jlWyScJke8wGSf+CvYLEpvromq6dosRjFizj/3mQ89sXjhnxcp0n8Z1geWcbLsDhXmKTh687vs/2VAndh/BymyXcp/eJoIZYScu7AqT1Qcb6X7bwjXKJyXpt07tKBX3/kbwkKSc+q625FI54U0jFLip8sKcY+4vH4UpLCUDSOBwSHPEcTFaWKUKguOEYce1F5Z4BKwupSouK+D344Oigq4kPp4gtJCrGTReX7lxQV5c4RwjHcceeI47/rMPnt8Zu0CEIRBo/C/GQf/fQxXq/F0N0yTcJVEq3FL3OGq9UimgRpFC/Fq/tFkD7FybN4+q+74f2/b6T6J6+BkEuwnEoBblarWAhCPv8U/BXI092JPw+pOB4k0/VW/eYXnaeptFZD+WXxOJhMwvV6kITTeZAOJkLV4/Gfy/hlEU6FdRLHkzSaLITNw2OECOGFHq3m1atJuZjz2pQm8WY5DeV7kfjCqtrw5T8xPkuCaSTmDUy+RKN58sWJYvDmcfYoxh+Kq6Pi9Th4jhZykr8E8/g5KN+VWzDkNQAlQuBd5xGALEV/IR9rQHNdA9C803EmXtagdhz0hvfiLx0QE0wqlLy8vECIrJJ4upmkEhbfHsWZhKjCJEPwczSdLsIXIT2Jni2WP6wqJI8VDPkWGBKPDCcqhgqkXBw+4hLzYBq/ZB+xx5LPoFri1NWZgEkttYkWd4Cuh5bccJyHFkL6hRbX9eqax2MKdvDArWmeDiKJDfAVkUTOR5LjMDYa9QdJiKh6x+hXXBk7OGM2aEBrLGgkfnb0FEn+swdI3yarQZzMxLNwKV+uE/F3GqZBJM49zhCBXATxkRvl8/BRza2B21THIEgy1iN5j44UMH4aUmgTRknhykxxMwzg4CbmfFlwDP/48PVB0uSf6iQZDxxbYFSRkQoY6HxgjMTD1gTl6vxqcECO6wBK6wJ0UJXw6ugg7aPj4cuvNVSgA3bnCFQ4LlZoLLKwJ13whZrABkHYFE8onWykWJVuYGP4x+8AG9Yaw/FVNzkX7o+NDcoYmH1XwYaiNmgnsPH5AUDjsONzBDz88rdt4eG+w4Nhf0Br8DigOjoBj4fh8BPAx/4wyjGqg3EVG288xNYENrjPTJxih+pwSBew8TV8lGHYMPkrmsj4qfNZTPQ0SIMaYG7ksqAAgZPOw238dhvztfRoPKRiySbU1hMseRwyFHIyljxzvLddX+f3+9EJlukYtDgqWrCFA9wXtPgMn6B5EO8EafkybBYavqMaJWxhlEaj8fiOHesCF/4uY53zg4miSTgF2KA+H/AaoemEUSosjLRKizCtoYTYez0EuSpKLMyNkKc5gtZOhJU2HWElMGaCCHR/XNc1xVSujJb7YbOOcZUNVEGEWgRNxng8vr07SZEQYoqvXlmRcGXRz2VQseiawyNAtTB2BQby8TKxVjWqRi1c474AxGNgna/0fUtDQ9CA1xf6mI4XBJULN+EF8l7WghnKlnNGea6kdIMqJA2TyTxKxehGLuc5QAm51kQXaRhjbxtjuAklhL06AMrMmDKJxYHwoLp5Ki8JQAWDNp5/SVDdfZIqKSMyFVzyMSwpsDZ2CWtmQYt7Y81caM2EnTrkI8F3oKtrp4d7YNWs/SdMVWZMLZhxX2kPIwdpDwUR4ivQnoexuoqYcyBLfGhriVa5B31hPRwGW7ijJxp47ftEMvam5xk04ByRMut/iwKLRAN6W+SM9MR/lg4y4BKQn3A66IbLPBw1HZfVwiquhUvUO1goRgT5BCQ9GoiqA8P37VsRkO6fLRNVeNkuFzWZq4JKzbmFkIXH0zcIMceYzlayEuzWvWvUjTBukewGSWojVERNdkN5sOAdKpm2UZf+AFSyQEydoBqUz9VC/lmsxb1E4iymKmRY65mzjmPOnJULR2dT2Bp4nCbAw2HIn/l8sD9sh9hV0cJqaBlvslm8T2IxX9JuNQYfUtYGbuFjQXvPgw/CxK90jOIBXXHxGdGTE6+vhhh9SRE3EKp1NdWC363RlrhA++O6gPuaisiva37qEX5Q5Vo7cBuuFvH3ZykCNdJiiybH81Q00fPRNKICCB9PCrN0M42Bm/2h0rP2hPBrpMbgZbtGrVSHmH9RiN2Gj5vZLFrOpBrKy6EhpvIcu9/SeSj//zVYzjbBLMvJazjvW4vzMgtXvTd5MpzuA5jL8IAbUMXNIX+w+0Wby0tqVpU1WvSsKmbhavWisIj6eyoEqI+NiOhYwM8aF3rAj1ll2/UBF0qtiOd3r8Ts1Kge+skaKFpYj1ksK/ajMpECoDDyZjjwIQJsvY6gs19uEabpo1ohBK4dEHoceDy3BfCY/GtqrUE0/5pbxF76oUGwxk47xzlG8fNz5jcPl8s4zRTIWnN3dpQU7WMquEzd2cLBItzSl8w45pE9QX/iukBpGAwOMxbEXy1PDiaxNJAHR7R61rwU4jzY9C7xHytODTQ6HLmHYrrX2C4BZsBhW4joGXDcIjLSd4goK9CUd3BDDdXttecimtvLLZIUegcRDjCBlFiIgakiGD8rNytt0SEu8rGRlnvdYo42QZrXYxFk65/i2bNbC4Xb/BjUDvIP7rPrwz3oyjWp7pWVMGukYawizSJs17/yR3PJWqXPIIumhjQr12TkWiXO+f5zn4NlMAsvEKDh6noAtwjn9c8AAoBgqKuwh035v0bIdCoKbL1hjB4E9izCen1DDfJg5aQPaRQrd7vvUp11I6xHVSWeRVyvd6DwyT5QuC4G9bQd8be0jF97p1zL9fUswn19dMrrybxKri/mAwOEehEXtmYyehzZs9pruWfqhzsAWByqH+KSQ+GergWUs80gmtVMqi/l0XcAVR1xHGb0uyvV5B0sQ0DQLTclV11YVd3+0vDWMmXUdAuZ9/BhbV9emDpV+tcVD/a6F2L+GAbSlv0vWERTNUmiiXLbssB8C5j3yOCu7aocT0mVYFekP3p3qTK1ZV97qXA5HSZJJqB9c6JKMeuDtFeG4irxJpmU7+KFLk2DZBamYFCXdhNNpIqC9CYJnF6K7r2Horb2FzkwoRkqU8zdQ31X2rw3yo2U990bMzF/q52SKbpZBo/l253TJQZFgqEz5dFDdU3E4ZAz6/KjygZ7ZVKCVdu6snBhn/D6sg+qj81zWJsGpVSE47amAWnT8FDrexdJnmDoaOZkCi/vV1U8rzoO1SZQSCW1E1HxEQ/ycg/ycm4WTE28WNDyOsp9Xbxl91c7cZIOqAQ5FXWdAJMefAebSgG6oBLoYeH1zRz6ZO9c6uzvaorCPVVR2OuE/bLx3TeiE9j1dYKrdDOGPkeHWcIRPZPbqSVtgSXs8GS6cPPrXuCBm79BZrBDLKUWIG9CC2BHJ1pX0AL78q1VYqDbnitpAVymT52tBa6+P8ExSC8g0kUFgB2d1x6jAM696XeKorzp6Ru56Y9gtJe+6X2EgDuA3obpx45OOE+76RurkmnhzqfdvfN19npqgOB8LbBDLG/N9B9BYtvQArtzLjzfuD1AF7TAEesPFy+dbEEBcPPsdUEB+GcpgPNv+h2i6LTpP9SUfSj3NeaD1/zE+5pcyt7rxSJS9lx8CTyexi/LRRxM1/nnq3bJ/HH6SAkOAkId4k0+FJO1czEpmwWB+VUwiZazL7G49u0HVwE2O2qeDixy+nvKH7jHTPvSuNzknICJgbkV1L1seXh97tzLzx3an13c2txRDgNrRJm8Q02oOz2PtIV5RN2YR4/TPQ32uGc06F2eR5nL3fzm8FqvEcOM4r0z+kP2DHAZbByrb9/gGRiKsqGd551uak9BjN5upJGdnNWSawNiLLJy+4MYJRVO6UKCNcRwAxlrve2IJTbKXU72YIO+Y4O7oHpIyYEz9iOBvJ8bHNA2GvM1WUuk5WIbsPLeow9zhvbwGLVHn6EJluI5e61rGXOZvkJlDhTrV2Nt8B2L/O4+dYas82MFdSe3XivdqOvsjXdEzb5KrJvvBmkAmkVeeF82wVKJNRLAOdBnB7PDCq3NMiWb6rjDDp1W82bAkcV+EL3BEfNNgc2q9o29tc3Usj0hKmDs2BvCmoRpe0MY0LU/qPqDbx6Nlf7q2LDBiKnxKDf2vb2cKfwsJ13ZV6uJaICP/EMAwhb7RvQnGgDjjRSCyMMH1JOy3VEnGm2bIHV5ML0HIzGncIkCKWCCjTUM3PwdTAWY3ncPqO8eoBBxaNhMdg3CsFz/aKH4zDCVepZJZt2cjJlL0v3p4Xf5MileCmGtyyZBToYrGGaonv4i0focBpLUCxofpBWbz9f76yeqPrTOcwTWxcWW4Yv+DWpvz49vz/QyjyZz+XvlCeKNvGT8VF0Xfs//b2K5ojbZ9k1z1pN4FW4PDXLRnLoK5zSAKsWZKzv6lYk3gjzVraKpWwvMVyBYxxhSM3f5OZhL4jitHfs5CVbzz/FU6qi7fwA=

List of all Java EE JSRs supported

Supported in JBoss EAP 4.3 / 5 /6

Supported in JBoss EAP 4.3

Supported in JBoss EAP 4.3 / 5.1

Supported in JBoss EAP 5.1

Supported in JBoss EAP 5.1 / 6

Supported in JBoss EAP 6

Java EE 7 and WebSocket API for Java (JSR 356) with AngularJS on WildFly

Maxime Gréau — Mon, 11 Nov 2013 00:00:00 GMT

This post was originally published in November 2013 and has been updated on February 3rd, 2016 for the following reasons:

Use the newest final version of WildFly 10.0.0
App deployed in a Docker Container at http://javaee7-websocket.mgreau.com thanks to Clever Cloud PaaS!
This app is not anymore available on OpenShift

Overview

This blog post describes the Java API for WebSocket Protocol (JSR 356) (which is one of four newest JSRs for the Java EE 7 platform) and provides a concrete application deployed on a WildFly 10 Docker Container and available online thanks to Clever Cloud .

[FR] La version française (HTML ou PDF) de ce post est basée uniquement sur la démonstration avec l’API Javascript sans AngularJS.

Once you will have read this post, you will be able to understand Arun Gupta's definition about what is it possible to do with WebSocket technology.

WebSocket gives you bidirectionnal, full duplex, communication channel over a single TCP.

— Arun Gupta (Java EE Evangelist at Oracle)
Devoxx UK 2013

Java EE 7 overview

The Java Platform Enterprise Edition was released in Version 7 (Java EE 7) in June 2013. In line with the two previous versions (Java EE 5 and Java EE 6) Java EE 7 always proposes to simplify the work of the developer. This version decorates previous versions with 3 main objectives :

embraces HTML5 (WebSocket API, JSON-P API, JAX-RS)
provide an even better productivity to developer (JMS)
meeting enterprise demands (Batch API, Concurrency Utilities)

Figure 1. The 3 goals of Java EE 7

Java Platform, Entreprise Edition 7 (JSR 342) can be summmed up around :

4 newest specifications : Java API for WebSocket 1.0, Java API for JSON Processing 1.0 , Batch Applications 1.0 and Concurrency Utilities for Java EE 1.0
3 specifications with major updates : JMS 2.0, JAX-RS 2.0 and EL 3.0
and 6 specifications with minor updates : JPA 2.1, Servlet 3.1, EJB 3.2, CDI 1.1, JSF 2.2 and Bean Validation 1.1

DEMO : AngularJS - HTML5 / JSR-356 API application deployed on WildFly 10 (Clever Cloud)

If you want to see right away what it looks like, you can access {link-demo}[the online application] whose code will be in part explained in this article. It’s an application that give you the ability :

to watch one or several tennis matches in live mode (Quarter Final U.S. Open 2013)
- click on each match that you want to access live
- click on exit button to disconnect from a specific match
to bet on the winner of the match
- each time a user bet on the same match, the counter is incremented
- at this end of the match, you will see the result of your bet

You will say: '"Nothing special !"', and you’re right :)

At first glance, it sounds like something already seen in many of today’s applications, but it’s the technique used behind which does matter because, as you will see below, everything is based around the standard of the new WebSocket protocol (ws:// ou wss://) and not on "HTTP hacking".

The technologies used for the development of this application are :

Frontend : HTML5, CSS, Javascript (WebSocket API) with 'Bootstrap CSS and AngularJS'
Backend : Java API for WebSocket, EJB, JSON-P, JAX-RS

Figure 2. US Open Application - Implementation of WebSocket (Java API et Javascript API)

Nope! This demonstration is not a chat application :) It’s obvious that the "chat demo" is the one that first comes to mind to illustrate the use of WebSocket technology. However, there are many other use cases, such as collaborative work on a text document online or online games like chess presented at the JavaOne 2013 keynote.

This application is available on the Cloud thanks to OpenShift, the cloud computing PaaS product by RedHat. It’s deployed on WildFly 8.0.0-Beta1 (normaly certified Java EE 7 to the end of 2013). To set up an application server like WildFly on OpenShit, you just need to read this Shekhar Gulati’s blog post Clever Cloud PaaS!

WebSocket (WS): a new protocol different from HTTP

HTTP is the standard protocol for the Web, it’s very effective for a lot of use cases but, nevertheless, has some drawbacks in the case of interactive Web applications :

half-duplex: based on the request/response pattern, the client sends a request and the server performs processing before sending a response, the client is forced to wait for a server response
verbose: a lot of information are send in HTTP headers associated with the message, both in the HTTP request and in the HTTP response
in order to add a server push mode, you need to use workaround (polling, long polling, Comet/Ajax) since there is no standard

This protocol is not optimized to scale on large applications that have significant needs of real-time bi-directional communication. This is why the new WebSocket protocol offers more advanced features than HTTP because it is:

based on 1 unique TCP connection between 2 peers (whereas each HTTP request/response needs a new TCP connection)
bidirectionnal : client can send message to server and server can also send message to client
full-duplex : client can send multiple messages to server, as well as server to client without waiting for a response from each other

'The term client is used only to define the one that initiate the connection. Once the connection is established, client and server become both peers, with the same capacity.'

The WebSocket protocol was originally intended to be part of the HTML5 specification but as HTML5 will be officially released in 2014, the WebSocket protocol is finally set, as well as HTTP protocol, by an IETF specification, with RFC 6455.

As shown in the diagram below, the WebSocket protocol works in two phases named :

handshake (open and close)
data transfer

Figure 3. How does the WebSocket protocol work

Opening Handshake

The Opening Handshake phase is a unique HTTP request/response between the one who initiate the connection (peer client) and the peer server. This HTTP exchange is specific because it uses the concept of Upgrade, defined in the HTTP specification. The principle is simple : Upgrade HTTP allows the client to ask the server to change the communication protocol and thus ensure that the client and server can discuss using a protocol other than HTTP.

Example 1. HTTP Handshake sample request

GET /usopen/matches/1234 HTTP/1.1     (1)
Host: wildfly-mgreau.rhcloud.com:8000  (2)
Upgrade: websocket  (3)
Connection: Upgrade (4)
Origin: http://wildfly-mgreau.rhcloud.com
Sec-WebSocket-Key:0EK7XmpTZL341oOh7x1cDw==
Sec-WebSocket-Version:13

1	HTTP GET method and HTTP 1.1 version required
2	Host used for the WebSocket connection
3	Request to upgrade to the WebSocket protocol
4	Request to upgrade from HTTP to another protocol

Example 2. HTTP Handshake Response sample

HTTP/1.1 101 Switching Protocols (1)
Connection:Upgrade
Sec-WebSocket-Accept:SuQ5/hh0kStSr6oIzDG6gRfTx2I=
Upgrade:websocket (2)

1	HTTP Response Code 101 : server is compatible and accept to send messages through another protocol
2	Upgrade to the WebSocket protocol is accepted

'When the upgrade request from HTTP to WebSocket protocol is approved by the endpoint server, it’s no longer possible to use HTTP communication, all exchanges have to be made through the WebSocket protocol.'

Data transfer

Once the handshake is approved, the use of WebSocket protocol is established. There are an open connection on the 'peer server side' as well on the 'peer client side', callback handlers are called to initiate the communication.
The Data transfer can now begin, so the 2 peers can exchange messages in a bidirectionnal and full-duplex communication.

As shown in the diagram named Figure 3, the peer server can send multiple messages ('in this example : 1 message for each scored point, 1 message each time any user bet on this game and 1 message at the end of the match') without any peer client response and the peer client can also send messages at any time ('in this example : betting on the winner of the match'). Each peer can send a specific message to close the connection.

With Java EE7 Platform, the peer server side code is written in Java while the peer client side code is in Java or Javascript.

Closing Handshake

This phase can be initiated by both peer. A peer that want to close the communication need to send a close control frame and it will received a close control frame too as a response.

WebSocket Javascript API (Client)

To communicate from a Web application with a server using the WebSocket protocol, it’s necessary to use a client Javascript API. It’s the role of W3C to define this API. The W3C specification for the JavaScript WebSocket API is being finalized. The WebSocket interface provides, among others, the following:

an attribute to define the connection URL to the server Endpoint (url)
an attribute to know the status of the connection (readyState : CONNECTING, OPEN, CLOSING, CLOSED)
some Event Handler in connection with the WebSocket lifecycle, eg :
- the Event Handler onopen is called when a new connection is open
- the Event Handler onerror is called when an error occured during the communication
- the Event Handler onmessage is called when a message arrives from the server
methods (send(DOMString data), send(Blob data)) with which it’s possible to send different type of flow(text, binary) to the Endpoint server

Example 3. Javascript source code example, from http://websocket.org

var wsUri = "ws://echo.websocket.org/";

function testWebSocket() {

	websocket = new WebSocket(wsUri);
	websocket.onopen = function(evt) { onOpen(evt) };
	websocket.onclose = function(evt) { onClose(evt) };
	websocket.onmessage = function(evt) { onMessage(evt) };
	websocket.onerror = function(evt) { onError(evt) }; }
}

function onOpen(evt) {
	writeToScreen("CONNECTED");
	doSend("WebSocket rocks");
}
function onClose(evt) {
	writeToScreen("DISCONNECTED");
}
function onMessage(evt) {
	writeToScreen('RESPONSE: ' + evt.data+'');
	websocket.close();
}

function onError(evt) {
	writeToScreen('ERROR: ' + evt.data);
}
function doSend(message) {
	writeToScreen("SENT: " + message);
	websocket.send(message);
}

JSR 386 : Java API for WebSocket protocol

As the W3C defines how to use WebSocket in Javascript, the Java Communitee Process (JCP) does the same for the Java world via the JSR 386.
JSR 356 defines a Java API for WebSocket protocol which be part of Java EE Web Profile and give the ability to :

create a *WebSocket Endpoint* (server or client), the name given to the Java component that can communicate via the WebSocket protocol
the choice of annotation or programmatic approach
send and consume messages controls, text or binary via this protocol
- manage the message as a complete message or a sequence of partial messages
- send or receive messages as Java objects (concept of encoders / decoders)
- send messages synchronously or asynchronously
configure and manage WebSocket Session (timeout, cookies…)

'The open source JSR-356 RI (Reference Implementation) is the project Tyrus'

WebSocket Server Endpoint

The transformation of a Plain Old Java Object (POJO) to a Server WebSocket Endpoint (namely capable of handling requests from different customers on the same URI) is very easy since you only have to annotate the Java Class with @ServerEndpoint and one method with @OnMessage :

import javax.websocket.OnMessage;
import javax.websocket.ServerEndpoint;

@ServerEndpoint("/echo") (1)
public class EchoServer {

	@OnMessage (2)
	public String handleMessage(String message){
		return "Thanks for the message: " + message;
	}

}

1	@ServerEndpoint transforms this POJO into a WebSocket Endpoint, the value attribute is mandatory in order to set the access URI to this Endpoint
2	the 'handleMessage' method will be invoked for each received message

Annotations

This Java API provides several types of annotations to be fully compatible with the WebSocket protocol :

Annotation	Role
@ServerEndpoint	Declare a Server Endpoint
@ClientEndpoint	Declare a Client Endpoint
@OnOpen	Declare this method handles open events
@OnMessage	Declare this method handles Websocket messages
@OnError	Declare this method handles error
@OnClose	Declare this method handles WebSocket close events

Annotation

Role

@ServerEndpoint

Declare a Server Endpoint

@ClientEndpoint

Declare a Client Endpoint

@OnOpen

Declare this method handles open events

@OnMessage

Declare this method handles Websocket messages

@OnError

Declare this method handles error

@OnClose

Declare this method handles WebSocket close events

@ServerEndpoint attributes are listed below :

value: relative URI or template URI (ex: "/echo", "/matches/{match-id}")
decoders: list of message decoder classnames
encoders: liste of message encoder classnames
subprotocols: list of the names of the supported subprotocols (ex: http://wamp.ws)

Encoders and Decoders

As described earlier in this article, the Endpoint server can receive different types of content in messages : data in text format (JSON, XML …) or binary format.
To effectively manage the messages from 'peers client' or to them in the application business code, it is possible to create Encoders and Decoders Java classes.

Whatever the transformation algorithm, it will then be possible to transform :

the business POJO to flow in the desired format for communication (JSON, XML, Binary …)
inflows in specific format(JSON, XML..) to the business POJO

Thus, the application code is structured so that the business logic is not affected by the type and format of messages exchanged between the 'peer server' and 'peers client' flows.

A concrete example is presented later in the article.

WebSocket Client Endpoint

This Java API also offers support for creating client-side Java Endpoints.

Example 4. Java Client Endpoint sample

@ClientEndpoint
public class HelloClient {

	@OnMessage
	public String message(String message){
		// code
	}
}

WebSocketContainer c = ContainerProvider.getWebSocketContainer();
c.connectToServer(HelloClient.class, "hello");

US OPEN Application

The sample application is deployed as a WAR outcome of a build with Apache Maven. In addition to the traditional management WebSocket lifecycle, the sending messages workflow is as follows :

each 'peer client' can connect to 1 or 4 live matches
each 'peer client' can disconnect from a match
at each point of a match, clients which are connected to this match will receive datas (score, service…)
the 'peer client' may send a message to bet on the winner of the match
each time that one 'peer client' bet on a match, all others 'peers clients' which have bet on the same match, will receive a message with the total number of bettors
at the end of the match, 'peers client' receive a message containing the name of the winner and a specific message if they bet on this match

All messages are exchanged in JSON format

The project layout is as follows :

Example 5. Maven project structure

+ src/main/java
   |+ com.mgreau.wildfly.websocket
      |+ decoders
         |- MessageDecoder.java   (1)
      |+ encoders       (2)
         |- BetMessageEncoder.java
         |- MatchMessageEncoder.java
      |+ messages       (3)
         |- BetMessage.java
         |- MatchMessage.java
         |- Message.java
      |+ rest       (4)
         |- RestApplication.java
         |- TournamentREST.java
      |- MatchEndpoint.java    (5)
      |- StarterService.java   (6)
      |- TennisMatch.java      (7)
+ src/main/resources
+ scr/main/webapp
   |+ css
   |+ images
   |+ js
      |+ live    (8)
         |- app.js
         |- controllers.js
         |- directives.js
         |- services.js
      |- websocket.js  (9)
   |+ templates
      |- bet.html
      |- match.html
      |- msg.html
   |- index.html
   |- live.html
pom.xml

1	Decode JSON messages sent from the 'peer client' (about bet on the winner) to a POJO ('BetMessage')
2	Encode in JSON format (via JSON-P), all messages about the winner and the match details for 'peers clients'
3	POJOs to handle messages sent between peers
4	REST endpoint to list all tournament’s matches
5	The application WebSocket Server Endpoint ('peer server')
6	EJB @Startup in order to initialize this application at deployment time
7	POJO to handle informations about the match
8	AngularJS files to handle several matches (live.html) with REST and WebSocket calls
9	File containing the implementation of Javascript API for WebSocket protocol to handle the client side of the communication for the simple case (index.html)

Maven dependencies for Java EE 7 API

Example 6. pom.xml with Java EE 7 dependencies


...

	UTF-8
	
	7.0

	
		javax (1)
		javaee-api
		${javaee.api.version}
		provided
	

...

1	It’s important to use the Java EE 7 dependencies to be able to deploy the same application in multiple Java EE application servers (WildFly, Glassfish…) without changing code.

Add Server Endpoint

This endpoint can receive messages about betting on the winner of a match (identified by match-id) and it can also send to 'peers client' all informations about the course of the match and bets.

Example 7. Server Endpoint : MatchEndpoint.java

@ServerEndpoint(
		value = "/matches/{match-id}",  (1)
		        decoders = { MessageDecoder.class }, (2)
		        encoders = { MatchMessageEncoder.class, BetMessageEncoder.class } (3)
		)
public class MatchEndpoint {

	private static final Logger logger = Logger.getLogger("MatchEndpoint");

 	/** All open WebSocket sessions */
	static Set peers = Collections.synchronizedSet(new HashSet());

	/** Handle number of bets by match */
	static Map nbBetsByMatch = new ConcurrentHashMap<>();

	@Inject StarterService ejbService;

	@OnOpen
	public void openConnection(Session session,
					@PathParam("match-id") String matchId) { (4)
    	session.getUserProperties().put(matchId, true);
    	peers.add(session);

    	//Send live result for this match
    	send(new MatchMessage(ejbService.getMatches().get(matchId)), matchId);
	}

	public static void send(MatchMessage msg, String matchId) {
	  try {
	    /* Send updates to all open WebSocket sessions for this match */
	    for (Session session : queue) {
    	  if (Boolean.TRUE.equals(session.getUserProperties().get(matchId))){
	        if (session.isOpen()){
		      session.getBasicRemote().sendObject(msg);	(5)
	        }
    	  }
	    }
	  } catch (IOException | EncodeException e) {
	    logger.log(Level.INFO, e.toString());
	  }
	}

	public static void sendBetMessage(Session session, BetMessage betMsg, String matchId)
	{
	  try {
	      betMsg.setNbBets(nbBetsByMatch.get(matchId).get());
	      session.getBasicRemote().sendObject(betMsg);
		  logger.log(Level.INFO, "BetMsg Sent: {0}", betMsg.toString());
	  } catch (IOException | EncodeException e) {
		  logger.log(Level.SEVERE, e.toString());
	  }
	}

	@OnMessage
	public void message(final Session session, BetMessage msg,    (6)
					@PathParam("match-id") String matchId) {
	  session.getUserProperties().put("bet", msg.getWinner());

	  //Send betMsg with bet count
	  if (!nbBetsByMatch.containsKey(matchId)){
	     nbBetsByMatch.put(matchId, new AtomicInteger());
	  }
	  nbBetsByMatch.get(matchId).incrementAndGet();
	  sendBetMessages(null, matchId, false);
	}

	@OnClose
	public void closedConnection(Session session,
	                    @PathParam("match-id") String matchId) {
	  if (session.getUserProperties().containsKey("bet")){
		  nbBetsByMatch.get(matchId).decrementAndGet();
		  sendBetMessages(null, matchId, false);
	  }
	  /* Remove this connection from the queue */
	  peers.remove(session);
	}
...
}

1	Access URI to this Endpoint, as the application context-root is '/usopen', the final URL looks like this : ws://:/usopen/matches/1234
2	'MessageDecoder' transforms the incoming JSON flow (about the bet on the winner) into a POJO 'BetMessage'
3	This 2 encoders add the ability to transform from 'MatchMessage' POJO and 'BetMessage' POJO to messages in JSON format
4	@PathParam annotation allows to extract part of the WebSocket request and pass the value (id match) as the parameter of the method, it is possible to manage several match with multiple clients for each match.
5	Send, to connected peers, messages about the course of the match. Thanks to the 'MatchMessageEncoder' object, simply pass the 'MatchMessage' object.
6	Handle received messages about the bet on the winner, thanks to the 'MessageDecoder' object, one of the parameters of this method is a 'BetMessage' object

Encodes and Decodes messages

To encode or decode messages exchanged between peers, simply implement the appropriate interface according to the message type (text, binary) and direction of processing (encoding, decoding), then redefine the associated method.
In the example below, it’s the encoder for MatchMessage POJO to JSON format. The API used to perform this treatment is also a new API released with Java EE 7 : Java API for JSON Processiong (JSON-P)

Example 8. Text Encoder : MatchMessageEncoder.java

public class MatchMessageEncoder implements Encoder.Text {

	@Override
	public String encode(MatchMessage m) throws EncodeException {
		StringWriter swriter = new StringWriter();
		try (JsonWriter jsonWrite = Json.createWriter(swriter)) {
			JsonObjectBuilder builder = Json.createObjectBuilder();
			builder.add(
				"match",
				Json.createObjectBuilder()
					.add("serve", m.getMatch().getServe())
					.add("title", m.getMatch().getTitle())
					...
			}

			jsonWrite.writeObject(builder.build());
		}
		return swriter.toString();
	}
}

HTML5 Web Client (single match - index.html)

The index.html page of this application loads the websocket.js file to implement the Javascript WebSocket API and thus interact with the Java Server Endpoint. This page handle only one single match.

Example 9. API Javascript implemented into websocket.js

var wsUrl;
if (window.location.protocol == 'https:') {  (1)
	wsUrl = 'wss://' + window.location.host + ':8443/usopen/matches/1234';
} else {
	wsUrl = 'ws://' + window.location.host + ':8000/usopen/matches/1234';
}

function createWebSocket(host) {
	if (!window.WebSocket) {    (2)
	...
	} else {
		socket = new WebSocket(host);   (3)
		socket.onopen = function() {
			document.getElementById("m1-status").innerHTML = 'CONNECTED...';
		};
		socket.onclose = function() {
			document.getElementById("m1-status").innerHTML = 'FINISHED';
		};
		...
		socket.onmessage = function(msg) {
			try {
				console.log(data);
				var obj = JSON.parse(msg.data);     (4)
				if (obj.hasOwnProperty("match")){   (5)
					//title
					m1title.innerHTML = obj.match.title;
					// comments
					m1comments.value = obj.match.comments;
					// serve
					if (obj.match.serve === "player1") {
						m1p1serve.innerHTML = "S";
						m1p2serve.innerHTML = "";
					} else {
						m1p1serve.innerHTML = "";
						m1p2serve.innerHTML = "S";
					}
					..
				}
				...
			} catch (exception) {
				data = msg.data;
				console.log(data);
			}
		}
	}
}

1	Choose the appropriate WebSocket protocol according to the HTTP protocol currently used (secure or not)
2	Check if the browser supports WebSocket API
3	Create the WebSocket object
4	Try to parse the JSON message sent by 'peer server', into the function called by onmessage Event Handler
5	Check the received object type (MatchMessage or BetMessage) to achieve adequate treatment with DOM

To find out which browsers are compatible with WebSocket API visit the website caniuse.com. Today, the latest versions of browsers are compatible excepted for Android and Opera Mini Browser, which represent, both together, only 3% of web traffic.

AngularJS Client (several matches - live.html)

As we saw on the beginning of this post, the version to handle severals matches is developed with AngularJS on the client side. So there are 4 JS files which contains :

app.js : just define the 'tennisApp' angular application
controllers.js : the TournamentCtrl controller
directives.js :
- bet directive and bet.html template to show the number of bettors and the current bet
- match directive and match.html template to handle live informations
- msg directive and msg.html template to shwo a message at the end of the match with the bet result if needed
services.js :
- WebSocketService : to handle WebSocket lifecycle with callback
- TournamentRESTService : to get all matches from REST Endpoint server
- BetsService and MatchesServices

'This post is not a tutorial about AngularJS since it’s my first app with this framework. But it was a quick solution to handle several matches on the client side. You can read the 3 following posts to better understand the JS code : directives in French and Refactoring to AngularJS directives and AngularJS WebSocket Service example'

Source code on Github

You can fork this project on Github at *https://github.com/mgreau/javaee7-websocket*

This sample application is basic, there could be many improvements like betting on other criteria…

'A feature that could be interesting technically, would be to create a new type of bet based on the coordinates of each winning point. Simply draw the ground through the HTML5 Canvas API and manage the coordinates selected by the user (such as winning point) and then compare with the actual coordinates at a point winner. '

Build and Deploy the WAR

Prerequisite :

JDK 7
Apache Maven 3.0.4+
Java EE 7 Application Server (WildFly 8)

In order to build the WAR, you just have to execute the Maven command below ;

mvn clean package

If your application server is WildFly, you can quickly deploy the WAR with the command below (WildFly has to be started) :

mvn jboss-as:deploy

The usopen application is then available at :

http://localhost:8080/usopen/ for the simple case with only native Javascript
http://localhost:8080/usopen/matches for the version with severals matches and AngularJS

WildFly 10 uses its new *Web Server called http://undertow.io[Undertow]* which replaces Tomcat.

'I didn’t test this application on Glassfish 4, but since I’m using only Java EE 7 API dependencies, it could work with the same code without problem. Let me know if you have troubles with GlassFish. '

Benchmark : WebSocket VS REST

In order to have some metrics about the performance of this new protocol, Arun Gupta has developed an application that allows compare the execution time of the same treatment performed by WebSocket code and REST code.

Each endpoint (REST Endpoint and WebSocket Endpoint) just do an "echo" so they only return the flows they receive. The web interface of the application allows you to define the size of the message and the number of times that the message must be sent before the end of the test.

The benchmark results, shown below, are quite eloquent :

Request	Total execution time REST Endpoint	Total execution time WebSocket Endpoint
Sending 10 messages of 1 byte	220 ms (63 ms)*	7 ms (29ms)*
Sending 100 messages of 10 bytes	986 ms (587 ms)*	57 ms (74 ms)*
Sending 1000 messages of 100 bytes	10 210 ms (4 636 ms)*	179 ms (288 ms)*
Sending 5000 messages of 1000 bytes	54 449 ms (18 049 ms)*	1202 ms (2862 ms)*

Request

Total execution time
REST Endpoint

Total execution time
WebSocket Endpoint

Sending 10 messages of 1 byte

220 ms (63 ms)*

7 ms (29ms)*

Sending 100 messages of 10 bytes

986 ms (587 ms)*

57 ms (74 ms)*

Sending 1000 messages of 100 bytes

10 210 ms (4 636 ms)*

179 ms (288 ms)*

Sending 5000 messages of 1000 bytes

54 449 ms (18 049 ms)*

1202 ms (2862 ms)*

'Values between ()* represent the same tests on my laptop (MacBook Pro 2013 i5 - 8Go - 128SSD) with WildFly 8.0.0-beta1 with default configuration.'

References about WebSocket

I would particularly recommend Arun Gupta's conferences, which allow you in less than 1 hour to discover and understand the WebSocket technology in general and the Java API for WebSocket.
For more advanced information, the ideal is IETF, W3C and Java specifications.

RFC 6455: The WebSocket Protocol - 'IETF Specification'
W3C: The WebSocket API - 'W3C Specification' (Candidate Recommandation)
JSR 356: Java API for WebSocket Protocol - 'Java Specification'
Adopt a JSR - JSR 356
Java EE 7 & WebSocket API - 'Arun Gupta’s conference @ SF' (from the 46th minute)
Getting Started with WebSocket and SSE - 'Arun Gupta’s conference @ Devoxx UK 2013'

'This article was structured based on the UK 2013 Devoxx conference.'

Conclusion

This article has introduced, through a concrete example, the WebSocket protocol, the HTML5 WebSocket API and Java API for WebSocket released with Java EE 7. It was already possible to use WebSocket with Java frameworks like Atmosphere but lacked a standard.
Today all standards are completed or about to be, this new technology meets a specific need and is promising in terms of performance. To be heavily used, this protocol will need to be allowed in businesses where often only the HTTP protocol is permitted.

Java EE 7 et l'API Java pour WebSocket (JSR 356)

Maxime Gréau — Fri, 27 Sep 2013 00:00:00 GMT

Cet article présente et met en oeuvre à travers un exemple concret et disponible en ligne, une des 4 nouvelles JSRs de Java EE 7, à savoir l’API Java pour communiquer via le protocole WebSocket (JSR 356), .

Après la lecture de cet article, vous devriez être en mesure de comprendre la définition de ce qu’il est possible de faire avec le protocole WebSocket, donnée lors de Devoox UK par Arun Gupta :

WebSocket gives you bidirectionnal, full duplex, communication channel over a single TCP.

Introduction à Java EE 7

La Plateforme Java Entreprise Edition est sortie en version 7 (Java EE 7) au mois de Juin 2013. Dans la continuité des versions Java EE 5 et Java EE 6, Java EE 7 propose toujours de simplifier le travail du développeur. Cette version agrémente les versions précédentes avec 3 objectifs principaux :

s’interfacer avec HTML5 (WebSocket API, JSON-P API, JAX-RS)
avoir une meilleure productivité (nouvelles annotations, moins de code inutile, meilleure cohésion entre JSRs)
répondre aux besoins des entreprises (Batch API, JMS API 2.0)

Figure 1. Les 3 objectifs de Java EE 7

Java Platform, Entreprise Edition 7 (JSR 342), se résume donc autour de :

4 nouvelles spécifications : Java API for WebSocket 1.0, Java API for JSON Processing 1.0 , Batch Applications 1.0 et Concurrency Utilities for Java EE 1.0
3 spécifications avec une mise à jour majeure : JMS 2.0, JAX-RS 2.0 et EL 3.0
ainsi que 7 spécifications mises à jour dans une version mineure : JPA 2.1, Servlet 3.1, EJB 3.2, CDI 1.1, JSF 2.2 et Bean Validation 1.1

DEMO : Application HTML5 / JSR-356 API déployée sur Wildfly 8 (OpenShift)

Les plus impatients peuvent accéder à la {link-demo}[démonstration en ligne] du code qui va être, en partie, expliqué dans cet article. Il s’agit d’une application qui permet :

de suivre un match de Tennis en Live (Finale de l’US Open 20013) sans aucune action autre que la connexion à l’URL
de parier sur le vainqueur du match

Vous allez me dire : "Rien d’extraordinaire !", et vous aurez raison.

A première vue, ce sont des choses que nous connaissons déjà sur beaucoup d’applications aujourd’hui, mais celle-ci est intéressante techniquement car comme vous le verrez au cours de l’article, tout est basé sur du standard autour du nouveau protocole WebSocket (ws:// ou wss://) et non sur du "hacking" de protocole HTTP.

Les technologies utilisées pour le developpement de cette application sont :

côté client : HTML5, CSS, Javascript (WebSocket API) avec 'Bootstrap CSS mais sans JQuery ou BootstrapJS'
côte serveur : Java API for WebSocket, EJB, JSON-P

Figure 2. Mise en oeuvre des WebSocket (Java API et Javascript API)

Non cette démonstration n’est pas une application de chat :) Il est évident que la démo "chat" est celle qui vient en premier à l’esprit pour illustrer l’utilisation de la technologie WebSocket. Néanmoins, il existe beaucoup d’autres cas d’utilisation, comme par exemple le travail collaboratif sur un document texte en ligne. Ou encore les jeux en ligne comme le jeu d'échec présenté lors de la keynote de JavaOne 2013.

'Cette application est disponible sur le Cloud grâce à OpenShift, la solution Cloud de RedHat. Elle est déployée sur le serveur d’applications Wildfly 8.0.0-Beta3 (normalement certifié Java EE 7 fin 2013). Pour mettre en place un serveur de ce type, il suffit de suivre le post de Shekhar Gulati'

WebSocket (WS) : un nouveau protocole différent de HTTP

HTTP est le protocole standard utilisé pour le Web, il est très efficace pour certains cas d’utilisation mais il dispose néanmoins de quelques inconvénients dans le cas d’applications Web intéractives :

half-duplex : basé sur le pattern request/response, le client envoi une requête puis le serveur réalise un traitement avant de renvoyer une réponse, le client est donc contraint d’attendre une réponse du serveur
verbose : beaucoup d’informations sont présentes avec les headers HTTP associés au message, aussi bien dans la requête HTTP que dans la réponse HTTP
pour faire du server push, il est nécessaire d’utiliser des méthodes de contournement (polling, long polling, Comet/Ajax) car il n’existe pas de standard.

Ce protocole n’est donc pas optimisé pour scaler sur des applications qui ont d’important besoins de communication temps réel bi-directionnelle. C’est pourquoi le nouveau protocole WebSocket propose des fonctionnalités plus évoluées que HTTP, puisqu’il est :

basé sur 1 unique connexion TCP entre 2 peers (en HTTP chaque requête/réponse necessite une nouvelle connexion TCP)
bi-directionnel : le client peut envoyer un message au serveur et le serveur peut envoyer un message au client
full-duplex : le client peut envoyer plusieurs messages vers le serveur et le serveur vers le client sans attendre de réponse l’un de l’autre

'Le terme client est utilisé uniquement pour définir celui qui va initialiser la connexion. Dès lors que la connexion est établie, le client et le serveur deviennent tous les deux des peers, avec les mêmes pouvoirs l’un par rapport à l’autre.'

Le protocole WebSocket devait à l’origine faire partie de la spécification HTML5 mais comme celle-ci sortira officiellement en 2014, il est finalement défini, au même titre que HTTP, par une spécification IETF, la RFC 6455.

Comme le montre le schéma ci-après, le protocole WebSocket fonctionne en 2 phases nommées :

handshake
data transfer

Figure 3. Explication du protocole WebSocket

Handshake

La phase nommée Handshake correspond à un unique échange requête/réponse HTTP entre l’initiateur de la connexion (peer client) et le peer serveur. Cet échange HTTP est spécifique car il utilise la notion d’Upgrade, définie dans la spécification HTTP.
Le principe est simple : l’Upgrade HTTP permet au client de communiquer avec le serveur pour lui demander de changer de protocole de communication et ainsi faire en sorte que le client et le serveur utilisent un protocole autre que HTTP pour discuter.

Example 1. Exemple de Requête HTTP Handshake

GET /usopen/matches/1234 HTTP/1.1     (1)
Host: wildfly-mgreau.rhcloud.com:8000  (2)
Upgrade: websocket  (3)
Connection: Upgrade (4)
Origin: http://wildfly-mgreau.rhcloud.com
Sec-WebSocket-Key:0EK7XmpTZL341oOh7x1cDw==
Sec-WebSocket-Version:13

1	Methode HTTP GET et version 1.1 obligatoires
2	Host utilisé pour la connexion WebSocket
3	Demande d’Upgrade vers le protocole WebSocket
4	Demande d’Upgrade HTTP pour changer de protocole

Example 2. Exemple de Réponse HTTP Handshake

HTTP/1.1 101 Switching Protocols (1)
Connection:Upgrade
Sec-WebSocket-Accept:SuQ5/hh0kStSr6oIzDG6gRfTx2I=
Upgrade:websocket (2)

1	Code HTTP 101, le serveur est compatible et accepte le changement de protocole
2	L’upgrade vers le protocole WebSocket est accepté

'Lorsque la demande d’upgrade du protocole HTTP vers le protocole Web Socket a été validée par le serveur endpoint, il n’y a plus de communication possible en HTTP, tous les échanges sont réalisés via le protocole WebSocket.'

Data transfer

Une fois que le handshake est acceptée, la mise en place du protocole WebSocket est donc acquise. Une connexion côté 'peer server' est ouverte ainsi que côté 'peer client', une gestion de callback est activée pour initier la communication.
La phase de Data transfer peut alors entrer en jeu, c’est-à-dire que les 2 peers peuvent désormais s'échanger des messages dans une communication bi-directionnelle et full-duplex.

Comme le montre le schéma de la Figure 3, le peer server peut envoyer plusieurs messages (dans l’exemple : 1 message à chaque point du match) sans aucune réponse du peer client qui, lui, peut également envoyer des messages à n’importe quel moment (dans l’exemple : le pari sur le vainqueur du match). Chaque peer peut envoyer un message spécifique afin de clôturer la connexion.

Dans Java EE7, le code côté peer server est en Java alors que le code côté peer client est en Java ou en Javascript.

WebSocket Javascript API (Client)

Pour communiquer à partir d’une application Web avec un serveur en utilisant le protocole WebSocket, il est nécessaire d’utiliser une API cliente en Javascript. C’est le W3C qui définit cette API.
La spécification W3C de cette API Javascript pour WebSocket est en cours de finalisation. L’interface WebSocket propose, entre-autres, les éléments suivants :

un attribut pour l’URL de connexion au server Endpoint (url)
un attribut sur l'état de la connexion (readyState : CONNECTING, OPEN, CLOSING, CLOSED)
des Event-Handler (gestionnaire d'évènement) pour s’adapter aux méthodes du cycle de vie des WebSocket, par exemple :
- l’Event-Handler onopen est appelé lorsqu’une nouvelle connexion est initiée
- l’Event-Handler onerror est appelé lorsqu’une erreur est reçue pendant la communication
- l’Event-Handler onmessage est appelé lorsqu’un message est reçu
les méthodes (send(DOMString data), send(Blob data)) avec lesquelles il est possible d’envoyer différents types de flux (texte, binaire) vers le serveur Endpoint

Example 3. Exemple de code Javascript, issue de http://websocket.org

var wsUri = "ws://echo.websocket.org/";

function testWebSocket() {

	websocket = new WebSocket(wsUri);
	websocket.onopen = function(evt) { onOpen(evt) };
	websocket.onclose = function(evt) { onClose(evt) };
	websocket.onmessage = function(evt) { onMessage(evt) };
	websocket.onerror = function(evt) { onError(evt) }; }
}

function onOpen(evt) {
	writeToScreen("CONNECTED");
	doSend("WebSocket rocks");
}
function onClose(evt) {
	writeToScreen("DISCONNECTED");
}
function onMessage(evt) {
	writeToScreen('RESPONSE: ' + evt.data+'');
	websocket.close();
}

function onError(evt) {
	writeToScreen('ERROR: ' + evt.data);
}
function doSend(message) {
	writeToScreen("SENT: " + message);
	websocket.send(message);
}

JSR 386 : Java API pour WebSocket

Le W3C définit donc comment utiliser WebSocket en Javascript, le Java Communitee Process (JCP) fait de même pour le monde Java via la JSR 386 .
La JSR 356 définit ainsi une API Java pour WebSocket qui propose :

la création d’un *WebSocket Endpoint* (serveur ou client), nom donné au composant Java capable de communiquer via le protocole WebSocket
la possibilité d’utiliser l’approche par annotation Java ou par programmation
la possibilité d’envoyer et de consommer des messages de contrôles, textuels ou binaires via ce protocole
- de gérer le message en tant que message complet ou par une séquence de messages partiels
- envoyer ou recevoir les messages en tant qu’objets Java (notion d'encoders/decoders)
- envoyer les messages en synchrone ou en asynchrone
la configuration et la gestion des sessions WebSocket (timeout, cookies…)
une intégration dans Java EE Web Profile

'L’implémentation de référence Java pour l’API WebSocket est le projet Tyrus'

WebSocket Endpoint : Serveur

La transformation d’un Plain Old Java Object (POJO) vers un WebSocket Endpoint de type serveur (c’est-à-dire capable de gérer des requêtes de plusieurs clients sur une même URI) est extrêment simple, puisqu’il suffit d’annoter la classe avec @ServerEndpoint et une méthode du POJO avec @OnMessage :

import javax.websocket.OnMessage;
import javax.websocket.ServerEndpoint;

@ServerEndpoint("/echo") (1)
public class EchoServer {

	@OnMessage (2)
	public String handleMessage(String message){
		return "Thanks for the message: " + message;
	}

}

1	L’annotation @ServerEndpoint transforme le POJO en WebSocket Endpoint, l’attribut value est obligatoire afin de préciser l’URI d’accès à cet Endpoint
2	la méthode handleMessage sera évoquée lors de chaque message reçu

Annotations

L’API met à disposition plusieurs types d’annotations afin d'être entièrement compatible avec le procotole WebSocket :

Annotation

Rôle

@ServerEndpoint

Déclare un Server Endpoint

@ClientEndpoint

Déclare un Client Endpoint

@OnOpen

Défini la méthode appelée pour gérer l'évenement d’ouverture de la connexion

@OnMessage

Défini la méthode appelée pour gérer l'évenement de réception d’un message

@OnError

Défini la méthode appelée pour gérer l'évenement lors d’une erreur

@OnClose

Défini la méthode appelée pour gérer l'évenement de clôture de la connexion

Les attributs de l’annotation @ServerEndpoint sont les suivants :

value: URI relative ou URI template (ex: "/echo", "/chat/{subscriver-level}")
decoders: liste de noms de classes utilisées pour décoder les messages entrants
encoders: liste de noms de classes utilisées pour encoder les messages sortants
subprotocols: liste de sous-protocoles autorisés (ex: http://wamp.ws)

Encoders et Decoders

Comme il a été décrit plus tôt dans cet article, le serveur Endpoint peut recevoir différents types de contenu dans les messages : des données au format texte (JSON, XML…) ou au format binaire.
Afin de gérer efficacement les messages provenant des 'peers client' ou à destination de ceux-ci dans le code métier de l’application, il est possible de créer des classes Java de type Decoders et Encoders.

Quelque soit l’algorithme de transformation, il va alors être possible de transformer :

le POJO métier vers un flux au format désiré pour l’envoi (JSON, XML, Binaire…)
les flux entrants dans format spécifique (JSON, XML..) vers le POJO métier

Ainsi, le code de l’application est organisé de telle façon que la logique métier n’est pas impactée par le type et le format de flux échangés entre le 'peer serveur' et les 'peers clients'. Un exemple concret est présenté dans la suite de l’article.

WebSocket Endpoint : Client

L’API propose donc également le support pour créer des Endpoints côté client en Java.

Example 4. Exemple de Client Endpoint en Java

@ClientEndpoint
public class HelloClient {

	@OnMessage
	public String message(String message){
		// traitement
	}
}

WebSocketContainer c = ContainerProvider.getWebSocketContainer();
c.connectToServer(HelloClient.class, "hello");

Application US OPEN

L’application exemple est déployée sous forme de WAR issue d’un projet Apache Maven. Outre la gestion classique du cycle de vie WebSocket, le workflow d’envoi de messages est le suivant :

à chaque point du match, les 'peers clients' recoivent les données du match (score, service…)
le 'peer client' peut envoyer un message pour parier sur le gagnant du match
à la fin du match, les 'peers clients' reçoivent un message contenant le nom du vainqueur

Tous les messages sont échangés au format JSON.

L’arborescence du projet est la suivante :

Example 5. Structure du projet Maven

+ src/main/java
   |+ com.mgreau.wildfly.websocket
      |+ decoders
         |- MessageDecoder.java   (1)
      |+ encoders       (2)
         |- BetMessageEncoder.java
         |- MatchMessageEncoder.java
      |+ messages       (3)
         |- BetMessage.java
         |- MatchMessage.java
         |- Message.java
      |- MatchEndpoint.java    (4)
      |- StarterService.java   (5)
      |- TennisMatch.java      (6)
+ src/main/resources
+ scr/main/webapp
   |+ css
   |+ images
   |- index.html
   |- websocket.js  (7)
pom.xml

1	Decode le message JSON provenant du 'peer client' concernant le pari sur le vainqueur en POJO ('BetMessage')
2	Encode à destination des 'peers clients', en JSON (via JSON-P), les messages contenant le détail du match et le résultat du pari sur le vainqueur
3	POJOs représentant les types de messages échangés entre peers
4	WebSocket Server Endpoint de l’application ('peer server')
5	EJB @Startup permettant d’initialiser l’application lors du déploiement
6	POJO pour gérer les informations du match
7	Fichier Javascript pour la communication WebSocket du 'peer client' via l’API Javascript

Dépendances Maven Java EE 7

Example 6. pom.xml


...

	UTF-8
	
	7.0

	
		javax (1)
		javaee-api
		${javaee.api.version}
		provided
	

...

1	il est important d’utiliser les dépendances de la spécification Java EE 7 afin de pouvoir déployer l’application dans plusieurs serveurs d’applications Java EE sans changement de code (Wildfly, Glassfish…)

Créer le Server Endpoint

Cet Endpoint permet de recevoir les messages concernant les paris sur le vainqueur du match et également d’envoyer aux 'peers clients' les informations du déroulement du match.

Example 7. Server Endpoint : MatchEndpoint.java

@ServerEndpoint(
		value = "/matches/{match-id}",  (1)
		        decoders = { MessageDecoder.class }, (2)
		        encoders = { MatchMessageEncoder.class, BetMessageEncoder.class } (3)
		)
public class MatchEndpoint {

	private static final Logger logger = Logger.getLogger("MatchEndpoint");

	/* Queue for all open WebSocket sessions */
	static Queue queue = new ConcurrentLinkedQueue<>();

	@OnOpen
	public void openConnection(Session session,
				@PathParam("match-id") String matchId) {	(4)
	    /* Register this connection in the queue */
	    queue.add(session);
	    session.getUserProperties().put(matchId, true);
	    logger.log(Level.INFO, "Connection opened for game : " + matchId);
	}

	public static void send(MatchMessage msg, String matchId) {
	  try {
	    /* Send updates to all open WebSocket sessions for this match */
	    for (Session session : queue) {
    	  if (Boolean.TRUE.equals(session.getUserProperties().get(matchId))){
	        if (session.isOpen()){
		      session.getBasicRemote().sendObject(msg);	(5)
		      logger.log(Level.INFO, "Score Sent: {0}", msg);
	        }
    	  }
	    }
	  } catch (IOException | EncodeException e) {
	    logger.log(Level.INFO, e.toString());
	  }
	}

	@OnMessage
	public void message(final Session session, BetMessage msg) {	(6)
	    logger.log(Level.INFO, "Received: Bet Match Winner - {0}", msg.getWinner());
	    session.getUserProperties().put("betMatchWinner", msg);
	}
...
}

1	URI pour accéder à cet Endpoint, comme le context-root de l’application est '/usopen', un exemple d’URL est ws://:/usopen/matches/1234
2	la classe 'MessageDecoder' permet de transformer le flux JSON entrant pour le pari sur le vainqueur en POJO 'BetMessage'
3	les 2 encodeurs permettent de transformer les POJO 'MatchMessage' et 'BetMessage' en flux JSON
4	l’annotation @PathParam permet ici d’extraire l'élément de la requête WS et de passer la valeur (identifiant du match) en paramètre de la méthode, il est ainsi possible de gérer plusieurs matchs avec des clients différents pour chaque match.
5	Envoi du message concernant le match aux peers connectés, grâce à l''Encoder' il suffit de passer en paramètre un objet 'MatchMessage'
6	Gestion de la réception des messages de pari sur le vainqueur du match, grâce au 'Decoder' la méthode prend en paramètre un objet 'BetMessage'

Encoder et Décoder les messages échangés

Pour encoder ou décoder les messages échangés entre peers, il suffit d’implémenter l’interface adéquate selon le type de message (Texte, Binaire) et le sens de traitement (encodage, décodage), puis de redéfinir la méthode associée.
Dans l’exemple ci-dessous, il s’agit de l’encodeur pour le POJO MatchMessage vers le format JSON. L’API utilisée pour réaliser ce traitement est une des nouvelles API de Java EE 7 : Java API for JSON Processiong (JSON-P)

Example 8. src/main/java/com/mgreau/wildfly/websocket/encoders/MatchMessageEncoder.java

public class MatchMessageEncoder implements Encoder.Text {

	@Override
	public String encode(MatchMessage m) throws EncodeException {
		StringWriter swriter = new StringWriter();
		try (JsonWriter jsonWrite = Json.createWriter(swriter)) {
			JsonObjectBuilder builder = Json.createObjectBuilder();
			builder.add(
				"match",
				Json.createObjectBuilder()
					.add("serve", m.getMatch().getServe())
					.add("title", m.getMatch().getTitle())
					...
			}

			jsonWrite.writeObject(builder.build());
		}
		return swriter.toString();
	}
}

Client Web HTML5

L’unique page HTML de cette application charge le fichier websocket.js pour mettre en oeuvre l’API Javascript WebSocket et ainsi intéragir avec le Server Endpoint Java.

Example 9. API Javascript : websocket.js

var wsUrl;
if (window.location.protocol == 'https:') {  (1)
	wsUrl = 'wss://' + window.location.host + ':8443/usopen/matches/1234';
} else {
	wsUrl = 'ws://' + window.location.host + ':8000/usopen/matches/1234';
}

function createWebSocket(host) {
	if (!window.WebSocket) {    (2)
	...
	} else {
		socket = new WebSocket(host);   (3)
		socket.onopen = function() {
			document.getElementById("m1-status").innerHTML = 'CONNECTED...';
		};
		socket.onclose = function() {
			document.getElementById("m1-status").innerHTML = 'FINISHED';
		};
		...
		socket.onmessage = function(msg) {
			try {
				console.log(data);
				var obj = JSON.parse(msg.data);     (4)
				if (obj.hasOwnProperty("match")){   (5)
					//title
					m1title.innerHTML = obj.match.title;
					// comments
					m1comments.value = obj.match.comments;
					// serve
					if (obj.match.serve === "player1") {
						m1p1serve.innerHTML = "S";
						m1p2serve.innerHTML = "";
					} else {
						m1p1serve.innerHTML = "";
						m1p2serve.innerHTML = "S";
					}
					..
				}
				...
			} catch (exception) {
				data = msg.data;
				console.log(data);
			}
		}
	}
}

1	Choix du protocole WS selon le type de protocole HTTP utilisé (sécurisé ou non)
2	Test du support par le navigateur de l’API WebSocket
3	Création du WebSocket
4	Sur l’Event-Handler onmessage , traitement du flux JSON reçu via le 'peer serveur'
5	Test du type d’objet reçu (Match ou Pari) afin de réaliser le traitement adéquat avec le DOM

Pour savoir quels sont les navigateurs compatibles avec l’API WebSocket, consultez le site caniuse.com. Aujourd’hui, les dernières versions des navigateurs sont compatibles exceptées pour Opéra mini et Android Browser, qui représentent, à eux deux, seulement 3% du traffic web.

Sources de l’exemple sur Github

Vous pouvez forker le code sur Github à l’URL *https://github.com/mgreau/javaee7-websocket*

Cette application exemple est très basique, les idées d’améliorations possibles sont nombreuses : gérer un tournoi avec plusieurs matchs, parier sur d’autres critères, voir en live les paris des autres internautes…

'Une feature, qui serait particulièrement intéressante techniquement, serait de créer un nouveau type de pari sur la zone de terrain des points gagnants. Il suffit de dessiner le terrain grâce à l’API HTML5 Canvas et de gérer les coordonnées de l’emplacement cliqué par l’internaute (comme zone gagnante) puis de les comparer aux coordonnées réelles lors d’un point gagnant.'

Construire et Déployer le WAR

Pré-requis :

JDK 7
Apache Maven 3.0.4+
Serveur d’applications Java EE 7 : Wildfly 8 ou Glassfish 4

Pour créer l’archive WAR, il suffit d’executer la commande Apache Maven ci-dessous ;

mvn clean package

Si vous utilisez Wildfly, le déploiement est automatique (le serveur doit être démarré) avec la commande ci-dessous :

mvn jboss-as:deploy

Il suffit ensuite d’accéder à l’URL : http://localhost:8080/usopen/

Performances : WebSocket vs REST

Afin d’avoir des métriques concernant les performances de ce nouveau protocole, Arun Gupta a developpé une application qui permet de comparer les temps d’execution d’un même traitement réalisé avec du code développé en utilisant les technologies WebSocket et REST.

Les 2 endpoints de l’application (REST Endpoint et WebSocket Endpoint) ne font que renvoyer le flux qu’ils recoivent. L’interface Web de cette application permet de définir la taille du message et le nombre de fois que ce message doit être envoyé avant la fin du test.

Les résultats de ses tests, présentés ci-dessous, sont éloquents :

Type de Requête

Temps execution
REST Endpoint

Temps execution
WebSocket Endpoint

Envoi de 10 messages de 1 byte

220 ms

7 ms

Envoi de 100 messages de 10 bytes

986 ms

57 ms

Envoi de 1000 messages de 100 bytes

10 210 ms

179 ms

Envoi de 5000 messages de 1000 bytes

54 449 ms

1202 ms

Références pour tout savoir sur les WebSocket

Je vous recommande plus particulièrement les conférences d' Arun Gupta, qui vous permettent, en moins d'1 heure, de tout connaître/comprendre sur la technologie WebSocket en général et sur l’API Java en particulier.
Pour des informations plus avancées, l’idéal reste les spécifications IETF, W3C et Java.

RFC 6455: The WebSocket Protocol - 'Spécification IETF'
W3C: The WebSocket API - 'Spécification W3C' (Candidate Recommandation)
JSR 356: Java API for WebSocket Protocol - 'Spécification Java'
Adopt a JSR - JSR 356
Java EE 7 & WebSocket API - 'Conférence Arun Gupta SF' (à partir de la 46e minute)
Getting Started with WebSocket and SSE - 'Conférence Arun Gupta Devoxx UK 2013'

'Cet article a été structuré en se basant sur la conférence Devoxx UK 2013.'

Conclusion

Cet article a introduit, grâce à un exemple concret, le protocole WebSocket, l’API WebSocket HTML5 et l’API Java pour les WebSocket sortie avec Java EE 7. Il était déjà possible d’utiliser les WebSocket en Java grâce à des frameworks comme Atmosphere mais il manquait un standard.
Aujourd’hui tous les standards sont finalisés ou en passe de l'être, cette nouvelle technologie répond à un besoin précis et est prometteuse en terme de performance. Pour qu’elle soit massivement utilisée, il faudra tout de même que ce protocole soit autorisée dans les entreprises là où bien souvent seul le protocole HTTP est disponible.

XStream on EAP 6 with Sun14ReflectionProvider

Maxime Gréau — Mon, 26 Aug 2013 00:00:00 GMT

If you want to use the Sun14ReflectionProvider with XStream, you have to add a dependency to the "sun.jdk" module.

...

Yahoo! Mail, t'es une messagerie, t'as pas de conversation ? non mais allô quoi !

Maxime Gréau — Wed, 24 Apr 2013 00:00:00 GMT

Cet article expose mon point de vue sur l’ergonomie, l’expérience utilisateur et les services rendus (ou pas) à l’internaute par Yahoo! Mail et Gmail. Je me base sur l’expérience de mon utilisation de Yahoo! Mail depuis 14 ans et de Gmail depuis 7 ans.

TIME: 15mn

Alors que Gmail vient de fêter, au début du mois, ses 9 ans d’existence, Yahoo! a sorti fin 2012 la dernière version de Yahoo! Mail créé en 1997. C’est l''occasion de faire un bilan de ces 2 acteurs principaux sur ce marché du webmail gratuit (Il ne sera pas question du 3e acteur, Hotmail, car je ne l’ai jamais testé). Il faut savoir que ces 3 acteurs revendiquent chacun plus de 280 millions d’utilisateurs dans le monde !

Il existe déjà un certain nombre de comparatifs de ces 2 webmails mais ils se focalisent trop souvent sur des éléments tels que le nombre de Gigas d’espace ou les protocoles activés… et pas sur les éléments importants d’une boîte de messagerie dans un navigateur à savoir : les fonctionnalités de base disponibles et l’expérience utilisateur associée. Autrement dit, comment faire pour nous rendre la vie la plus simple possible sur les principales actions que nous réalisons tous (geek ou novice) chaque jour : écrire un mail, lire un mail, répondre, faire suivre, envoyer une pièce jointe, rechercher dans nos messages…

Table des matières de l'article

Yahoo! Mail, une messagerie restée dans les années 90
- Des mauvais choix techniques et ergonomiques
Le mode "Conversation" : une fonctionnalité indispensable !
Des options qui font la différence
Du renouveau avec la nouvelle CEO Marissa Mayer ?…venue de Google :)
Merci Gmail. Une révolution en 2013 pour Yahoo! Mail ?

Yahoo! Mail, une messagerie restée dans les années 90

Depuis 1999 et la création de mon adresse mail @yahoo.fr, j’ai beau cherché, je ne vois pas de réelle évolution réalisée par Yahoo! pour sa messagerie si populaire. Je parle évidemment en terme de fonctionnalités pour l’utilisateur (même si en terme technique au niveau de l’interface Web on peut presque en dire autant). C’est vrai, à part les modifications "standards" liées aux évolutions des technologies Web, je ne vois pas ce que Yahoo! Mail a apporté de nouveau à ce jour.

Des mauvais choix techniques et ergonomiques

Yahoo! Mail n’a cessé de prendre les mauvaises décisions pour son produit phare ! Heureusement que son public est en partie composé (je présume) de personnes qui n’osent pas passer le cap de changer de client de messagerie par peur du changement justement; sinon Yahoo! Mail aurait fermé depuis longtemps.

Sa première version "classique" est celle que j’ai gardé le plus longtemps même (et surtout) après la première version "Web 2.0". Cette première version "Web 2.0" entièrement réalisée à base de composants Javascript se voulait une simulation, dans un navigateur Web, d’un client de messagerie installé localement sur le système d’exploitation (type Outlook ou Thunderbird) . Double erreur ! Tout d’abord techniquement cette version n'était vraiment pas au point ! Un temps d’initialisation interminable dans les premières versions du au chargement de la majorité des messages (et de leur contenu ?) avant le premier clic de l’utilisateur. Je ne vous parle même pas du "déroulement de souris" dans la boîte de réception qui vous affichait un sablier pendant un temps infini. Ensuite côté ergonomie, elle simulait une version "client local" sans l’exhaustivité des fonctionnalités et ajouté aux temps de réponses intolérables, le résultat : une frustration générale.

Le mode "Conversation" : une fonctionnalité indispensable !

Vous avez sûrement des amis ou de la famille avec qui vous échangez des mails pour une fête, un anniversaire…et vous vous retrouvez avec 20 mails dans votre messagerie car tout le monde répond à l’ensemble des destinataires. Sur Yahoo! Mail ça donne 20 lignes dans votre Boite de Réception avec comme sujet "Re:Re:Re:Re:Re:Re:Re:Re:Re:Re:Re:Re:Re:Re:Re:Cadeau Anniversaire Jean-Michel" Quel est l’intérêt d’avoir autant d’espace pris sur votre écran pour une discussion avec des réponses du type "OK pour moi" ? Si, en plus, vous avez plusieurs discussions différentes de ce type dans votre Boîte de réception, il devient impossible de retrouver le fil rapidement.

Figure 1. Exemple de discussion avec 1 ligne pour chaque message avec des "Re: Re: Re: Re: Re: Re: Re:"

Depuis longtemps dans Gmail vous avez par défaut le mode conversation activé qui vous permet d’avoir une seule ligne pour toute la conversation puis d’afficher le détail et le déroulement de la conversation à plusieurs lors du clic sur cette discussion. Ainsi, vous suivez beaucoup plus facilement le fil de discussion et l'écran principal de votre boîte de réception est épuré de tous ces messages.

Figure 2. Même type de discussion avec Gmail et le mode conversation : 1 ligne dans la boîte de réception puis le détail lors du clic

C’est pour moi une fonctionnalité majeure, indispensable vu le nombre de mails envoyés aujourd’hui quotidiennement 39 milliards en 2007 de personne à personne) comparé à 10 ans en arrière. Cette option peut tout de même être désactivée pour les personnes réfractèrent à ce mode de lecture des discussions.

Des options qui font la différence

90% des fonctionnalités d’un webmail sont communes à tous ceux qui proposent un logiciel de ce type. Il faut donc faire la différence sur les 10% restants. Et là que propose Yahoo! Mail de plus que les autres, que le standard ?…pas grand chose…j’ai même envie de dire RIEN ! Des exemples ? En voici quelques-uns, ce n’est bien sûr pas vital mais ce sont des petits plus très pratiques que l’on se doit d’attendre d’une multi-nationale comme Yahoo!, encore leader de la messagerie Web aux Etats-Unis fin 2012.

Oups, avec la pièce jointe c’est mieux :-)

Vous devez avoir souri en lisant ce titre, non ? Combien de fois cela vous est-il arrivé ? J’ai plutôt envie de vous demander : "Cela fait combien d’années que cela vous est arrivé pour la première fois ? 5 ans ? 10 ans ?". Et depuis, toujours rien de nouveau. Pourtant, techniquement ce n’est vraiment pas compliqué d’essayer de limiter ce genre d’erreur et donc d’aider l’utilisateur.

Clairement, soit vous envoyez une pièce jointe directement sans écrire de texte dans le contenu du message et là le risque d’erreur est quasi nul, soit vous saisissez un texte avant et c’est à ce moment là que l’oubli peut se produire. Dans ce deuxième cas, il y a de (très) fortes chances que vous fassiez référence au fait que vous allez envoyer une pièce jointe, non ? Il suffit donc d’analyser le contenu du message saisi avant l’envoi du mail à la recherche de mots clés tels que "pièce jointe", "pj", "fichier joint"… et de prévenir l’utilisateur qu’il a peut-être oublié quelque-chose. Gmail propose d’activer cette fonctionnalité et vous préviens par une boîte de dialogue lors de la tentative d’envoi du message :

Figure 3. Boîte de dialogue pour vous prévenir que vous avez peut-être oublié la pièce jointe

Pour ceux qui mettraient en avant le fait que Gmail analyse ici le contenu de vos messages, sachez que lorsque vous faîtes vos courses en magasin, vôtre parcours est analysé à votre insu par les caméras afin d’optimiser par la suite la vente des produits. Ne pensez donc pas que le fait que Yahoo! Mail ne propose pas cette fonctionnalité signifie qu’il n’analyse pas le contenu de vos messages également.

Trop tard, j’ai cliqué !

Combien de fois vous vous êtes dit après avoir cliqué sur le bouton ENVOYER : "Mince! il y avait qui en copie ??" ou "Arg, j’ai oublié machin et truc" ou encore "Zut, je voulais écrire ça aussi". Trop tard ??? Non, pas avec Gmail ! Et oui, quand on y pense, qu’est-ce que ça peut bien vous faire que votre message soit envoyé sur les serveurs destinataires *immédiatement après votre clic ou 5 secondes plus tard *(à part dans les services informatiques où les collègues entrent dans le bureau en disant "je viens de t’envoyer un mail il y a 2 secondes, tu l’as reçu ?!?" ). Vous ne maîtrisez de toute façon pas le chemin et le temps que va prendre votre message dans "le Cloud" pour se rendre à destination, et vous maîtrisez encore moins le moment où votre destinataire va être disponible pour lire votre message.

Gmail propose donc une option à activer qui permet de réellement envoyer le message après un délai paramètrable en secondes. Ainsi, si vous décidez que votre mail sera réellement envoyé 5 secondes après votre action d’envoi, vous aurez la possibilité de cliquer sur un lien "Annuler" pendant ce laps de temps. Sans action de votre part, le mail est envoyé automatiquement après 5 secondes, c’est donc totalement transparent pour vous sauf quand vous en avez besoin, génial non ? Encore une fois, il n’y a rien d’extraordinaire techniquement derrière ça, c’est simple, activable ou non par l’utilisateur et ça peut empêcher des désagréments importants (l’oubli que le chef était en copie….)

Figure 4. Vous avez un délai pour cliquer sur "Annuler" afin de ne pas envoyer le mail, passé ce délai le message est automatiquement réellement envoyé

Il est rangé où déjà ce mail ? si si je l’ai quelque part !

Vous avez sûrement déjà utilisé Microsoft Windows, là où on organise ses fichiers dans une arborescence de dossiers et donc si un document répond à plusieurs thèmes, il faut choisir un des dossiers ou dupliquer le document en question ou encore créer un raccourci. Et bien Yahoo! Mail fonctionne comme ça encore aujourd’hui (sans l’option raccourci) !! On déplace donc un mail dans un dossier, du coup il n’est plus dans la boîte de réception. La boîte de réception est donc un dossier comme les autres et un message ne peut apparaître que dans un seul dossier.

Avec Gmail tout est géré avec la notion de "libellé" et non pas de dossier. Ainsi chaque message est associé à un ou plusieurs libellés, il est donc possible de d’associer le message a des libellés tout en le gardant dans la boîte de réception (qui est un libellé particulier) ou de l’archiver (autre libellé) pour ne pas qu’il perturbe la boîte de réception. Les libellés peuvent être imbriqués et ils sont personnalisables graphiquement (couleur, police) pour mieux repérer rapidement les messages associés à ces libellés. On peut ensuite réaliser des recherches uniquement sur certains libellés. Bref, on peut faire au minimum la même chose qu’avec les dossier Yahoo! Mail mais surtout on dispose de 10 fois plus de possibilités pour organiser nos messages et donc les retrouver facilement.

Figure 5. Gestion des labels Gmail

Tout message est d’abord un brouillon !

Avec Gmail, lorsque vous commencez à écrire un mail, c’est-à-dire que vous avez débuté votre saisie de texte, automatiquement (sans action de votre part) votre message est un brouillon enregistré qui disparaîtra dès l’envoi du mail ou qui vous fera une sauvegarde si votre PC s'éteint ou votre navigateur plante violemment (si si ça arrive souvent dans ces moments là). Sur Yahoo! Mail, il faut faire la première démarche de dire "Oui je veux l’enregistrer comme brouillon" pour qu’ensuite il se comporte comme Gmail ou attendre 5 minutes pour qu’il le fasse automatiquement.

Il faut s’interroger, combien de fois vous vous dîtes : "Tiens je vais écrire un brouillon", Non la majorité du temps, vous écrivez un message qui, s’il n’est pas envoyé dans la foulée pour des raisons X ou Y, doit être enregistré sans une action de votre part, c’est implicite. C’est comme si vous commenciez un message sur un bout de papier pour votre femme, que vous entendez votre enfant pleurer dehors car il est tombé de la balançoire, vous revenez 20 minutes plus tard pour finir votre message…et là plus rien !! Parce qu’avant de partir en courant, vous n’avez pas dit "Attends, enregistre mon travail avant que je revienne".

Mais encore

Ce sont quelques exemples parmi tant d’autres : Gmail propose aussi une sécurité renforcée avec la validation en 2 étapes lors de la connexion à votre compte (un code temporaire, reçu par sms, est demandé après le mot de passe) ou encore la proposition automatique de destinataires souvent utilisés lors de l’écriture d’un mail à destination de plus de 2 personnes… Google met donc à disposition de l’utilisateur une liste très intéressante de fonctionnalités qu’il est toujours possible de désactiver si elles ne nous satisfont pas.

Du renouveau avec la nouvelle CEO Marissa Mayer ?…venue de Google :)

Il y a longtemps que je souhaite écrire cet article et, depuis, une nouvelle version de Yahoo! Mail est sortie fin 2012. Cette annonce correspond à la première version depuis l’arrivée à la tête de Yahoo! d’une ex-employée de Google, Marissa Mayer. Dans cette nouvelle version, on perçoit immédiatement une volonté d’aller dans le sens du renouveau : simplifier et épurer l’interface pour la rendre plus intuitive et optimiser la rapidité de fonctionnement. Après quelques jours d’utilisation (pour cet article justement), je peux confirmer que c’est la meilleure version de Yahoo! Mail que j’ai utilisé depuis… Yahoo! Mail classique.

Mais, on peut aussi noter, à juste titre, que dans cette annonce il n’y a aucune nouvelle fonctionnalité d’annoncée ! Peut-être pour la prochaine version ? Il faudra tout d’abord rattraper le retard sur les fonctionnalités majeures indispensables en 2013. Cela a commencé avec l’association récente de Yahoo! Mail avec Dropbox là où Gmail propose l’utilisation de Google Drive depuis fin 2012 pour la gestion des pièces jointes volumineuses.

Merci Gmail. Une révolution en 2013 pour Yahoo! Mail ?

J’ai (volontairement) été un peu dur avec Yahoo! Mail dans cet article mais cela vient de ma frustration de voir comment cette messagerie utilisée par autant de personnes (280 millions fin 2012) et gérée par une société aussi importante que Yahoo! peut avoir si peu évoluée au fil des années. Cette impression qu’aucun bon choix n’ait été fait après la version "classique". Je suis peut-être aussi influencé par mon métier qui fait que je me soucie de choses auxquelles la majorité des utilisateurs ne prêtent guère attention. Les éventuels commentaires qui suivront ce post m'éclairciront sûrement sur ces points. Seulement quand je voie les efforts réalisés par Google avec Gmail pour inventer de nouvelles fonctionnalités, je me dis que nous les utilisateurs pourrions avoir encore davantage de possibilités si la concurrence était plus accrue.

J’ai l’impression que la stratégie de Marissa Mayer va dans ce sens : améliorer l’expérience utilisateur des internautes qui utilisent massivement ce service.

Vous l’avez certainement compris, après avoir commencé avec Yahoo! Mail, je suis devenu pro-Gmail depuis quelques années maintenant mais je ne désespère pas de voir Yahoo! Mail s’améliorer. D’ailleurs, je leur propose un exemple d’ajout de fonctionnalité dans la version gratuite de leur webmail : l’accusé de lecture.

L’accusé de réception c’est bien, mais il est demandé lors du clic sur le sujet d’un message donc il permet de confirmer à l’expéditeur que le message est bien arrivé à destination (en gros de valider le fonctionnement des serveurs de messagerie !) mais le plus intéressant pour un utilisateur est d'être averti que le destinataire a bien pris connaissance du contenu du message envoyé; donc il est plus judicieux de proposer une action du style "Confirmer la lecture ?" à l’utilisateur lorsqu’il a potentiellement lu le message en entier (en bas de l’écran) ou lorsqu’il quitte le message (retour à la boite de réception…).

Au passage donc, Merci aux équipes de Google pour leur travail assez exceptionnel tout de même, et allez Yahoo! Mail, faites nous quelque chose de nouveau !! Ajoutez une fonctionnalité qui n’existe pas encore chez vos concurrents. Il est évident qu’il reste encore plein de choses à proposer aux internautes pour les aider dans l’utilisation quotidienne de leurs mails, des petites choses souvent simples mais efficaces.

Liens référencés dans cette article :

Gmail Blog officiel : http://www.google.com/mail/help/intl/fr/about.html
Yahoo! Mail Blog officiel :
Marissa Mayer :
Gmail, 9 ans :
Yahoo! Mail :
Yahoo! Mail et Dropbox :
Gmail et Google Drive :
Le nouveau Yahoo! Mail :
Yahoo! Mail n°1 aux USA :
Email en chiffres :
Les labels Gmail :

[Talk] Google Cloud Endpoints @ DevFest 2012

Maxime Gréau — Fri, 09 Nov 2012 00:00:00 GMT

My Session about Google Cloud Endpoints at DevFest Nantes 2012 with a Web application (Bacbkone JS, HTML5, AppEngine) and Android demo:

Google Cloud Endpoints - DevFest - Nantes 2012 from Maxime Gréau

Subversion - corriger les propriétés d'une révision SVN

Maxime Gréau — Mon, 30 Jul 2012 00:00:00 GMT

Language : FR / Temps de lecture : 10mn

Ce post explique comment mettre à jour les propriétés SVN d’une révision donnée d’un repository. Et notamment la propriété svn:date qui, lorsqu’elle est absente sur certaines révisions, bloque les checkout via le client SVNKit (utilisé par défaut dans le plugin Subversion de Jenkins CI).

Suite à des traitements d’administration sur des référentiels Apache Subversion 1.6, les jobs Jenkins CI ne parviennent plus à récupérer les sources d’un référentiel.

Les symptômes du problème

les jobs Jenkins ne parviennent plus à faire des "checkout" sur un repository
toutes les commandes SVN fonctionnent sur ce même repository via le plugin Eclipse (Subclipse - JavaHL)
ces mêmes commandes fonctionnent également en direct sur le serveur SVN
le message d’erreur dans la console Jenkins est le suivant :

Building in workspace /.../continuous-integration/jobs/mon-projet/workspace
Checking out a fresh workspace because there's no workspace at
/.../continuous-integration/jobs/mon-projet/workspace

Cleaning local Directory .
Checking out http://serveur/svn/repo1/mon-projet/trunk
ERROR: Failed to check out http://serveur/svn/repo1/mon-projet/trunk

org.tmatesoft.svn.core.SVNException: svn: E175002: REPORT of '/svn/repo1/!svn/vcc/default': 500 Internal Server Error (http://serveur)
 at org.tmatesoft.svn.core.internal.wc.SVNErrorManager.error(SVNErrorManager.java:64)
 ...
 Caused by: svn: E175002: REPORT of '/svn/repo1/!svn/vcc/default': 500 Internal Server Error (http://serveur)
 at org.tmatesoft.svn.core.SVNErrorMessage.create(SVNErrorMessage.java:208)
 at org.tmatesoft.svn.core.SVNErrorMessage.create(SVNErrorMessage.java:189)
 ...
 at org.tmatesoft.svn.core.internal.io.dav.DAVRepository.getDatedRevision(DAVRepository.java:200)
 ... 30 more
FATAL: null
java.lang.NullPointerException

L’accès à SVN est réalisé avec le module DAV, après une recherche dans les logs d’Apache, le message réel du serveur SVN est le suivant :

Fri Jul 27 10:04:45 2012] [error] [client ] Could not access revision times.  [500, #0]

Le problème se confirme lors de l’exécution des 2 commandes suivantes qui devraient affichées les logs des commit :

Accès aux sources via le système de fichiers

svn log --xml -v -r {2008-12-01T00:00:00Z}:{2012-07-13T15:00:00Z} file:///svn/repos/repo1

<?xml version="1.0"?>
<log>
svn: Failed to find time on revision 38307

Accès aux sources via le protocole HTTP

svn log --xml -v -r {2008-12-01T00:00:00Z}:{2012-07-13T15:00:00Z} http://serveur/svn/

svn: Server sent unexpected return value (500 Internal Server Error) in response to
REPORT request for '/svn/repo1/!svn/vcc/default'

L’aperçu des informations sur les révisions SVN dans l’IDE Eclipse confirme également le problème :

Figure 1. Révisions SVN dans IDE Eclipse

Solution

La solution consiste à ajouter une date sur les révisions en question.

Pour cela, il faut commencer par autoriser la modification des propriétés sur le référentiel SVN puis par exécuter la commande svn propset sur la révision concernée.

Autoriser la modification des propriétés SVN

Par défaut Apache Subversion définit un hook (pre-revprop-change) sur chaque référentiel SVN qui bloque la modification des propriétés SVN (hormis la propriété svn:log). il faut donc désactiver temporairement ce hook (faire une copie de sauvegarde avant)

echo '#!/bin/sh'  > repos/repo1/hooks/pre-revprop-change
echo 'exit 0'    >> repos/repo1/hooks/pre-revprop-change
chmod 755 repos/repo1/hooks/pre-revprop-change

Executer la commande SVN pour valoriser les propriétés d’une révision

Il est donc possible d'éxécuter le commande SVN pour valoriser la propriété svn:date

svn propset -r38307  --revprop svn:date '2011-09-21T19:55:44.000220Z' file:///svn/repos/repo1
property 'svn:date' set on repository revision 38307

On en profite également pour mettre à jour l’auteur du commit (svn:author) ainsi que le commentaire (svn:log) associé :

svn propset -r 38307 --revprop svn:author 'mgreau' file:///svn/repos/repo1
property 'svn:author' set on repository revision 38307

svn propset -r38307  --revprop svn:log 'Correction pb date de révision' file:///svn/repos/repo1
property 'svn:log' set on repository revision 38307

Aperçu du résultat dans l’IDE Eclipse

En rafraichissant la vue History dans Eclipse, on s’aperçoit que la révision 38307 contient désormais des informations pour la date, l’auteur et le commentaire de commit.

Figure 2. Révisions SVN OK dans IDE Eclipse

Script de mise à jour automatique

L’impression écran précédente met en valeur le fait que plusieurs révisions sont impactées par ce problème sur les propriétés SVN. Je met à disposition un script shell (svn-propset.sh) qui valorise ces propriétés SVN (date, auteur, commentaire) avec les valeurs passées en paramètres du script, pour un intervalle donné de révisions.

Exemple d’utilisation du script :

./svn-propset.sh -X -a mgreau -f 38215 -t 38321 -l "Correction pb date de révision"
 -d 2011-09-21T19:55:44.000220Z -u file:///svn/repos/repo1

Pour d’autres informations vous pouvez consulter les posts (en anglais) qui m’ont permis de résoudre ce problème: