Vaadin dependencies in Maven projects

The Vaadin framework has several dependencies but not all of them should be included in our war/ear artifacts.

The following table shows all Vaadin version 7.6/7.7 main modules and their meaning and usage

Module Description and usage
server This is the core of the framework. It has the following (transitive) dependencies: vaadin-shared and vaadin-sass-compiler
themes Compiled version of the standard Vaadin themes
client-compiled Compiled version of the standard Vaadin widgets set
client Vaadin and GWT classes for widgets
client-compiler Widgets compiler based on GWT Google Web Toolkit
push Optional module. It includes the support for push protocols (server to client) thanks to the Atmosphere framework
shared Common modules code. It is included as dependency in the server module
sass-compiler SASS to CSS compiler, used at build time and at run-time (“on-the-fly” compilation). It is included as dependency in the server module

Depending on the project requirements, the above modules should be included or not as project dependencies. We can identify two possible scenarios:

  1. Project without a custom widget set. It can have a custom theme
  2. Project with a custom widget set

In the first case (without a custom widget set) we need the following modules:

  • server
  • themes
  • push (optional)
  • client-compiled

while, if we have a custom widget set, we need to compile the widgets so the dependencies become:

  • server
  • themes
  • push (optional)
  • client (for build only)
  • client-compiler (for build only)

Note: the compiled custom widgets are included in our artifact

The following table summarizes the Maven dependencies:

Module ArtifactId Scope Required?
server vaadin-server compile yes
themes vaadin-themes compile yes
client-compiled vaadin-client-compiled runtime only if the project does not use custom widget set
client vaadin-client provided only with custom widget set
client-compiler vaadin-client-compiler provided only with custom widget sett. See also note below.
push vaadin-push compile optional
shared vaadin-shared vaadin-server dependency. No need to be specified in the pom.xml
sass-compiler vaadin-sass-compiler vaadin-server dependency. No need to be specified in the pom.xml

Note: the vaadin-client-compiler dependency is automatically included in the classpath by the Vaadin Maven plugin (vaadin-maven-plugin) when the custom widgets set should be compiled.

Tutorial: Correct SLF4J logging usage and how to check it

SLF4J is a very popular logging facade but, like all libraries we use, there is a chance that we use it in a wrong or at least in a not optimal way.

In this tutorial we will list common logging errors and how we can detect them using FindBugs. We will also mention PMD and Sonar Squid checks when relevant.

We will use two external FindBugs plugins which add logging detectors to FindBugs.

The first one is a SLF4J only plugin by Kengo Toda which contains SLF4J detectors only.

The second plugin is the popular FB Contrib which contains, among many others, some logging detectors.

For how to use FindBugs plugins, please refer to the following posts:

Note: in all examples we will assume the following imports:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

1. Logger definition

Wrong way:

W1a. Logger log = LoggerFactory.getLogger(MyClass.class);
W1b. private Logger logger = LoggerFactory.getLogger(MyClass.class);
W1c. static Logger LOGGER = LoggerFactory.getLogger(AnotherClass.class);

Correct way:

C1a. private static final Logger LOGGER = LoggerFactory.getLogger(MyClass.class);
C1b. private final Logger logger = LoggerFactory.getLogger(getClass());

General rule: the logger should be final and private because there are no reasons to share it with other classes or to re-assign it.

On the contrary there is no general agreement if the logger should be static or not. SLF4J plugin favors non static version (C1b) while PMD (“LoggerIsNotStaticFinal” rule) and Sonar (squid rule S1312) prefer a static logger (C1a) so both options should be considered as valid.

Additional info:

Please note that

  • in the static version (C1a), the logger name is usually in uppercase characters as all constant fields. If not, PMD will report a “VariableNamingConventions” violation.
  • in both cases, the suggested name is “logger/LOGGER” and not “log/LOG” because some naming conventions avoid too short names (less than four characters). Moreover log is the verb, more suited for a method name.
  • the W1c is wrong because we are referring to a class (AnotherClass) which is not the class where the logger is defined. In the 99% of the cases, this is due to a copy & paste from one class to another.

Related FindBugs (SLF4J plugin) checks:

  • SLF4J_LOGGER_SHOULD_BE_PRIVATE
  • SLF4J_LOGGER_SHOULD_BE_NON_STATIC
  • SLF4J_LOGGER_SHOULD_BE_FINAL
  • SLF4J_ILLEGAL_PASSED_CLASS

 

