Chain of Responsibility

The chain of responsibility design pattern is known as a behavioral pattern consisting of client objects and a series of handler objects. It provides more than one object the opportunity to handle a request by linking receivers together (see left UML diagram). Instead of having one monolithic class, as I have or coupling your code to each and every concrete class, with the chain of responsibility pattern, you can avoid both.

Refactoring Rotation Controller

On the right is the UML diagram for handling user inputs in my game. The ControlListener implements the Java AWT Event KeyListener. The ControlListener listens for various keyboard actions (UP_ARROW – rotate clockwise, DOWN_ARROW – drop, LEFT_ARROW – move left, RIGHT_ARROW – move right, Q – rotate counter-clockwise, and W – rotate clockwise). When user presses UP_ARROW, Q, or W, it will create an instance of RotateController class to handle the respective rotation action. On the original UML diagram, you can see the long list of private methods I’ve implemented to handle the rotation action for various tetris shapes.

On the left is the refactored UML diagram with the rotation logic implemented using the chain of responsibility design pattern. Gone are the many private methods created to handle every possible shapes. For each shape, we now have a respective handler class responsible for rotating the shape. The chain of these rotation handler will check if can handle the rotation request by inspecting the shape associated with the request.

public Coordinate[] executeRequest(RotateRequest request) {
  final Coordinate[] coordinate;
  final IShape shape = request.getShape();
  final Rotate rotate = request.getRotate();

  if( shape.getShape() == this.getShape()) {
    coordinate = getTargetCoordinates(shape, rotate);
  } else {
    if(this.nextHandler == null) {
      throw new HandlerNotFoundException("No handler defined for " + shape.getShape());
    } else {
      coordinate = this.nextHandler.executeRequest(request);
    }
  }

  return coordinate;
}

If it cannot handle the request, it will pass the request to the next handler. If it reaches the end of the chain and no handler is found, a runtime exception will be thrown. Feel free to browse the final code base on GitHub.

WSDL to Java
Recently, I published one of my old SharePoint API to GitHub. Originally, I had written the build script using Ant for this project. One of the task I had was to take the SharePoint List WSDL and generate the corresponding java soap client classes. This is fairly trivial task in Ant – in fact, axis already provides an ant task. Sure, I could google for Gradle plug-in for WSDL to Java but I wanted to use this opportunity to learn to write my own plug-in. I’ve also been looking to write more Groovy code.

Creating a Custom Gradle Task
All custom Gradle tasks resides under buildSrc at the root of your project. If you are familiar with Gradle multiproject then you will notice that buildSrc is structured like a subproject. In fact, it is a subproject. Since I will be writing my custom task using Groovy, my source file will reside under src/main/groovy. If you wanted to write your custom task in Java, you would create it under src/main/java.

Since my custom task is merely a wrapper for Axis2 class org.apache.axis2.wsdl.WSDL2Java, the build.gradle file will contain the Axis2 dependencies. Note, if your custom task does not require any dependencies besides core java, then you do not need to define the build.gradle file. Here’s my build.gradle file:

repositories {
  mavenCentral()
}

dependencies {
  compile 'org.apache.axis2:axis2:1.6.2'
  compile 'org.apache.axis2:axis2-xmlbeans:1.6.2'
  compile 'org.apache.xmlbeans:xmlbeans:2.6.0'
}

Once the build.gradle has been defined, I create my custom task in Groovy – WSDL2Java.groovy. The below Groovy class is a simple implementation. As you can see, there are no validation checks. It assumes all properties will be set.

import org.gradle.api.DefaultTask
import org.gradle.api.tasks.TaskAction
// since this groovy class has the same name as the axis2 class, alias axis2 class to CodeGen
import org.apache.axis2.wsdl.WSDL2Java as CodeGen

class WSDL2Java extends DefaultTask {
  // source location of the WSDL file
  String wsdlfilename
  // specify the binding type - xmlbeans, adb, or jibx
  String databindingName
  // target location where java classes should be created under
  String targetSourceFolderLocation
  // base package name
  String packageName

  @TaskAction
  def generateJava() {
    String[] args =
      [
        "-o", targetSourceFolderLocation,
        "-p", packageName,
        "-d", databindingName,
        "-or",
        "-uri", wsdlfilename
      ]
    CodeGen.main(args)
  }
}

Here’s how this custom task is called within the project. First, I define a task called “genJavaFromWSDL” with type WSDL2Java – the Groovy class name. Within this custom task, I set all properties. Then, I update the dependency of java compile task to this custom task. This will ensure the java soap client is created before build is trigger.

