About this book

Vert.x is a platform for building highly networked and scalable applications on the Java Virtual Machine. Using just a few powerful building blocks, it provides a powerful framework that scales to a multitude of different usage scenarios. It is one of the few truly polyglot development platforms, providing seamless interoperability between components written in JavaScript, CoffeeScript, Java, Ruby, Python, and Groovy.

Real-time Web Application Development using Vert.x 2.0 will show you how to get up and running on the powerful Vert.x platform. Using a hands-on example of developing a mind map editor, this book shows you how to build a Vert.x application from the ground up, and on the way introduces all of the major building blocks of Vert.x, such as integrating with a database, polyglot development, and so on.

Real-time Web Application Development using Vert.x 2.0 will guide you step-by-step through building a Vert.x application so that you’ll be able to start building one of your own in no time. From initiation to scaling, you’ll develop a mind map editor application with real-time collaboration capabilities. As you go through the development process, you’ll get to know all the building blocks of Vert.x applications: Verticles, Worker Verticles, the Event Bus, and Modules. You’ll also see how Vert.x apps seamlessly reach into client devices by building a client application using the Vert.x Event Bus Bridge, Knockout.js, and D3.js.

Real-time Web Application Development using Vert.x 2.0 guides you through the whole Vert.x application development process, tying all of the important concepts together with a simple, realistic example application.

Publication date:
September 2013


Chapter 1. Getting Started with Vert.x

The web frameworks that powered much of the page-based web aren't necessarily cut out to serve the real-time web. This is where Vert.x excels. Vert.x has been designed from the ground up to enable you to build scalable and real-time web applications.

In this chapter, you will take your very first steps in Vert.x development by installing Vert.x, and running it from the command line.

You will also get familiar with some key Vert.x concepts and put them into use by creating a web server for serving static files.


Installing Vert.x

To install Vert.x, you simply download and unpack a ZIP file. A Vert.x installation lives in a self-contained directory structure, which can be located anywhere on your machine.

It's also recommended that you include the path to the Vert.x executable in your PATH environment variable. This will make working with the Vert.x command line easier.

In the following pages, we'll go through these steps, after which you'll have everything up and running.

Prerequisite – Java

Vert.x is written in Java, and needs the Java JDK 7 to run the program. Older versions of Java are not supported.

Checking your version of Java

If you're not sure whether you already have Java or you're not sure about its version, launch a terminal or a command prompt and check the Java version:

java –version

In the output, you should see a version number beginning with 1.7. If not, you'll need to obtain the JDK before you can start working with Vert.x.


If you are on Windows, it may be the case that Java is installed but the java command still isn't available in the command prompt. If you suspect this is the case, check if the directory C:\Program Files\Java exists. If it has a subdirectory beginning with jdk1.7.0 you're good to go.

Obtaining Java

If you're running Mac OS X or Windows, I recommend you to install Oracle's Java SE Version 7 or newer. You will find it from Oracle's website at http://www.oracle.com (be sure to select the full JDK or the for Developers option, and not just the JRE or the for Consumers option). Follow the instructions provided by the web page and the installer to complete the installation.

If you're running Linux, I recommend you install OpenJDK 7 from your package manager, if available. On Ubuntu and Debian, it will be in the openjdk-7-jdk package:

apt-get install openjdk-7-jdk

Alternatively, Oracle's Java SE is also available for Linux.

Obtaining a Vert.x distribution

Because Vert.x is built in Java, the distribution package is the same regardless of your operating system or hardware. Head to http://vertx.io/, and download the latest version of Vert.x.


In the following instructions, the Vert.x version is marked as x.x.x. Substitute it with the version of Vert.x that you have downloaded.

The next steps will be different for different operating systems. You'll need to unpack the downloaded ZIP file and add the bin directory of the distribution to your PATH environment variable. This will allow you to easily launch Vert.x from anywhere on your machine.

OS X and Linux

If you are using the Homebrew package manager on OS X, you can just install the Vert.x package and skip these steps.

