Archive for June 2016

Getting Started with the Java Play Framework and Building a Test App

This is Step B, the final setup stage in our Building a Microservices Project series before we actually start building our application.

By the end of this post we will have a working Java development environment, installed Activator, will have created a test application, and learned how to compile and run the application locally.

Activator is a build tool that makes it much easier to pull in required libraries, run a Java web server,  and create skeleton projects. A skeleton project gives us the bones needed to build new applications more quickly.

Before we get started, please make sure you already have the latest Java runtime environment installed.

Please also install the IntelliJ IDE (Integrated Development Environment):

The free community version of IntelliJ is sufficient. If you prefer to use another IDE, go for it! Unfortunately, you’ll have to figure out how to configure your project in that IDE, though I am sure there are plenty of helpful tutorials out there. I will be mentioning configuration steps specific to IntelliJ.

Newb Tip: If this is your first time installing IntelliJ, there is a first-time setup for plugins, etc. You can simply leave all the defaults and click Next a few times.

Next, install the latest Java JDK:

Make a note of the JDK install location. You can customize this however you wish, just remember it.

Windows users extra step

If you do not use Windows, you can skip this short section.

In order for java and javac to work properly in our Cygwin terminal, we need to add the JDK bin to our system PATH.

  • Go to Control Panel -> System -> Advanced system settings
  • Select the Advanced tab
  • Click Environment Variables
  • Underneath System variables, select Path and click Edit
  • Click Browse
  • Navigate to where you installed the JDK, and select the bin directory within it
  • Click OK to exit all the windows
  • Open up your terminal and run:
    • $ javac -help
  • Make sure you get a lengthy usage description and not an error

Setup Activator

When you visit the link below, look for the section at the top, “Alternative downloads”, and click Offline distribution.

After the download completes, extract its contents. Move activator into your home directory, and add it to your PATH.

Mac OS X / Linux

  • Edit ~/.profile
  • Add or change the PATH line to include the activator location:
export PATH=/path/to/activator-x.x.x:$PATH
  • Additionally, ensure activator is executable:
    • $ chmod u+x /path/to/activator-x.x.x/activator


  • Move the extracted activator directory into your Cygwin home directory. For me this looked like: D:\cygwin64\home\Elliot\activator-dist-1.3.10
  • Add the activator bin to your system PATH:
    • Control Panel -> System -> Advanced system settings
    • Advanced tab, Environment variables
    • Underneath System variables, click Path and then click Edit
    • Click Browse, and locate the new activator home as described above, but be sure to select the bin directory. For me, this was D:\cygwin64\home\Elliot\activator-dist-1.3.10\bin
    • Click OK to close all windows

Now, ensure that activator is ready. Open a new terminal, and type:

$ activator -h

If you don’t see any errors, you are good to proceed.

Create your first Play app

From the terminal, cd to your home directory. Feel free to create a subdirectory within here, called “code” or “projects”.

Newb Tip:

  • $ mkdir ~/projects
  • $ cd ~/projects

Now let’s create a new Play applcation, called little-app:

  • $ activator new little-app play-java

This tells activator to create a new project using the Play framework and Java, called little-app. It creates a new directory for you, little-app, which you can now cd to.

  • $ cd little-app

Now let’s launch the web service and make sure we have our first demo page:

  • $ activator run

Upon first run, activator will download many dependencies. This gets quicker the next time you call run for the project.

At some point, you will see the downloading come to a conclusion, and some text saying “Running the application … Listening for HTTP on … :9000”. Let’s see if this is really true. Open your browser, and go to:

There may be a few second delay before you see the demo Play page. Your sources were compiling.

So, if you do see your first demo page, then excellent! We have a working development environment and are ready to begin building the first microservice Java Play application.

To stop the Play application from running, simply type Ctrl+D (Ctrl+C also works).

Getting Started With Cygwin – Step A for developers on Windows

Before we jump into programming our first Java Play service, we need a development environment.

This step is for Windows users only. If you are using Mac OS X or Linux, you may continue on to the next entry.

Before we start, an explanation

For several years now, when I have needed to develop web services using Windows, I always use Cygwin. Why? Because I cannot stand the Windows command prompt interface. Mainly because it is not Unix friendly. I am looking forward to this changing in a future Windows update that is bringing Linux command line applications to the Command Prompt. However, that is most likely far off, and until then, I will continue to use Cygwin.

Along with Cygwin, I use a tabular terminal tool called Console Z. Together, this gives me a command line environment very much like the Unix terminal you get with Mac OS X and the various Linux flavors.

Environment consistency is critical to human error prevention and efficient web service development and maintenance.

I usually switch between many OS’s on a daily basis. Consistency makes this easier. And Linux (specifically bash) is the tool that bridges each platform. Whether I am ssh’d (remotely connected) to one of my cloud servers, or running commands locally, the commands look the same. Trust me, this setup will bring you much joy.

Let’s get started

Console Z

First, download Console:

Select the correct version for you, most likely amd64/x64.

What you are downloading is a zip file. Extract this, and then move the extracted directory into the root of one of your drives. If you only use C: for your main programs, that works.