// define the WSDL2Java task
task genJavaFromWSDL(type: WSDL2Java) {
  wsdlfilename= "$buildDir/../src/main/wsdl/Lists.SP2013.wsdl"
  databindingName='xmlbeans'
  targetSourceFolderLocation= "$buildDir/generated/wsdl/main"
  packageName='com.microsoft.sharepoint'
}

// add prior hook before compile
compileJava.dependsOn genJavaFromWSDL

// add generated wsdl java classes to source dir
sourceSets.main.java.srcDir "$buildDir/generated/wsdl/main/src"
sourceSets.main.java.srcDir "$buildDir/generated/wsdl/main/resources"

Finally, I add the generated source and resources to the Groovy sourceSet so that the generated sources are properly compiled. It also allows them to appear under Eclipse.

SharePoint API
Several years ago, I wrote a SharePoint API in Java to interact with its List Soap Service. This soap service had a feature to query the target list using Collaborative Application Markup Language (CAML). Here’s an example of CAML query to filter the task list where the TaskName is “Foo Bar” and the Status is “In Progress”.

<query>
  <where>
    <and>
      <eq>
        <fieldref name="TaskName">
        <value type="Text">Foo Bar</value>
      </fieldref></eq>
      <eq>
        <fieldref name="Status">
        <value type="Text">In Progress</value>
      </fieldref></eq>
    </and>
   </where>
</query>

As part of this SharePoint API, I had written a corresponding set of Java classes – each node represented by a class. For trivial query like above, it would look like the following:

final Expression leftExpression = new Equals(new Field("TaskName", "Foo Bar"));
final Expression rightExpression = new Equals(new Field("Status", "In Progress"));
final Condition condition = new And(leftExpression, rightExpression);
final Where clause = new Where(condition);
final Query query = new Query(clause);

As you can predict, for complicated scenarios, this would quickly become unreadable. By applying the concept of Fluent Interface, we can make it far more readable. For example, the above become the following:

final Where clause =
  new Where(
    and(eq("TaskName", "Foo Bar"),
        eq("Status", "In Progress")));

Applying Fluent Interface
A good Fluent Interface takes a while to build. It should be built with the goal of readability and flow in mind. Return type should be chosen based on what you need to continue fluent action. Here’s the SharePoint API implementation. For the complete implementation, please see GitHub Source.

.
.
.
public static Condition and(Expression left, Expression right) {
  return new And(left, right);
}

public static Condition and(Expression left, Condition right) {
  return new And(left, right);
}

public static Condition and(Condition left, Expression right) {
  return new And(left, right);
}

public static Condition and(Condition left, Condition right) {
  return new And(left, right);
}
.
.
.
public static Expression eq(Field field) {
  return new Equals(field);
}

For complicated scenarios where you want to get all task assigned to John with status in “New” or “In Progress” and task created after Jan 1, 2014, the CAML would like the following.

<query>
  <where>
    <and>
      <eq>
        <fieldref name="AssignedTo">
        <value type="Text">John</value>
      </fieldref></eq>
      <and>
        <or>
          <eq>
            <fieldref name="Status">
            <value type="Text">New</value>
          </fieldref></eq>
          <eq>
            <fieldref name="Status">
            <value type="Text">In Progress</value>
          </fieldref></eq>
        </or>
        <gt>
          <fieldref name="CreateDate">
          <value type="DateTime">2014-01-01T00:00:00Z</value>
        </fieldref></gt>
    </and>
   </and></where>
</query>

Here’s the same in Fluent Interface

final Where clause =
  new Where(
    and(eq("AssignedTo", "John"),
    and(
      or(eq("Status", "New"),
         eq("Status", "In Progress")),
      gt("CreateDate", "2014-01-01T00:00:00Z"))));

Application Monitoring

There are several things to consider when monitoring an application. This is not meant as an exhaustive list but here are few items:

• application state
• resource utilization
• proactively report application errors
• module/component status
• external dependency status (databases, services, etc.)

The monitor should be proactive and not reactive. It should provide early enough warning before something goes wrong. This includes monitoring dependencies and the application itself. There are tools that monitor logs and report when it detects various errors in the log file. Although this is better than nothing, it’s too reactive. If you’re lucky enough to have nagios in-house, this is better. However, in most cases, they are configured only for Production and, if lucky, QA. However, for other environments, it may be an overkill to use nagios.

Health Monitoring

The purpose of my health monitor tool is to provide a simple framework to quickly setup and actively check the overall health of any application.

