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

Windows

  • 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: http://127.0.0.1:9000/

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: https://github.com/cbucher/console/wiki/Downloads

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.

Cygwin

Download Cygwin setup here: https://cygwin.com/install.html

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 cygwin.mirrors.hoobly.com.
  • 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 rawgit.com/transcode-open/apt-cyg/master/apt-cyg > 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

Gutted

This weekend I finally decided to do something about my aging website. Initially, my thoughts were to update the design, maybe tweak some of the content. Alas, there comes a point where a complete rewrite is demanded. My site, built in 2010, was one of those version 1.0’s that could not be saved by a new coat of paint, refactoring, or content updates.

My blog had gone stale. Even the posts from back then were not worth hauling over. My last post was in November of 2011, when I thought building a web application in C++ might be a good idea.

As our past shapes us, I thought it only appropriate that my last blogs shall shape these first few posts. A tribute of sorts–where I was at the start of the decade, contrasted to where I am now and more importantly where I and my relationship with technology are headed. Below are a few highlights from my favorite age-old posts.

August, 2010 – Zend ACL and How To Create a Simple Login

Zend Framework 1. What sweet memories. My first introduction to legitimate MVC frameworks and architectural design patterns. Zend framework and my work around it matured me more as a programmer than any other moment in my history as a developer. It was at the same time that I fell in love with domain driven design, learning from the philosophies of Eric Evans and Martin Fowler.

Zend Framework had a steep learning curve at the time. And I wanted to help developers jump right in to securing their ZF web applications, using the ACL library. I also talked about how to build a decoupled namespace, where the core of the logic should live, while utilizing only the pieces of ZF that were necessary. Keep in mind that PHP didn’t actually have namespaces at the time. So classes tended to have very long names.

ZF was difficult because it was one of the most flexible frameworks of its time. The ZF team didn’t want to be overly descriptive on where your application logic should live. Compared to CakePHP’s version 1, or even worse, CodeIgniter.

My first blog on this new site will share a similar topic. But instead of describing how to build a login flow for the latest Zend Framework version (which is 3 by the way), I want to walk through a microservices project, where the first part is building an OAuth 2.0 service.

Modern web applications are frontend heavy, built entirely out of JavaScript. The current craze being the React framework. Though who knows what it will be in a few months. The JavaScript application connects to the backend through API’s. To secure these API’s, a common security specification is used, which I am sure you have heard of, called OAuth 2.0.

When a user logs in, she is authorizing the client (a browser in this case) to communicate with the backend API’s on her behalf, utilizing a token that is stored in a cookie.

Though the OAuth flow seems similar to the old fashioned login flow, where a session id is created instead of a token and stored in the browser, also commonly using a cookie, there are a few distinct differences.

With OAuth backend API’s, once the request hits the API, the API can assume the request is authorized. The backend doesn’t need to worry about session management. This is because the OAuth service catches each request and will only pass it along if the OAuth token is valid.

Removing the whole authentication/authorization piece from the backend API simplifies the application code, allowing the service to achieve an ideal state of serving a single, clear purpose. In the microservice world, this singular purpose allows you to build manageable, flexible components. This leads to faster iterations, less daunting code bases, and the option to vary your development language case by case.

To be continued…