Other package manager integrations may exist, but obtaining the distribution from the Vert.x website is still the most common installation method.

  1. Start a command line shell (such as the terminal applications on OS X and Ubuntu), and navigate to a directory into which you want to install Vert.x. For example, if you have one named dev within your Home directory:

    $ cd ~/dev
  2. Unzip the Vert.x distribution package you downloaded earlier. This will create a folder named vert.x-x.x.x.final, from where we will run Vert.x.

    $ unzip ~/Downloads/vertx-x.x.x.final.zip
  3. Open your .bash_profile file in a text editor.

    $ pico ~/.bash_profile
  4. Add the path to the bin subdirectory of the Vert.x distribution to the PATH environment variable, by adding the following line:

    export PATH=$PATH:$HOME/dev/vert.x-x.x.x.final/bin
  5. Save and close the editor.

  6. The Vert.x executable will now be in your PATH for all the future terminal windows you open. You can also apply this change immediately to your current terminal window by typing:

    $ source ~/.bash_profile

You can now proceed to Running Vert.x section to test your installation.


Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.


To install Vert.x on Windows 7 or Windows 8, perform with the following steps:

  1. Open File Explorer (in Windows 8) or Windows Explorer (in Windows 7) and find the downloaded Vert.x ZIP file. Right-click on the file and select Extract All….

  2. Select the folder into which you want to install Vert.x (for example, one named dev within your Home directory). After selecting the directory, click on Extract.

  3. Open Control Panel. Navigate to System and Security | System | Advanced system settings | Environment Variables.

  4. In the System variables listbox, find the variable Path. Select it and click on Edit.

  5. At the end of the existing variable value, add a semicolon followed by the path to the bin folder of the extracted Vert.x distribution.

  6. If you do not already have an environment variable named JAVA_HOME in either the User variables or the System variables listbox, you will need to add it, so that Vert.x will know where to find Java.

    • Below the System variables listbox, click on New. Set the name as JAVA_HOME and the value as the path to your Java JDK 7 installation folder (for example, C:\Program Files\Java\jdk1.7.0_10).

You can now proceed to the Running Vert.x section to verify your installation.


Running Vert.x

Let's verify that the Vert.x installation was successful by trying to run it. Go to a terminal (on OS X/Linux) or a Command Prompt (on Windows). Try running the vertx command:

vertx version

This should simply output the version of your Vert.x distribution. If you see the version, you have successfully installed Vert.x!

The vertx command has multiple uses, but the main one is to launch a Vert.x instance, which is something you'll be doing a lot.


A Vert.x instance is the container in which you run the Vert.x applications. It is a single Java virtual machine, which is hosting the Vert.x runtime and its thread pools, classloaders, and other infrastructure.

If you want to see the different things that you can do with the vertx command, just run it without any arguments, and it will print out a description of all the different use cases:


Embedding Vert.x

As an alternative to using the vertx command, it is also possible to launch an embedded Vert.x instance from within an existing Java (or other JVM language) application. This is useful when you have an existing application and want to integrate the Vert.x framework in to it.

To embed Vert.x, you need to add the Vert.x JARs to your application's classpath. The JARs are available in the Vert.x installation directory, and also as Maven dependencies. After this, you can instantiate a Vert.x instance programmatically.

We won't be using embedded Vert.x instances in this book, but you can find more information about it in the Embedding the Vert.x platform section of the Vert.x documentation available at http://vertx.io.


Your first verticle – Hello world

Now that you have Vert.x installed and are able to run it, you're all set to write your first Vert.x application. This application will consist of a single verticle that prints out the classic "Hello world" message.


A verticle is the fundamental building block of the Vert.x applications. You can think of a verticle as a component of an application, which typically consists of one or a few code files and is focused on a specific task.

Verticles are similar to packages in Java or namespaces in C#; they are used to organize different parts of a system. However, as opposed to packages or namespaces, verticles are also a runtime construct with some interesting properties when it comes to concurrency. We will discuss them in Chapter 2, Developing a Vert.x Web Application.

Verticles can be implemented in any of the supported Vert.x languages (JavaScript, CoffeeScript, Java, Ruby, Python, or Groovy). For this one, let's use JavaScript.