Health monitoring tool is built on the following open source frameworks:

• quartz-scheduler – used to schedule recurring checks to verify your site, components/modules, and dependencies
• apache httpcomponents – used to retrieve resources (JSON/HTML) from HTTP/HTTPS servers
• grizzly NIO framework – used as embedded web container to host status page (see above screenshot)
• jackson – used to parse JSON resources and configuration
• freemarker – used for web/email template
• javamail – used to send failure notification

It can proactively check your application and its dependencies with predefined service checks:

• com.jstrgames.monitor.svc.impl.HttpService – make non-SSL web call
• com.jstrgames.monitor.svc.impl.HttpsService – make SSL web call
• com.jstrgames.monitor.svc.impl.SimpleJmxService – make simple remote JMX calls
• com.jstrgames.monitor.svc.impl.SocketService – make a client socket call

It can then verify these services with predefined rules:

• com.jstrgames.monitor.rule.HttpResponseCode – check if expected status code returned
• com.jstrgames.monitor.rule.HttpResponseBody – check if body contains expected values
• com.jstrgames.monitor.rule.JsonResponse – check if specified JSON key has expected value
• com.jstrgames.monitor.rule.SimpleJmxResult – check if specified JMX attribute has expected value

All can be configured on a simple JSON format configuration file.

Example: Checking HTTPS site

The use case is to verify that the text “Google Search” and “I’m Feeling Lucky” appears on the google.com page every 5 minutes:

[{"servicename": "HTTPS Example (SSL)",
  "classname": "com.jstrgames.monitor.svc.impl.HttpsService",
  "schedule": "0 0/5 * * * ?",
  "hostname": "www.google.com",
  "port": 443,
  "uri": "/",
  "rules": [{
    "classname": "com.jstrgames.monitor.rule.HttpResponseCode",
    "condition": "equals",
    "expected": 200
  },{
    "classname": "com.jstrgames.monitor.rule.HttpResponseBody",
    "condition": "contains",
    "expected": "Google Search"
  },{
    "classname": "com.jstrgames.monitor.rule.HttpResponseBody",
    "condition": "contains",
    "expected": "I'm Feeling Lucky"
  }]
}]

Here, class com.jstrgames.monitor.svc.impl.HttpsService is used check www.google.com at port 443. Once the resource has been retrieved, 3 rules are executed:

• verify http response code is 200
• verify http response body contains the phrase “Google Search”
• verify http response body contains the phrase “I’m Feeling Lucky”

If any of the above checks fails, service is considered to be in “FAIL” status. If it fails to connect to said service, it is in “ERROR” status. It will also send out a notification and user will see a similar content in their inbox, granted, not as pretty.

For more details, please go to my github repository. I will be updating its wiki page soon.

Why Groovy?

Consider the use case of executing a system command and redirecting the output to be processed by your program. With Perl, this is a trivial task: just use a backquote to perform your system command. Perl will assign the result of your standard out to the left-hand variable.

$output = `ls -l`;
print $output, "\n";

In Groovy, it’s just as easy.

def process = "ls -l".execute()
println "${process.text}"

Now, imagine having to perform this in Java:

try {
  StringBuffer stdout = new StringBuffer();
  Process p = Runtime.getRuntime().exec( "ls -l" );

  BufferedReader in = new BufferedReader(new InputStreamReader(p.getInputStream()) );
  while ((line = in.readLine()) != null) {
    stdout.append(line);
  }
  in.close();
}
catch (Exception e) {
  // ...
}

Did I get your attention? I hope so. Let’s consider list. I think Groovy is better at list than Perl. Take the use case of sorting a list of numbers. In Perl, it would look akin to this.

@list = (1, 23, 4, 6, 12, 5, 36);
@sortedlist = sort {$a <=> $b} @list;
print "@sortedlist ";

In Groovy, it’s even shorter

def list = [1, 23, 4, 6, 12, 5, 26]
println list.sort()

Lists are easier to work with in Groovy. If you want to print a sub-range, it’s “println list[1..3]”. If you want the last 3 items in the array in reverse order, it’s “println list[-3..-1]”. Negative index tell Groovy to retrieve the item from tail and work its way back.

If you’re a Java developer, how can you not love Groovy.

Like Java, Love Groovy

Groovy is built on Java. It brings dynamic typing and the benefits of dynamic language to the world of Java but still provides static typing when needed. Because it’s built on Java, Groovy has access to all the Java API available in your classpath. By default, the following classes are exposed to Groovy:

