Maven essentials for the impatient developer

We just recently published a new Maven page at vaadin.com/maven. It contains Maven “coordinates” for Vaadin projects and a super handy generic Maven repository search. But does it help you if you haven’t used Maven before? No. Are our most interesting Java examples built with Maven these days? Yes.

This tutorial tries to cover Maven basics as little as possible, but still enough to get your first Maven project up and running. Don’t expect to learn how to setup a perfect build for your project based on this tutorial alone, but you should be able to grab an existing Maven project, set it up in your IDE, build it and run it.

Requirements: pom.xml and the code

The “heart” of the Maven built project is the pom.xml file at the root of your project structure. It contains the essential metadata about your project that various tools, including the mvn command line tool, can work with. The fundamental difference to e.g. ANT build scripts is, it doesn’t directly express how your project should be built, but what it is like. With Maven you do not configure your build, but describe your project’s characteristics, like artifact type and dependencies, to the pom.xml.

Your tools, like your IDE, then read the pom.xml file to know how to handle your project. Modern IDEs, even the latest versions of Eclipse, understand pom.xml files really well, out of the box. Thus, your Maven built project doesn’t need to contain IDE settings files in your source code repository. Still, you can set it up in a couple of seconds and your co-worker can do the same in his/her favourite IDE. If your IDE can’t automatically configure the project for you, you are either doing something wrong or some very custom things.

Importing the project to IDE

The best tool to get started with Maven is probably your favourite IDE. With IDE you can easily navigate in your source code, build the project, make changes and learn! Use the IDE dude, CLI is for the nerds! :-) Seriously, it is often handy to have Maven installed as a CLI tool as well.

IDEs have lived longer than Maven, though, so not all things are necessarily that intuitive yet. The most critical part is to import it correctly to your IDE. Choose your IDE from following tabsheet to get the relevant instructions only.

My favourite IDEs, NetBeans and IntelliJ, are the easiest ones with Maven projects. If you have checked your Maven project from a source code management system, you can just go and do “File-> Open/Open Project” and choose the project’s root directory you wish to open. NetBeans has clearly the best Maven support and it even synchronizes the project settings like its name and Java compiler settings from the IDE UI back to pom.xml automatically.

With IntelliJ, a small gotcha is to click “Enable auto configuration on pom.xml change” on the very first time IntelliJ asks it. You will pretty much always want that and make changes in build settings to pom.xml instead of IntelliJ settings.

With Eclipse, you should always open Maven projects using “File->Import->Maven->Existing Maven projects”. This way Eclipse figures out it is a Maven project and knows what to do with it. The same thing can be accomplished via direct source control imports, but the above is the method I can trust with Eclipse.

You should always try to make all build settings to pom.xml instead of IDE specific settings. This way e.g. your CI server can still build your project if you e.g. change its Java version. If you change something in pom.xml, Eclipse will detect this, but it most often does nothing but just shows a small red warning in your project. In this case, you can right click on the project and choose “Maven->Update Project…”. This will basically re-configure the project in Eclipse, based on the metadata that you describe in the pom.xml.

Although Eclipse is said to have the worst Maven support among the major IDEs, it kind of goes quite far when trying to understand the pom.xml. In some cases, it shows scary red warnings about build details it cannot interpret. Most often this is nothing serious and everything works fine if you just execute one full Maven build before actually starting with the project.

 

A freshly imported Vaadin project showing errors that can safely be marked as ignored.

In the above example with vaadin-maven-plugin, Eclipse doesn’t know what to do with “widgetset compilation”. In an ideal world, our Eclipse integration should support Maven projects better and yell that “I can take care of this”. Currently you can just brutally use “autofix” (CTRL-F1) and force Eclipse to ignore these steps and execute full build via Maven once after import. During the build, vaadin-maven-plugin generates the required client side resources for your project and everything works just fine.

Words about multi-module projects

Maven emphasis modularization. One logical “project” may consist of multiple modules. In case your example project contains multiple pom.xml files, it is probably a so called multi-module project. Opening just its “parent-pom”, most often located at the root directory of the project, your IDE will by default suggest to open all its child modules. Don’t be afraid, just open them all if you are not sure what you are doing.

Building the project

In case you decided to install the CLI build tool, you can build a Maven project with “mvn install” from the root directory of the project. A multi-module project will automatically cascade the call to sub modules. If you have a basic Java project or a library, it will create a jar file into your target folder, a war file for web app projects and something else for other projects. The build also puts the “artifact” to your local repository.

Even if you imported the project to an IDE, I’d suggest to do a full build once you have imported it. During the build there are probably some dependencies that are downloaded and there might be some generated resources which need to be built. In Maven conventions, all generated stuff, like Java .class files are saved under “target” directory.

In NetBeans the full build is always done via Maven, so you can just use the Build Project functionality. Right clicking on the project, you can also choose “Custom->Goals” to specify the exact Maven command and custom parameters. Focusing the project also shows available plugin goals in the Navigator panel.