When you extract the zip file, you will be left with a directory with the version number and everything. Let’s rename this simply to ConsoleZ. Therefore, once you have moved it to C: (or another drive), you’ll have a path that looks like this:

  • C:\ConsoleZ\Console.exe

To start Console, double click Console.exe. Create a shortcut or pin to Start if you like. You’ll be using this frequently.

Make a note of this folder, as we’ll come back to it soon. For now, please close out of Console if you have it open.


Download Cygwin setup here:

Make sure you download the correct version, example setup-x86_64.exe for Windows 64-bit.

After you download the setup application, run it and follow these steps:

  • Click Next
  • Install from Internet
  • Root Directory: leave as default or move to another drive if you prefer
  • Package Directory: default is fine
  • Internet Connection: Direct Connection, unless you are on some funky network
  • Randomly select a download site, for whatever reason I usually select
  • Select Packages–the most important step. Use Search at the top to find each of these, using the keyword I place within the slashes. There are sub-categories for each, which I designate before the colon.
    • Web – lynx: A text-based Web Browser (needed for apt-cyg)
    • /ssh/ – Devel: libssh2: SSH2 protocal library
    • /ssh/ – Net: libssh-common
    • /ssh/ – Net: libssh-devel
    • /ssh/ – Net: libssh2-devel
    • /ssh/ – Net: openssh
    • /wget/ – Web: wget
    • /gcc/ – Libs: libgcc1
    • /gcc/ – Devel:
      • cygwin32-gcc-core
      • cygwin32-gcc-g++
      • cygwin32-gcc-obj
      • gcc-core
      • gcc-obj
      • gcc-g++
      • gcc-tools-epoch1-autoconf
      • gcc-tools-epoch1-automake
      • gcc-tools-epoch2-autoconf
      • gcc-tools-epoch2-automake
      • gccmakedep
      • mingw64-x86_64-gcc-core
      • mingw64-x86_64-gcc-g++
      • mingw64-x86_64-gcc-obj
    • /cmake/ – Devel: cmake: Cross-platform makefile generation system
    • /ssl/ – Devel: *0penSSL (download both libraries 64 and 32-bit toolchains)
    • /ssl/ – Libs: libxmlsec1-openssl-devel
    • /ssl/ – Libs: libxmlsec1-openssl1
    • /ssl/ – Net: openssl-devel
    • /subversion/ – Devel: subversion: A version control system
  • Phew! Finally, click Next
  • Make sure the checkbox for Select required packages is checked, then click Next
  • Now go grab a cup of coffee and come back in 15 minutes, since it’ll take some time for all your packages to download
  • When the downloading is complete, simply click Finish. You do not need any shortcuts to Cygwin

I know, I know. That is quite a list of Cygwin packages. But, this should be a good start to getting you everything you need to have a Unix-like experience.

And we’re not done yet. But the rest of the packages will be installed in a different way.

Cygwin phase 2

What is Cygwin you ask? It is an alternative to the Windows command prompt. Many of the commands you can run on the Command Prompt can also be run in Cygwin. Additionally, you can run all the commands we just installed as well as as bash commands (<3 bash).

So, Cygwin is a command line interface (cli). When you run Cygwin, you are presented with a black window and a place to start typing. The place where you start typing is called your command line.

We won’t run Cygwin directly. Instead, we will run it through Console Z. Console Z merely adds the ability to have tabbed Cygwin terminals open. And very often you will run many tabs (just like you probably have many browser tabs open at the same time).

So, let’s finish setting up Console Z now.

Remember where you copied the ConsoleZ directory to (C:\ConsoleZ possibly)? Navigate there. Then download this file and copy it into that directory:

Make sure the file is called console.xml.

Next, edit console.xml, changing each occurrence of “A:\cygwin” with the correct location for you. Make sure to leave the rest of the path as it is, or you’ll run into some errors.

There are 3 places in the file where you’ll find “A:\cygwin.” For example, if your location is “C:\cygwin64”, then the first occurrence will change to: C:\cygwin64\bin\bash.exe.

Save and close the file.

Now, test your console configuration by running ConsoleZ.

The first time you open this up, if everything is setup properly, you’ll see messages at the top telling you that Cygwin has setup your home directory. You will only see these messages the first time you run Cygwin’s bash shell.

Cygwin phase 3

Almost done setting up Cygwin. For the final steps, we are going to install a package manager (similar to debian’s apt-get).

TIP: the keyboard shortcuts for copying and pasting do not work within Cygwin. This is because CTRL+C means something in bash that is not copy. So instead, to copy and paste into the Cygwin command line, do this:

  • Copy: Ctrl + Insert
  • Paste: Shift + Insert
  • To drag and highlight text in Cygwin, you must hold down the Shift key when you click and drag. Then you can copy the highlighted text.

In your console’s command line, run the following two commands. Note: The “$” character denotes a command to run in your new, fancy bash command line interface.

  • $ lynx -source > apt-cyg
  • $ install apt-cyg /bin

There are no messages output when apt-cyg is installed. But you can test by running:

  • $ apt-cyg –version

If you don’t see a message like “command not found”, you’re good to continue.