• java.io.*
• java.lang.*
• java.math.BigDecimal
• java.math.BigInteger
• java.net.*
• java.util.*

If you need a class not imported by default, if it’s in the classpath, Groovy can use them. You can import them in or use the fully qualifying classname:

println java.sql.Date.valueOf("2013-12-31").getTime()

As stated earlier, all of Java libraries are at your disposal. Short of sounding like an infomercial, that’s not all! You can compile Groovy program and it will become accessible from Java. Consider having to write a simple POJO. Sure, you can use most IDEs to generate your getters and setters, but with Groovy, this can be simplified.

package com.jstrgames.groovy.example

class Book {
  String title
  String author

  String toString() { "${title} ${author}" }
}

Once compiled by Groovy compiler, com.jstrgames.groovy.example.Book can be accessed from any Java program. It will also automatically create all your getters and setters for each property: getTitle(), setTitle(), getAuthor(), and setAuthor(). If you want to use this class in Groovy, you can directly access the properties:

def book = new Book( title: "Groovy by Action", author: "Dierk Koenig" )
println book

def myBook = new Book()
myBook.title = "Tech Genre"
myBook.author = "John Ra"
print myBook

You can clearly see an increased productivity building modules/application/APIs with Groovy. If you want to learn more, I highly recommend reading Groovy by Action by Dierk Koenig.

It didn’t take long before I managed to stumble across a pure Java API from Oakland Software. Oakland Software team managed to reverse engineer the NTLMv2 security protocol. With this API, I could plug-in an Oakland’s HttpClient agent into Apache Axis1 to seamlessly communicate with SharePoint. It worked perfectly. However, it was too risky to build a system that relied on a small unknown company that licensed this technology. Instead, I mitigate this risk by re-architecting the whole system on .NET platform. As anyone that has dealt with Microsoft knows, MS products always work better with other MS products. Since then, a lot has changed. Oakland has open sourced their API and Microsoft has made a patent pledge not to purse open-source developers. If you wanted to, you can still use Oakland API and Axis1 to communicate over NTLMv2. That’s one alternative. The other alternative, which I think is more forward thinking, is to use Axis2 with HttpComponents, HttpClient v3 replacement.

The Good, The Bad, and the Ugly
You’re probably thinking, “thanks for the history lesson but I really just want to know how to get java to talk to services behind NTLMv2 security.” First, the good news is that Axis2 will be integrated to HttpClient v4, which happens to support NTLMv2. The bad news is that it won’t be available until Axis2 version 1.7 is released. Then comes the ugly news, as of Aug 22, their latest snapshot implementation doesn’t work. From looking at the source code, there’s a bug that causes Axis2 to still load HttpClient v3. This is due to line 376: “sender = new HTTPSenderImpl();”. The base class is hardcoded to use httpclient v3. Below is a simple patch that I’ve written.

// Commenting out original code as it loads httpclient v3. This should really
// be refactored in an abstract method. For now, patching with simpler if condition
// sender = new HTTPSenderImpl();
if(this instanceof org.apache.axis2.transport.http.impl.httpclient4.HTTPClient4TransportSender) {
  sender = new org.apache.axis2.transport.http.impl.httpclient4.HTTPSenderImpl();
} else {
  sender = new org.apache.axis2.transport.http.impl.httpclient3.HTTPSenderImpl();
}

Ideally, this class should have an abstract method that will be over written by extended classes in httpclient3 package or httpclient4 package. For now, I’ve patched it to perform a simple instance check to identify the extended class and call the correct corresponding HTTPSenderImpl class. The following will provide step by step instructions on how to run Axis2 v1.7 + HttpComponent v4.1 to communicate to a .NET SOAP service sitting behind NTLMv2

1. Setting up IIS with NTLMv4
First, We need to setup test environment with NTLMv2 enabled. If you already have access to IIS with NTLMv2 enabled, you can skip to the next section. Otherwise, here are instructions on how to setup IIS 7 on Windows 7 Professional, Enterprise, or Ultimate: Go to your Control Panel and click Programs -> “Turn Windows features on or off”.

Expand “Internet Information Services” and check the following features:

• IIS Management Console
• IIS Management Service
• .NET Extensibility
• ASP.NET
• ISAPI Extensions
• ISAPI Filters
• Request Filtering
• Windows Authentication

Once installed, go to “Control Panel” -> “System and Security” -> “Administrative Tools” and open “Internet Information Service (IIS) Manager”. You can either perform the following steps at the server level or at individual site level. In either place, if you click on your server name or “Default Web Site”, you’ll have several options appear on right. Double-click on “Authentication” and disable all but Windows Authentication option.

