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.
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.
Vert.x is written in Java, and needs the Java JDK 7 to run the program. Older versions of Java are not supported.
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'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.
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.
Note
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.
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.
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 yourHome
directory:$ cd ~/dev
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
Open your
.bash_profile
file in a text editor.$ pico ~/.bash_profile
Add the path to the
bin
subdirectory of the Vert.x distribution to thePATH
environment variable, by adding the following line:export PATH=$PATH:$HOME/dev/vert.x-x.x.x.final/bin
Save and close the editor.
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.
Tip
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:
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â¦.
Select the folder into which you want to install Vert.x (for example, one named
dev
within yourHome
directory). After selecting the directory, click on Extract.Open Control Panel. Navigate to System and Security | System | Advanced system settings | Environment Variables.
In the System variables listbox, find the variable Path. Select it and click on Edit.
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.;C:\Users\YourUsername\dev\vert.x-x.x.x.final\bin
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.
You can now proceed to the Running Vert.x section to verify your installation.
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.
Note
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:
vertx
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.
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.
Note
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
commandIn that instance, you deployed the code as a verticle
Note
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.
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.
Note
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:
cd 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"> <head> <meta charset="utf-8"> </head> <body> Hello! </body> </html>
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.