Running “Make Project” in IntelliJ is almost the same as “mvn package” via CLI, but the build is executed by the IDE instead of the “real Maven build”. This is usually slightly faster than the full Maven build as a separate build process doesn’t need to be spawned. After importing the Maven project to IntelliJ, I tend to execute a full build with Maven once to make sure everything works fine. Using the quick search feature, open “Maven Projects” panel. To build the project using Maven, double click “install” under the your-module-name->Lifecycle.

In Eclipse the most essential Maven goals are easily accessible via right click on the project and choosing “Run as”. For a newly imported module, you can choose “Maven install” to get its initial build done. You can also use custom goals or properties easily via “Maven build…”.

Speeding up the build

Your first build with Maven will take long. Period. Maven will famously download you the “whole interwebs”. It needs a lot of modules for various build steps and it also takes care of dependencies for your project. Next builds will be substantially faster because Maven caches the dependencies and builds plugins to your local Maven repository.

If there are lots of tests that you wish to skip during a development build, learn from the very beginning the parameter to skip all tests. To make a basic build without tests, issue mvn install -DskipTests. The parameter can also be passed with all IDEs.

When you progress with your Maven skills, be sure to learn about profiles as well, which can for example help you to pass e.g. the above skipTests parameter during the development on your workstation. Also Maven profiles are well supported by IDEs.

Executing the actual application

The most interesting step with your cool example application is naturally to execute it locally, see how it looks like and try to make some changes to it. So how do you actually execute your Maven built application? Well, it depends. There is no common Maven goal to execute an “application”.

If the project is a standard Java web application, the artifact of your project is a WAR file and packaging tag in your pom.xml has value war. There are a couple of methods, of which the most universal is to build the project and deploy the war file manually to a compatible server. But most probably you want to launch it directly from your IDE to make things like debugger and your JRebel work out of the box.

Jetty Maven Plugin goals shown by the Navigator panel in NetBeans. Choosing jetty run will launch the web project in a jetty server managed by Maven. No need to install a server at all.

Most application servers have excellent plugins for Maven. They can help you do the deployment to a remote server, but also to launch it locally. If your project has for example TomEE, WildFly or Jetty plugin installed, it is probably trivial to start the application. Those server plugins all have a “run” goal to launch an ad-hoc development server and deploy the webapp into it. Super-handy for quick hacking and testing, and you don’t even need to download and install the server separately.

As an example, you can check out my recent jpa-addressbook example from github and just issue ”mvn wildfly:run” from the project root or use the same goal with your IDE. Although it is a “heavy” Java EE project with “gazillions of dependencies”, Maven will with one single command package the application and deploy it to a local server, which it downloads for you, if necessary. In a moment you have your application available for testing from http://localhost:8080/.

 

The Run on Server feature in Eclipse works well with properly imported Maven WAR projects.

Another option to run your web application is to use your built-in server support in your IDE. All modern IDEs detect the project as a web app and you can just use your existing IDE skills to deploy it to your development server. Based on the details in the pom.xml, your IDE should know exactly how to do it for you.

Not all applications on Earth are web apps, and in fact, there are Java web apps that aren’t actually packaged as WAR files. For example, Spring Boot apps are by default packaged as plain old JAR files. Their execution starts from the good old main method and packaged apps are launched in the traditional “java -jar“ style. The embedded web server will then serve your web application.

A Spring Boot application about to be “booted” directly from the good old main method in IntelliJ.

In this “main method style” application initialization, you can during the development phase just execute the main method directly from the IDE. All IDEs have always contained a shortcut to this, via context click on your class containing the main method. If you are working from command line, your Maven project might also have maven-exec-plugin configured that can issue the correct “java -jar” command with possibly a bit more complex classpath. And with those trendy Spring Boot apps, you can just issue “mvn spring-boot:run”.

Summary

I originally planned to cover lots of other topics like conventions, build phases, plugins, dependency management, versioning, releases, generic project settings and java settings as well. But hey, with the above instructions you can already check out and play with pretty much any of the most interesting modern Maven built Java projects. I think this is exactly the Maven essentials for the inpatient developer.

In case you later want to learn more, I strongly suggest to go to maven.apache.org, read the basic documentation and understand the core concepts. Maven isn’t the easiest tool to start with, but it isn’t rocket science once you understand its fundamentals. But now it is time to return to the example project you initially wanted to play with, or verify your skills with my awesome Spring Data + Vaadin CRUD. The trick with it (Spring Boot application) is to realize it is kind of more like a normal Java application than a web application! ;-)

If you want a really quick start for your project, you could also watch our recent webinar on Vaadin archetypes.

Don't marginalize your UX

I have seen hundreds of projects fail. But also much more projects succeed in the past 6 years I have worked at Vaadin. It doesn't really matter if it's a 10 person team in Texas or a 1 person project in Laos, they are all basically the same and succeed or fail for the same reason. Any library you choose for your project, be it Vaadin (great choice by the way! ;) or anything else, there are issues that are much more important.

What is the most critical part to get right?

Some of the customers I’ve met assume that choosing Vaadin for their UI layer automatically gives them the best app on the market. Sure, it helps, a lot, but the best framework in the world will only get you so far. Looking at the projects that succeeded vs. those that didn’t, there seems to be a common denominator: User Experience Design. Every single project where I have had dedicated UX time available during the project has been more successful than the ones that didn’t.