This will enable NTLMv2 and protect you site. All requests to this site will challenge user for valid Windows credentials.

2. Deploy Test Application
Download my simple .NET TimeService web application. Unzip and place the content anywhere on your computer. From IIS Manager, create a virtual application under Default Web Site and give the alias “TimeService”. The “Physical Path” should point to the location of the recently downloaded and unzipped .NET web application. If you open up App_Code\TimeService.cs file, you’ll see the following.

[WebMethod]
public string Now(string name)
{
  return name + ", current time is " + DateTime.Now.ToShortTimeString();
}

This is a simple .NET web service application that returns the current time for the specified parameter. If all works out, when you visit http://localhost/TimeService/TimeService.asmx?WSDL, assuming your site is running under port 80, you’ll be prompted to login with your windows credential. Once logged in, you’ll see the WSDL for this web service.

3. Generating Axis2 Client
If you’re familiar with Axis, you should know that it comes with a tool to generate Java client based on specified WSDL. If you’re not, now you know. Since the target WSDL is protected behind NTLMv2, the simplest way is to visit the site using your credentials and then save the WSDL to your file system. To generate the java client stubs, please visit Axis2 website for their instructions. It’s pretty thorough. You can also download my Eclipse Projects which has both the above Axis2 v1.7 patch and generated java stubs based on the TimeService WSDL.

4. Running Java Client
In Axis2NTLMClient project downloaded from prior step, locate the Client.java class which contains the main method. Prior to running this class, you must add a VM argument (“-Daxis2.xml=conf/axis2.xml”) under Run Configuration in Eclipse (see image left). This VM argument informs Axis2 to use the axis2.xml located in conf folder instead of the default that comes with axis2-kernel.jar. The version in config/axis.xml has been modified to inform Axis2 to use HTTPClient v4 Transporter (line 232). When you run this class, you will be prompted with a login screen. This is a custom login dialog that I’ve written as I’m not a fan of saving username and password in properties file or in code. This simple login dialog will capture your username, password, and domain. If all goes well, you should see the following message on your console screen: “John, current time is <<your current time>>”.

Analysis
When Client class is constructed, it will call the setupAuthentication() method. This method will construct the authenticator and will set the username, password, and domain entered by user.

private void setupAuthentication() {
  this.auth = new HttpTransportPropertiesImpl.Authenticator();
  try {
    showLoginDialog();
  } catch (java.awt.HeadlessException e) {
    log.fine("User does not have a desktop session! using console");
    showLoginConsole();
  }

  auth.setRealm(AuthScope.ANY_REALM);
  auth.setHost(this.host);// must MATCH target Host
  auth.setPort(this.port);// must MATCH target Port
}

The HeadlessException catch logic is put in place in the event user does not have a windows/xsession available. It will use the default console to capture username, password, and domain. By default, I set the Realm to ANY_REALM. I haven’t played around enough with Realm to give you additional insight. As for host and port, it MUST match the target URL. For example, if you decided to connect to site via IP address (e.g. 127.0.0.1) instead of “localhost”, you must setHost() with IP address. For this reason, my Client class is constructed with host and port to ensure consistency.

public String getResponse(String param) {
  try {
    TimeServiceStub service = new TimeServiceStub(getServiceEndPoint());

    Options options = service._getServiceClient().getOptions();
    options.setProperty(HTTPConstants.AUTHENTICATE, this.auth);
    options.setProperty(HTTPConstants.CHUNKED, Boolean.FALSE);

    Now req = new Now();
    req.setName(param);
    NowResponse resp = service.now(req);

    return resp.getNowResult();

  } catch (AxisFault e) {
    log.severe(e.getMessage());
  } catch (RemoteException e) {
    log.severe(e.getMessage());
  }
  return new String();
}

Once the authenticator has been constructed, Axis2 generated java class TimeServiceStub is used to connect to the .NET SOAP service. The helper method “getServiceEndPoint()” will generate and return the location of the webservice end point. It then set the options for AUTHENTICATE to use the constructed authenticator and disables CHUNKED on the transport encoding. If you do not disable the CHUNKED transport encoding on .NET services, it will break. Request class Now is used to set the parameter and the result of the SOAP service is returned through NowResponse class.

As HttpComponent v4 has a pure Java implementation of NTLMv2, you can run this client from any OS. Here’s a screenshot from my Ubuntu Server.