2. Format string

Wrong way:

W2a. LOGGER.info("Obj=" + myObj);
W2b. LOGGER.info(String.format(“Obj=%s”, myObj));

Correct way:

C2. LOGGER.info("Obj={}",myObj);

General rule: the format string (the first argument) should be constant, without any string concatenation. Dynamic contents (the myObj value in the example) should be added using the placeholders (the ‘{}’ ).

Motivation is simple: we should delay logging message creation after the logger has established if the message should be logged or not, depending on the current logging level. If we use string concatenation, message is built any way, regardless the logging level which is a waste of CPU and memory resources.

Related FindBugs (SLF4J plugin) checks:

  • SLF4J_FORMAT_SHOULD_BE_CONST Format should be constant
  • SLF4J_SIGN_ONLY_FORMAT Format string should not contain placeholders only

Related FindBugs (FB Contrib plugin) checks:

  • LO_APPENDED_STRING_IN_FORMAT_STRING Method passes a concatenated string to SLF4J’s format string

 

3. Placeholder arguments

Wrong way:

W3a. LOGGER.info("Obj={}",myObj.getSomeBigField());
W3b. LOGGER.info("Obj={}",myObj.toString());
W3c. LOGGER.info("Obj={}",myObj, anotherObj);
W3d. LOGGER.info("Obj={} another={}",myObj);

Correct way:

C3a. LOGGER.info("Obj={}",myObj);
C3b. LOGGER.info("Obj={}",myObj.log());

General rule: the placeholder should be an object (C3a), not a method return value (W3a) in order to post-pone its evaluation after logging level analysis (see previous paragraph). In W3a example, the mehod getSomeBigField() will be always called, regardless the logging level. For the same reason, we should avoid W3b which is semantically equivalent to C3a but it always incurs in the toString() method invocation.

Solutions W3c and W3d are wrong because the number of placeholders in the format string does not match the number of placeholders arguments.

Solution C3b could be somehow misleading because it includes a method invocation but it could be useful whenever the myObj contains several fields (for example it is a big JPA entity) but we do not want to log all its contents.

For example, let’s consider the following class:

public class Person {
private String id;
private String name;
private String fullName;
private Date birthDate;
private Object address;
private Map<String, String> attributes;
private List phoneNumbers;

its toString() method will most probably include all fields. Using the solution C3a, all their values will be printed in the log file.

If you do not need all this data, it is useful to define a helper method like the following:

public String log() {
return String.format("Person: id=%s name=%s", this.id, this.name);
}

which prints relevant information only. This solution is also CPU and memory lighter than toString().

What is relevant ? It depends on the application and on the object type. For a JPA entity, I usually include in the log() method the ID field (in order to let me find the record in the DB if I need all columns data) and, may be, one or two important fields.

For no reason, passwords fields and/or sensitive info (phone numbers,…) should be logged. This is an additional reason to not log using toString().

Related FindBugs (SLF4J plugin) checks:

  • SLF4J_PLACE_HOLDER_MISMATCH

 

4. Debug messages

IMPORTANT: rule #4 (see 5 rules article) guide us to use a guarded debug logging

if (LOGGER.isDebugEnabled()) {
LOGGER.debug(“Obj={}”, myObj);
}

Using SLF4J, if the placeholder argument is an object reference (see solutions C3a/C3b), we can use avoid the if in order to keep the code cleaner.

So it is safe to use the following:

LOGGER.debug(“Obj={}”, myObj);

 

5. Exceptions

Proper exceptions logging is an important support for problems analysis but it is easy to neglect its usefulness.

Wrong way:

W5a. catch (SomeException ex) { LOGGER.error(ex);}..
W5b. catch (SomeException ex) { LOGGER.error("Error:" + ex.getMessage());}..

Correct way:

C5. catch (SomeException ex) { LOGGER.error("Read operation failed: id={}", idRecord, ex);}..`

General rules:

  1. Do not remove the stack trace information by using getMessage() (see W5b) and not the complete exception. The stack trace often includes the real cause of the problem which is easily another exception raised by the underlying code. Logging only the message will prevent us to discover the real cause of the problem.
  2. Do show significant (for the human which will analyze the log file) information in the logging message showing a text explaining what we wanted to perform while the exception was raised (not the exception kind or messages like “error”: we know already something bad happened). What we need to know is what we were doing and on which data.

The C5 example tells we were trying to read the record with a specific ID whose value has been written in the log with the message.

Please note that C5 use one placeholder in the format string but there are two additional arguments. This is not an error but a special pattern which is recognized by SLF4J as an exception logging case: the last argument (ex in the C5 example) is considered by SLF4J as a Throwable (exception) so it should be not included in the format string.

Related FindBugs (SLF4J plugin) checks:

  • SLF4J_MANUALLY_PROVIDED_MESSAGE: the message should not be based on Exception getMessage()

Tutorial: logging during tests

Logging is a popular solution to show what the software is doing while it is running.

But what happens to the logging when we are unit testing our application with jUnit/TestNG ?

During the automated tests execution, we are usually not interested to see the logging messages because our main interest is the test results.

It would be nice to be able to disable logging messages during standard automated tests.

On the contrary, there are some cases where logging messages can be useful at test time. A typical example is when we are coding missing tests for some legacy code we do not want to touch before having a good test coverage in place. In this case logging messages on the console can help us to understand the code and how it works.

So we can identify three use cases:

  1. Running mode, when the application is executed: the logging is enabled and configured as required by the application
  2. Test execution mode, when the automated tests are executed all together: the logging messages should be disabled

  3. Test creation mode, when we are creating new tests: the logging messages are useful but it would be nice to have them in the console

Let see an example based on Maven and SLF4J, the popular logging facade.

Complete project can be found here.

Typical SLF4J configuration in the project pom.xml is the following:

        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>${slf4j.version}</version>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-log4j12</artifactId>
            <version>${slf4j.version}</version>
            <scope>runtime</scope>
        </dependency>

the slf4-api dependency is the main SLF4J library while the second one, slf4j-log4j12, is referencing one of the possible logging engines (LOG4J) that can work below the SLF4J.

This is the running mode configuration. In this example, the project resources will contain a LOG4J properties file which dictates what, how and where LOG4J should log.

The same situation happens when we are using a different logging engine like java.util.logging (JDK) and Logback. See Slf4J manual for more details.

In the Test execution mode we do not want logging so we can simply add the following scope test dependency

        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-nop</artifactId>
            <version>${slf4j.version}</version>
            <scope>test</scope>
        </dependency>

The NOP Logger (slf4j-nop) simply discards all logging.

Important: the dependencies order in the pom.xml is significant. Put the slf4j-nop dependency just after the slf4-apidependency so it will be used during the tests even if there is another logging engine in the dependency.

When there are multiple logging engines dependencies in the pom.xml, SLF4J will show anyway a message like the following:

    SLF4J: Class path contains multiple SLF4J bindings.
    SLF4J: Found binding in [jar:file:.m2/repository/org/slf4j/slf4j-nop/1.7.12/slf4j-nop-1.7.12.jar!/org/slf4j/impl/StaticLoggerBinder.class]
    SLF4J: Found binding in [jar:file:.m2/repository/org/slf4j/slf4j-log4j12/1.7.12/slf4j-log4j12-1.7.12.jar!/org/slf4j/impl/StaticLoggerBinder.class]
    SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation.
    SLF4J: Actual binding is of type [org.slf4j.helpers.NOPLoggerFactory]

To summarize, a complete configuration example is the following:

        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>${slf4j.version}</version>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-nop</artifactId>
            <version>${slf4j.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-log4j12</artifactId>
            <version>${slf4j.version}</version>
            <scope>runtime</scope>
        </dependency>

Again, the last dependency should be adjusted to match the desired logging engine.

As I mentioned before, logging can be useful when creating new tests. In this case (Test creation mode), we can temporarily replace the slf4j-nop with the slf4j-simple dependnecy which enables the SLF4J Simple logger.

The logging messages will now be shown in the console window during tests execution as System.err messages. No configuration file is needed.

By default, the Simple logger does not log DEBUG messages. Standard logging level is INFO.

You can customize the Simple logger behaviour using system variables documented here.

A smart way to define Simple logger configuration is using the [Surefire plugin configuration section] (http://maven.apache.org/surefire/maven-surefire-plugin/examples/system-properties.html):

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>2.18.1</version>
                <configuration>
                    <systemPropertyVariables>
                        <org.slf4j.simpleLogger.defaultLogLevel>DEBUG</org.slf4j.simpleLogger.defaultLogLevel>
                        <org.slf4j.simpleLogger.showDateTime>true</org.slf4j.simpleLogger.showDateTime>
                    </systemPropertyVariables>
                </configuration>
            </plugin>
        </plugins>
    </build>

In the systemPropertyVariables section we can create tags with the Simple logger variable name. In the above example, DEBUG and timestamp logging are enabled.

FindBugs plugins

FindBugs is a key code quality tool for Java based projects.

It includes several dozens of bug patterns which are used by FindBugs to identify potential bugs and, more in general, weaknesses in our code.

FindBugs has a plugin architecture which can be used to extend the set of detectors (bug patterns) used during the analysis.

There are few open source projects which aim to develop FindBugs plugin.

My preferred one is Fb-Contrib which contains a significant amount of additional detectors. See here for the complete list. Most of them are really useful to detect poor code quality.

Another interesting plugin is Find Security Bugs; the focus here is on security vulnerabilities (list here) like using unsecured random generator or not checking data received from the user.

Let’s have a look at versions dependencies:

JDK FindBugs FB-Contrib Find Security Bugs
7 and 8 3.x 6.x 1.3 and above
5 and 6 2.x 5.x 1.2

All plugins are released in .jar format and they can be easily added to the FindBugs :

  • FindBugs stand-alone: place the jar in the plugins dir inside FindBugs installation dir
  • Eclipse FindBugs plugin: use the plugin options to specify the plugin path or place the jar file inside FindBugs plugins dir
  • NetBeans FindBugs integration: use Custom FindBugs Plugins button inside Editor → Hints → FindBugs page.
  • IntelliJ FindBugs plugin: add new plugin in the Plugin Configuration tab.

After adding new plugins, review the list of detectors enabled. New detectors are usually added but not enabled.

Tutorial: unit testing in Eclipse with moreUnit plugin

Eclipse Kepler, even in the Java EE Developers edition, does not include a good enough support for automatic tests development. Both NetBeans and IntelliJ have superior native support for testing. For example, if you rename one class, Eclipse does not rename its test class.

To overcome such limitations, we need to install a plugin.

In this tutorial, I will describe moreUnit (http://moreunit.sourceforge.net/), a plugin which extends Eclipse testing support. I will not cover moreUnit installation because it is quite standard.

Let’s create a standard ant based Eclipse project. In the example the project name is “EclipseTest” and the main package is “it.gualtierotesta”.
20140522_01
In the package, I’ve created a new Java class named MyClass with the following content:

package it.gualtierotesta;

public class MyClass {

    private String msg;

    public String message() {
        return generateMsg();
     }

    private String generateMsg() {
        return "Hello " + msg;
    }

    public String getMsg() {
        return msg;
     }

    public void setMsg(String msg) {
       this.msg = msg;
    }

}

Very simple. We want now to create a unit test to check the message() method. While in the Java Editor window, you should press Ctrl+R (or, from the contextual menu, MoreUnit –> Jump To Test) to trigger test class creation.

20140522_02
where we can select our preferred unit library. In this tutorial we will use JUnit 4.

Press “Finish” to confirm. Note: Eclipse will eventually ask you to add JUnit library to the project build path.

In the created test class (MyClassTest.java file), add the following contents:

package it.gualtierotesta;

import org.junit.Assert;
import org.junit.Test;

public class MyClassTest {

@Test
 public void showMessage() {
     // given
     MyClass sut = new MyClass();
     sut.setMsg("Gualtiero");
     // when
     String res = sut.message();
     // then
    Assert.assertEquals("", res);
 }

}

Note: sut is system under test.

In the test class window, press Ctrl+R to run the test. Test will fail:
20140522_03This is expected because the Assert.assertEquals check for the wrong result.
Change the Assert line as following:

Assert.assertEquals("Hello Gualtiero", res);

E re-run the test (Ctrl+R). Test will now succeed.
20140522_04
Note: in the test method body I added some comment lines to divide the body instructions in three sections. Given section is where the test texture is prepared, when is the execution of the method under test and the then section marks the results checks instructions (assertions). This is a good habit to make test strategy clearer. It comes from BDD, Behavior Driven Development (http://en.wikipedia.org/wiki/Behavior-driven_development).

 

A nice moreUnit feature is to mark the Java source file icon with a small green rectangle to show that the class has a test class.
20140522_05We have now our test running without failure but still our setup is not correct: test classes should be placed in a different source folder because they should not be packaged and released to the user.

Traditional approach is to have src dir for Java source files and test dir for test classes.

We create now a new folder named “test” under project root:
20140522_06
Then in the Java Build Path section of the project properties we add the new test folder as one of the project source folders:
20140522_07
Finally we configure moreUnit to use the “test” folder as the place to create and look for test classes:
20140522_08
Finally we can move the MyClassTest.java to the test folder (or create it again).

At the end, the project configuration is the following:
20140522_09As shown in this short tutorial, moreUnit plugin simplify a lot test classes handling in Eclipse.

Moreover, moreUnit offers special support for mocking libraries users. The test class creation wizard has additional pages to insert mocking specific instructions in the test class:
20140522_10
In this page, you can select the dependencies you want to mock and moreUnit will add specific mocking instructions. For more info about Mockito, have look here and here.

Tutorial: license headers in NetBeans (reloaded)

An alternative solution to the native NetBeans license header management (see my previous post) is the “License Changer” plugin by nhoffmann available on NetBeans plugin portal (http://plugins.netbeans.org/plugin/17960/license-changer).

The plugin is based on license template concept. NetBeans installation includes several license templates (Tools → Templates) for the most popular Open Source licenses: 2014-02-25_pic01The plugin uses one of the available templates. If you have your own license file, you have to include it in the template list (but the plugin help on this).

NOTE: all custom license files will be saved in the NetBeans User Directory. You can have a look at the beginning of View → IDE Log for your real path.

With the plugin we can do more that native NetBeans solution except for one use-case: when you have a proprietary and project specific license. In this case NetBeans let us save the license file within the project (so all team members can use it) while, with the plugin, all licenses are stored in the user NetBeans installation (which is not shared across the team).

Let’s describe now the plugin.

After plugin installation, you can select a file or a package and apply “Change License Header” (see picture below).

2014-02-25_pic02A wizard starts. On the first page we can select the files types on which the plugin should operate on (see 1). Nice added feature is the possibility to change the line endings character (see 2).

2014-02-25_pic03

 

Second page of the wizard is the following:

2014-02-25_pic04

We can select the license from the template list (see 1) or browse the disk for a custom license file (see 2) which will be included in the template list by the plugin.

IMPORTANT: The checkbox “Set as default project license” (see 3) is very important. If checked, the plugin will save the selected license in the project configuration (the same used by native NetBeans solution). All new created files (including file types not supported by the plugin) will inherit the setting and they will have the correct license header.

After license selection:

2014-02-25_pic05The rest of the wizard is very simple.

NOTE: One little annoying problem with the plugin is that the selected license is not kept for the following plugin invocations.

Typical procedure :

  1. install the plugin
  2. run the plugin on a project file or package or folder,in order to include all existing project files
  3. use standard NetBeans File → New File procedure to create new project files

NetBeans plugin for file line endings

Nowadays it is common to work in a multi-platform (Windows, Linux, Mac) development environment and that means different file line endings characters.

To terminate text files lines, Windows uses two characters, CR (Carriage Return) and LF (Line Feed), while Linux and Mac OS X use LF character only and “old” Mac OS uses CR only.

Three platform, three combinations. We are not lucky.

NetBeans can handle all combinations, while opening and saving text files (.java, .html, .css, .php,….) but this is not necessarily the case for all developments tools we are using.

Best approach is to use just one and, we are now lucky, one plugin can help us.

The “Change Line Endings on Save” plugin can be found here and on NetBeans plugin portal.

Once installed, we can decide to have NetBeans or project based setup. Development teams should use project based setup so every developer uses the same configuration.

NetBeans based setup can be found on Tools → Options → Editor → Line Endings as in the following image:

2014-02-02 fig1Project based setup is available on project Properties page:

2014-02-02 fig2Note: project setup is saved in the nb-configuration.xml file (in the project root dir).