Now, let’s use apt-cyg to install two more command line applications.

  • $ apt-cyg install vim
  • $ apt-cyg install git

Next, let’s configure vim to work properly on Windows. But first, let me teach you how to use vim. This will be a brief tutorial on vim and editing text files within bash. Note: vim is my personal preference for file editing within bash. There are other applications you can use that are easier to learn. But I do strongly recommend learning the basics of vim. It is a very powerful text editor.

Quick vim tutorial

Why even learn vim? Well, you won’t always have local copies of the file you need to edit. Whether you are ssh’d into a local vagrant machine, local or remote docker container, or any remote virtual machine, vim will come in handy.

If you are already familiar with vim and the basics of the bash shell, you can skip this part and continue to the final section below.

From your command line, make sure you are inside your home directory.

  • $ cd ~

cd means change directory. “~” means your home directory. To see the full path of your home directory, you can type:

  • $ pwd

pwd means (maybe means) present working directory. ~ is a shortcut on Linux machines to your home directory. When you type pwd, it tells you what ~ actually means in your current environment. For me, I get:

  • /home/Elliot

Now, let’s create a test file using vim.

  • $ vim test.txt

This command starts up vim and creates an empty file, called test.txt.

To start adding text to the new file, you first need to press the “i” key. This means you are ready to insert text.

When you are done typing, press the Esc key. That exits insert mode.

To save the file, you type a colon character, “:” followed by a “w”, followed by a “q”:

  • :wq

Then press Enter.

This saves and closes the file, returning you to the command line.

What does this mean? “:” tells vim you are about to issue a command. “q” tells vim you are wanting to quit. “w” tells vim you want to save the changes to the file.

Let’s say you make changes to a file, but then decide not to save it. In this scenario,  you would type:

  • :q!

The “!” tells vim to discard the changes.

If you open a file, and then want to close it without having made any changes to its contents, you can simply type:

  • :q

Take a minute and play with these various vim commands, creating new files and editing existing files like test.txt. Hopefully you grow a bit of a comfort level with using vim. I’ll teach you more advanced vim commands later.

Fixing vim on Windows

For whatever reason, vim is a bit buggy when it comes to the backspace key on Windows. Luckily, there is a very easy fix to this problem.

cd into your home directory.

  • $ cd ~

Use vim to create a file called “.vimrc” (yes, the filename starts with a period):

  • $ vim .vimrc

Press “i” to begin insert mode. Then type one line of content:

set bs=2

Press Esc key to exit insert mode. Then save and close the file by typing the characters :qw then press Enter.

That’s it. From now on, vim should behave properly on Windows.

Final words

You now have a Unix-like terminal on your Windows machine. Reading the rest of the articles in this development series will be much simpler, since all the commands will work the same regardless of what operating system you are using.

In this article, you installed Cygwin, downloaded several command line packages, installed Console Z, and learned a little bit about vim. From now on, if I instruct you to open a terminal window, or ask you to type the following on the command line, I am asking you to open Console and start typing.

Console is the graphical user interface that wraps Cygwin, the command line interface.

The Big Microservices Project with Java Play and React

In order to motivate myself in adding some new blog posts to this site, I have come up with a fun project. That is very relevant, yet tricky for newbs–building out a microservices application.

Additionally, I want to learn a new Java framework, so for the most part we will write each service using Java Play, which is built on top of Netty.

Each post will tackle a specific and targeted need of this application. And hopefully be easy enough to follow for those new to web development and infrastructure operations.

What this series will not do: teach programming. I will not spend too much time explaining basic programming concepts. So make sure you follow a beginner’s tutorial, in Java or any OOP language, before jumping into this set of how-to’s.

However, we will discuss advanced programming concepts–those that directly impact our application design. Powerful concepts like concurrency, non-blocking I/O, RESTful API’s, tracing, message queues, and many more goodies!

Although we will mostly use Java Play, we will use React for the front-end JavaScript piece, and possibly Go for a small proxy service. This is going to be a big project, probably take me a couple months to complete; I imagine the result will change from some of these initial thoughts. This is called Agile Architecture: commit to decisions until the last responsible moment.

What is our application going to do? As of now, I am thinking the best way to teach the importance around concurrent connections, message queues, and microservices is to build out a social media data aggregation service.

Why? It is not necessarily going to be that useful. However, social media API’s provide us lots of data to play with right from the start. Additionally, you’ll find that 3rd party API’s can never be trusted. We need to build services that won’t fail just because Facebook is slow or down.

Let’s build 3 adapters for data aggregation– Facebook, Twitter, and Pinterest. Hopefully we can do something interesting to look at with this.

Below is the initial diagram for our microservice stack. Don’t let this intimidate you– there are quite a few components. However, when you’re done with each post in this series, you should walk away with a solid understanding of each piece and its importance to the big picture.

Oh, the last point I should make is that we will be securing our single-page application with OAuth 2.0. We’re going to build out our own OAuth 2.0 implementation, most likely incorporating it into the gateway component.

Lastly, we should ensure our application is easy to scale, maintain & change, and debug. I’ll make sure to hit on this criteria several times over the course of this project.

Let’s get started!

Infra layout map