Create a file named hello.js (it doesn't matter where you put it). Open the file in an editor and add the following contents:

var console = require("vertx/console");
console.log("Hello world");

That's all the code you need for this simple application.

Now, let's launch a Vert.x instance and run hello.js in it as a verticle:

vertx run hello.js

This should print out the message. Even though there's nothing else to do, the Vert.x instance will keep running until we explicitly shut it down. Use Ctrl + C to shut down the Vert.x instance when you're done.

So, what just happened?

  • You wrote some code that loads the Vert.x console library and then uses it to log a message to the screen

  • You fired up a Vert.x instance using the vertx command

  • In that instance, you deployed the code as a verticle


In JavaScript verticles, we will always use the require function to load the code from within the Vert.x framework or from other JavaScript files. The require function is defined by the CommonJS modules/1.1 standard, which Vert.x implements. You can find more information about it at http://wiki.commonjs.org/wiki/Modules/1.1.

You have just gone through the basic process of writing and running a Vert.x application. Now, let's turn to something a bit more useful.


A web server

Our application is going to need a web server, which is used to serve all the HTML, CSS, and JavaScript files to web browsers.

Vert.x includes all the building blocks for setting up a web server, including the HTTP networking and filesystem access. However, there is also something more high-level we can use, that is, a publicly available web server module, which does file serving over HTTP for us out of the box.


Vert.x modules are a solution for packaging and distributing the Vert.x applications or pieces of application functionality for reuse.

A module can include one or more verticles, and an application can make use of any number of modules written in different programming languages.

Vert.x has a growing public-module registry (http://modulereg.vertx.io/), from which you can get a variety of open source modules to your applications. The web server module is one of them, and we will install some more later in the book.

In addition to public modules, it is also possible and highly encouraged to package your own applications and libraries as modules. You will learn how to do this in Chapter 5, Polyglot Development and Modules.

First create a folder for the application we will be building for the duration of this book. You can just call it mindmap, and put it within your Home directory:

mkdir mindmap
cd mindmap

In this folder, create a file named app.js. This will be the deployment verticle of our application. We will use it to deploy all the other verticles and modules that our application needs. As far as the Vert.x itself is concerned, there is nothing special about a deployment verticle; it is just a code organization practice.

We are going to deploy the mod-web-server module. The latest version of the module at the time of writing is 2.0.0-final, which we will be using here. Alternatively, you can look for the latest version in the Vert.x module registry.

Add the following code to app.js:

var container = require("vertx/container");
container.deployModule("io.vertx~mod-web-server~2.0.0-final", {
  port: 8080,
  host: "localhost"

Let's go through the contents of this file:

  • On the first line, we have used the require function again; it loads into the Vert.x container. It represents the runtime in which the current verticle is running, and can be used to deploy and undeploy other verticles and modules.

  • Next, we called the deployModule function of the container to deploy the web server module. We gave two arguments to the function:

    • The fully qualified name and version of the module to deploy

    • A module-specific configuration object. Within the configuration object, we passed two entries to the module: the host name and port to which to bind the server

Now you can run this code as a verticle:

vertx run app.js

The first time a new module is deployed, Vert.x will automatically download and install it from the public module registry. You will see a subfolder named mods appearing in the project folder, and within it the contents of the installed modules. (In this case, the web server module.)

If you now point your web browser at http://localhost:8080/, you will see a 404 Resource not found message. This means that the web server is running, but there is nothing to serve. Let's fix that.

Create a subfolder named web in the project folder. By default, this is where the web server module looks for static files to serve the browsers (this folder is configurable through the web server's module configuration object).

mkdir web

In this folder, add a simple HTML document in a file named index.html, with the following contents:

<!DOCTYPE html>
<html lang="en">
  <meta charset="utf-8">

Now, as you point your browser at http://localhost:8080/, you will see the Hello! message. You are running a web server in Vert.x!



In this chapter, you have installed Vert.x and taken the very first steps towards building a real-time web application by configuring and running a web server.

You have already covered a lot of ground:

  • Obtaining and installing Vert.x

  • Launching Vert.x instances and running verticles from the command line

  • Embedding a Vert.x instance to an existing application

  • Installing and deploying the Vert.x modules

  • Some key concepts, such as Vert.x instances, verticles, and modules

  • Accessing the Vert.x core API from JavaScript

  • Running a web server

  • In the next chapter, we'll build on our simple web server by adding the very first actual features to our mind map application.

About the Author

  • Tero Parviainen

    Tero Parviainen has been building software professionally for about 12 years, mostly for the web and most of it with Java, Ruby, JavaScript, and Clojure. From large enterprise back-office systems to consumer mobile applications, he has worked in a variety of different environments. He currently works as an independent software maker, focusing mainly on software development contracting and training for several customers. He can be found on Twitter and GitHub as @teropa.

    Browse publications by this author
Book Title
Access this book, plus 7,500 other titles for FREE
Start FREE trial