So, how do I do this ‘UX’, anyway?

User Experience design is something all great things have in common: it isn’t restricted to software alone. But in our field, UX determines how your users will respond to your application. Please do not confuse design with ‘prettiness’. An app that has not been designed from the user’s point of view, but looks good, will still frustrate your user to no end, no matter how many hours you spend on polishing the colors. Creating good design takes some time, but it will also clarify your goals, making the rest of your project much more smooth.

The best practice I’ve found for proper design is to start with the most boring stuff: specifications. Wait, I’m not talking about waterfall here. What I mean is that you as a project manager (or team lead, or even product owner) need to have a clear vision about what problem your application is trying to solve. Before any coding takes place, sit down with a small group: the product owner, the project manager, and a UX designer. In the meeting, hammer out a plan that will allow the UX designer plenty of time to get to grips with the problem domain, to study other solutions that may already exist, and most importantly, get to know the end users of the application. When done, the designer will produce the UI blueprints (here is a nice list of things that might be included: http://www.helloerik.com/ux-is-not-ui), from which you can start the implementation. On smaller projects this process can take anywhere from two to four weeks; in bigger projects, you could easily spend two or three months on this.

I have learned the hard way that excellent developers rarely make excellent designers. Having dedicated people for usability issues makes all the difference. We can however all learn something about usability and a first step towards that could be the recently aired webinar we had on UX Best practices below.

A month without any coding, are you serious?

Yes. I can’t emphasize that enough.

Don’t marginalize your UX

Some people think that UX is a one-time thing. Doing it for a week or so in the beginning should be fine. Or, even worse, assume that UX is something you can create after the project is mostly done. Some also think that time will pay for a fully featured theme for the app. Sorry, but that’s not the way you’ll get results.

Specifications and features change, this is one of the fundamental laws of software development. If your development team is agile, why shouldn’t your UX be, too? User experience design is something that lives alongside development in your project. You should review and expand on it during development. Same goes for the theme; creating one in the beginning of the project is probably not a good idea, since you’ll end up changing it alongside your UX. My recommendation is to use the lightest theme you can during development, and leave the actual theme for later. But you can still prepare for the theme; make sure your layouts are sane, that you have proper style naming, and remember to keep up a discussion with the designer on how the design is moving forward.

Speaking of the actual styling, as a rule of thumb, usually a good time to start looking at your theme is 2/3 through the project. Typically things have settled down in the design and implementation, but you still have plenty of time for a nice theme.

There's also life under the surface

You will need more than just good UX. You will need to actually create the application. For that, you will need other tools; data storage, reporting, deployment, monitoring, issue trackers, code repositories, and much more. Choose what works best for you, Vaadin will behave nicely with 99% of them. Knowing what tool to use is something I’ll leave out of this article; suffice to say that a tool you know is usually better than one you don’t.

What you also have to do, is decide what sort of testing you want to do. In my experience, having at least some regression tests is critical for an application. Without them, you’ll end up fixing the same issue multiple times, since your developers will not be able to test everything they did, in addition to everything everyone else has already done, before they merge a new feature. Even if you have no other tests, regression tests are the time saver you can’t afford to be without.

What makes a software project rock?

Creating an application with Vaadin can be rewarding, but it can also be frustrating. Knowing where and how to do design choices is a tricky field, one that can’t be fully taught in blog posts. I still hope I’ve given you some pointers on how to approach these things in your Vaadin project. If you follow these, I guarantee your apps will rock and your users will thank you.

  • Start with UX. Do this before writing any code.
  • Evolve your UX. Your requirements will change, let the design adapt.
  • A pretty application is not automatically a good UX, far from it.

 

And if you leave this blog post with just one thing, here’s a final pro tip: buying the tools to make a Ferrari doesn’t give you a Ferrari.

Check out the UX wiki

State of the Vaadin Framework

Greetings from the Vaadin Framework team. While there hasn’t been too many updates aside from release announcements, I think every now and then it is good to let everyone know where we are and what we are doing.

In Vaadin 7.4 we introduced the declarative format and released one of the most important components in the whole framework - the Grid. But there is more.

Vaadin 7.5 is getting quite close to feature freeze which means that beta 1 should be expected within a couple of weeks and a final release about one month after that. While the team has mainly been focusing on bugfixes and the upcoming Vaadin Spring add-on, there are also some new features in progress.

For Grid, we are adding column reordering using drag and drop, column hiding through a context menu and expandable row details. On top of this, we are also finalizing declarative syntax support to be fully compatible with the upcoming Designer 1.0, as well as adding some other minor enhancements. We were also considering drag and drop column resizing in Grid for this release, but scheduling constraints forced us to postpone it to 7.6 instead.

Beyond 7.5, we have already started considering what to focus on in Vaadin 7.6, scheduled for October. Right now it seems like the main focus will be on an armada of small productivity enhancements for you developers. While we already have collected a good list of suggestions from you, it is not too late to comment right here what you need - which parts of the framework cause most friction for your application development?

Btw, if you completely missed the Grid update, you can get a quick overview from the recent webinar we had: