Friday, August 31, 2012

Java Unit Testing with JUnit 4.x from Terminal


JUnit


In this tutorial I will guide you through the process of installing and writing a simple java unit test all from the terminal (command line). I'm not going to go through explaining why test driven development is the way to go for most serious programmers out there, but rather explain how tests are created and then performed. Hopefully, when you go through this tutorial you will finally understand the advantages of unit testing yourself if not already so!

This tutorial assumes that you have a basic text-editor installed. In my demonstrations, I will be using the famous Vim text-editor; however, you can use your preferred text-editor let it be NotePad or any other text-editor you find suitable to your needs. Also, it is assumed that you have the Java Compiler and JVM installed.

First, let us download the JUnit library/Jar which we will import later in our code to run tests. To do so visit http://www.junit.org and download the latest Jar directly from there. Alternatively, you can download the entire JUnit project (source files) from GitHub, and then compile them, this ensures that you get the latest updated JUnit by the creator Kent Beck himself. To do so you can fetch the latest project from GitHub using non other than Git. If you are unfamiliar with Git you can ignore the next paragraph and just download the Jar directly from the above website. Otherwise, follow along to fetch and build the latest JUnit project.

From the terminal/command-line execute the following:

$ git clone git://github.com/KentBeck/junit

This will clone a copy of the latest project to your local disk. Once the download is complete, you should cd into the junit/ directory and then ant dist. Executing the last command will start building and compiling the project using the ant tool. When the build is done cd into junit4.x directory to find all the Jar files you will need in your future test driven projects. Again if all this is not clear, you can just download the Jar from http://www.junit.org and use it directly without going through the hassle of building and compiling.

OK! Away from JUnit for a bit. Let's say we want to create a simple class called MyClass.java that does division of two numbers. This class has only one method which is called division. The division method takes two arguments division(double x, double y), and obviously does division as in x / y. The code in MyClass.java is as follows:

// the class to be tested
public class MyClass{
       public double division(double x, double y){
                return x / y;
       }
}

Now let's say we want to test this class. Particularly, unit test the division(double x, double y) method. The test case we want to verify is the division by zero case. We first create a test class called MyClassTest.java. This test class is located in the same disk location where MyClass.java is located (This is not necessary. It can be located anywhere). Note that the test class has the same name as the original class but with Test appended to its name; such as, MyClassTest.java which tests MyClass.java. This is a JUnit convention that must be followed to help JUnit map the classes using reflection. The code in MyClassTest.java is as follows:

import org.junit.*;
import junit.framework.JUnit4TestAdapter;

// the testing class
public class MyClassTest{
 private MyClass runner;

 @Before
 public void setUp(){
  runner = new MyClass();
 }

 @Test
 public void testZeroDivision(){
  Assert.assertEquals(0.0, runner.division(100.0, 0.0), 0.0);
 }

 @After
 public void tearDown(){
  runner = null;
 }

 public static junit.framework.Test suite(){
  return new JUnit4TestAdapter(MyClassTest.class);
 }
}

Firstly, we import org.junit.* that will do the parsing of JUnit annotations, and also import junit.framework.JUnit4TestAdapter which will invoke the actual testing. Note that these imports are specific to JUnit 4.x and not JUnit 3.x or any other earlier versions to that matter. Because we want to test the MyClass object we declare a private member of that type and is called runner. 

Secondly, we introduce JUnit annotations; such as, @Test, @Before and @After. @Test is used before the test method to tell JUnit that this is a testing function or testing fixture in JUnit terms. @Before and  @After are used with JUnit specific methods setUp() and tearDown() respectively. These annotations are very important when you have multiple test methods that you want to test altogether. @Before tells setUp() to initialise the MyClass object runner before every test method and @After tells tearDown() to nullify that same object once the testing method is done. So if we have another testing method, @Before and @After will make sure to initialise and cleanup any objects you are testing before going through the following test case.

Thirdly, in the testing fixture/method testZeroDivision() we use another JUnit specific method which is Assert.assertEquals(expected, actual, delta). The assert mechanism is the most famous mechanism of verification in the world of JUnit testing. There are many assert methods; such as, assertEquals(), assertTrue(), assertNull() and so on, and all of them are overloaded for most of the basic Java datatypes. OK! back to assertEquals(expected, actual, delta). What we want is to have zero as a result whenever we divide by zero. Theoretically, any division by zero yields infinity, but computers are finite and have no concept of infinity; thus, we have to account for this case by forcing the division by zero to yield zero. So 100 / 0 = 0 . As the expected argument in our division method we insert 0.0 because this is the result we want. For the actual argument we insert the method we want to test and that is runner.division(double x, double y). Delta is the error or uncertainty threshold that assertEquals would accept. Because we are comparing two floating points this delta can be convenient sometimes; however, in our test case we want delta to be 0.0, that is no difference between the expected result and the actual result.

Finally, note that we have a public static junit.framework.Test suite() method. This static method will help in executing this test class whenever we use the java command in the terminal/command-line. This method returns an instance of the JUnit4TestAdapter which takes as argument to its constructor the name of the test class we want to run and that is MyClassTest.class.

Now, to actually run this test we have to first compile both classes using the javac command and then execute the test class using the java command. Put in mind that we have to include the JUnit Jar and the user classes in the classpath during our compilation and execution. We assume that both files are under the same directory in the file system. cd into that directory and execute the following commands from any unix-like terminal to run the test:


$ javac MyClass.java
$ javac -cp ../JARs/JUnit/JUnit4.11/junit-4.11.jar:./ MyClassTest.java
$ java -cp ../JARs/JUnit/JUnit4.11/junit-4.11.jar:./ org.junit.runner.JUnitCore MyClassTest
$ JUnit version 4.11-SNAPSHOT
.E.
Time: 0.009
There was 1 failure:
1) testZeroDivision(MyClassTest)
java.lang.AssertionError: expected:<0.0> but was:<Infinity>
 at org.junit.Assert.fail(Assert.java:93)
 at org.junit.Assert.failNotEquals(Assert.java:828)
 at org.junit.Assert.assertEquals(Assert.java:560)
 at org.junit.Assert.assertEquals(Assert.java:664)
 at MyClassTest.testZeroDivision(MyClassTest.java:19)
 at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
 at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
 at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
 at java.lang.reflect.Method.invoke(Method.java:597)
 at org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:46)
 at org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:15)
 at org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:43)
 at org.junit.internal.runners.statements.InvokeMethod.evaluate(InvokeMethod.java:20)
 at org.junit.internal.runners.statements.RunBefores.evaluate(RunBefores.java:28)
 at org.junit.internal.runners.statements.RunAfters.evaluate(RunAfters.java:30)
 at org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:270)
 at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:70)
 at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:49)
 at org.junit.runners.ParentRunner$3.run(ParentRunner.java:238)
 at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:62)
 at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:236)
 at org.junit.runners.ParentRunner.access$000(ParentRunner.java:52)
 at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:229)
 at org.junit.runners.ParentRunner.run(ParentRunner.java:307)
 at junit.framework.JUnit4TestAdapter.run(JUnit4TestAdapter.java:39)
 at org.junit.internal.runners.JUnit38ClassRunner.run(JUnit38ClassRunner.java:83)
 at org.junit.runners.Suite.runChild(Suite.java:129)
 at org.junit.runners.Suite.runChild(Suite.java:25)
 at org.junit.runners.ParentRunner$3.run(ParentRunner.java:238)
 at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:62)
 at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:236)
 at org.junit.runners.ParentRunner.access$000(ParentRunner.java:52)
 at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:229)
 at org.junit.runners.ParentRunner.run(ParentRunner.java:307)
 at org.junit.runner.JUnitCore.run(JUnitCore.java:152)
 at org.junit.runner.JUnitCore.run(JUnitCore.java:131)
 at org.junit.runner.JUnitCore.run(JUnitCore.java:112)
 at org.junit.runner.JUnitCore.runMain(JUnitCore.java:93)
 at org.junit.runner.JUnitCore.runMainAndExit(JUnitCore.java:48)
 at org.junit.runner.JUnitCore.main(JUnitCore.java:39)

FAILURES!!!
Tests run: 1,  Failures: 1


In the first line we simply compile the class to be tested. MyClass.java has no dependencies; thus, there is no need to include anything in the classpath during compilation. The second line we compile MyClassTest.java. As you remember we have JUnit imports in this test class and have to include the JUnit jar in the class path accordingly. We also declared a private member of type MyClass, so we have to account for that by also including MyClass.class in the classpath. We do this by using the -cp argument to specify the jars and classes (separated by colons) that we want to include during the compilation. Because MyClass.class exists in the current directory we use ./ to instruct the compiler to look for this class in the current folder. In the third line we finally run the test by including the same in the classpath and then using the JUnit command-line runner to run the test and that is org.junit.runner.JUnitCore and then the test class name.

The output of the test is shown in the last box, and apparently the test has failed. Highlighted in red is the reason why the test has failed expected:<0.0> but was:<Infinity> . This is actually good, because it demonstrate exactly what JUnit should do. Since we have not accounted for the zero division case in MyClass.division() method then the test must fail! To fix this we have to add a small piece of code to MyClass.division() method to account for the zero division case.


// the class to be tested
public class MyClass{
       public double division(double x, double y){
                // if division by zero case
                if(y == 0.0)
                       return 0.0;

                return x / y;
       }
}

Now that we accounted for this case let's run the test again. Following is the output of the second run of the test:


$ JUnit version 4.11-SNAPSHOT
..
Time: 0.007

OK (1 tests)

Voila! the test was successful, and resulted in no failures which theoretically means that our code in MyClass.java could be moved to production (assuming this is the only case which can result in division errors).

Most major IDEs such as Eclipse, IntelliJ and many others have integrated JUnit into their suite of tools. I hope that by this simple example you can get a glimpse of test driven development.


Thursday, March 8, 2012

Java Web Service Client with JAX-WS in Eclipse

In this tutorial, I will show how simple it is to create a web service client that consumes the web service created in the previous blog post. We will be using JAX-WS annotations to inject a reference to the web service in our web service client code. I will be using the Eclipse IDE (Indigo) to  build the web service client.


First let us start by creating a standard Java Project. I will name the project "SimpleCalculatorWebServiceClient". Click finish to allow Eclipse to create the Java Project.
Fire a Terminal or a Command Prompt and cd into the root directory of the project you just created. We will use the wsimport tool to generate the source files and classes you will need to  access the web service. Note that you will need the URL to the web service's WSDL file to execute the wsimport command. Following is the complete wsimport command that will generate all necessary files for you and place them in their respective directories under your Eclipse Java Project.


wsimport -s src/ -d bin/ http://localhost:8089/SimpleCalculatorWebService/CalculatorService?WSDL


Now refresh your project in Eclipse to see all the newly generated files by wsimport. Next, create a new class which will act as the client class. I named this class "CalculatorWSClient". Following is the client's code.

package com.moeabdol;

// jaxws imports
import javax.xml.ws.WebServiceRef;

public class CalculatorWSClient {

 // this is the reference to the web service
 @WebServiceRef(wsdlLocation="http://localhost:8089/CalculatorWebService/CalculatorService?WSDL")
 
 private static CalculatorService service;
 private static Calculator port;
 
 public static void main(String[] args) {
  CalculatorWSClient wsc = new CalculatorWSClient();
  service = new CalculatorService();
  port = service.getCalculatorPort();
  
  System.out.println("10 + 3 = " + port.add(10, 3));
  System.out.println("3 - 10 = " + port.subtract(3, 10));
  System.out.println("100 * 100 = " + port.multiply(100, 100));
  System.out.println("22 / 7 = " + port.divide(22, 7));
 }

}


Right-Click the project and select run as a java application. The results should show in the console window.



Tuesday, March 6, 2012

Java EE Web Service with JAX-WS in Eclipse

In this simple tutorial I will demonstrate step-by-step how to build a java web service using Java API for XML Web Services JAX-WS in Eclipse. The JAX-WS API is available in Java SE 1.5 and later. JAX-WS can be used to build web services and web service clients that communicate using XML messages. For the purpose of this tutorial I will be using:
  1. Eclipse IDE (Indigo) to create the web service.
  2. Glassfish application server to host the web service.
Make sure Glassfish is installed and configured in your Eclipse IDE. For more information on how to configure Glassfish in Eclipse refer to this link.

First open Eclipse and create a "Dynamic Web Project". Name the project "SimpleCalculatorWebService". Set the Target Runtime to Glassfish, and the configuration to minimal.

Take note of your source and output folders. We will use them later to generate the web service artifacts. Click finish to allow Eclipse to generate the project.








Create a new class under the source folder. This will be the implementation class of the web service. I named the class "Calculator". The following code is the web service implementation in the Calculator class. Note that I have added specific  JAX-WS annotations. @WebService to imply this class is an implementation of a web service, and a @WebMethod which implies that this is a web service method implementation.

package com.moeabdol;

// jaxws imports
import javax.jws.WebService;
import javax.jws.WebMethod;

@WebService
public class Calculator {

 @WebMethod
 public double add(double x, double y){
  return x + y;
 }
 
 @WebMethod
 public double subtract(double x, double y){
  return x - y;
 }
 
 @WebMethod
 public double multiply(double x, double y){
  return x * y;
 }
 
 @WebMethod
 public double divide(double x, double y){
  if(y == 0)
   return 0;
  else
   return x / y;
 }
 
}

Now we will use "wsgen" web service generation tool which will generate the web service portable artifacts. Start a terminal or command prompt and make sure JDK is in your PATH, then navigate to the root directory of the project and execute the wsgen command:


wsgen -verbose -keep -cp build/classes/ -wsdl -r WebContent/WEB-INF/ -s src/ -d build/classes/ com.moeabdol.Calculator


For more information about wsgen options, review the wsgen manual. If you're on a unix like machine just man wsgen.


Now, in Eclipse right-click the project and refresh it. You'll notice that wsgen has created some new source files and class files in your project. Most importantly, for each web method you created wsgen has created two java files for it. For example, the web method add which you have created wsgen created an add.java and an addResponse.java. These files will handle the requests and responses to this web methods. Moreover, wsgen also created a WSDL file for the web service implemented at com.moeabdol.Calculator.


We are almost done here. All we have to do next is to modify the WSDL file by changing where it says "REPLACE_WITH_ACTUAL_URL"  with the actual URL of the service "http://localhost:8089/SimpleCalculatorWebService/CalculatorService". Note that I'm deploying this web service to a locally installed instance of Glassfish and i configured Glassfish to use port 8089.



Right-Click the project and select Run -> Run On Server select Glassfish and click finish. The web service will be deployed on Glassfish. Now we don't have a web service client to test the web service, so we can use a facility provided by Eclipse. Under WEB-INF folder right-click on CalculatorService.wsdl and select Web Services -> Test with Web Services Explorer. Select the add method and enter any chosen numbers for arg0 and arg1 and click go. The response from the web service should show the result.







Sunday, December 18, 2011

The Hopfield Neural Network II

In this implementation of the Hopfield Neural Network, I designed the classes in a way that would make the network dynamic. By that I mean that the user can determine the size of the network during run-time of the program. Note that this post is a subsequent post to the original The Hopfield Neural Network I. Please refer to that post if you want to understand the internals of HNN.

Moreover, I decided that i will stick to the command-line interface since this is a dynamic application and it would be easier to create it in such an interface rather than to create the controls during run-time. Please note that there is one restriction and that is we can't create more than a 10 neuron neural net since the patterns are parsed to integers first and integers have specific sizes. I realized this late during the development and decided that I will fix this bug later because my intention was to demonstrate that the application can be dynamic.

Most importantly, the classes I added in this implementation are the Matrix.java, List.java and Node.java. Simple a Matrix type is nothing but a List of a Lists of Nodes. Each Node is an element or a cell in the Matrix, and each row is a List and the Matrix is a List of Lists.

Please take a look at the source code. Any suggestions and/or enhancements to the code are welcome.




Wednesday, December 14, 2011

Hopfield Neural Network

The Hopfield 4 Neurons Single Layer Neural Network
One of the simplest Neural Networks out there. Unlike other more complex Neural Nets, HNN employes a single network layer which is the input and output layer at the same time. This implementation of HNN contains four neurons acting together to recognize any four-digit binary pattern.

When the network is first initialized, it needs to be trained to recognize a specific binary pattern. Depending on the pattern we choose, the system will build what is called a weight matrix - during the training -. This weight matrix will help recognize the specific pattern we chose. When we feed the system with a new pattern and run the network, it will run the new pattern against the weight matrix and identify the pattern if it was the same original pattern or its inverse. Moreover, if the pattern was closely similar it will try to auto-correct the entered pattern. This is the auto-associative property of the Hopfield NN.

To construct the Hopfield NN we must first understand the mathematics behind it. Most of the math behind HNN is simple matrix operations and linear algebra. To further understand HNN I will take you through the process step by step.

This simple Hopfield network consists of four neurons and twelve connections constituting a one layer neural network. You can think of the network as a bidirectional graph of nodes. Each node has three outbound connections and three inbound connections as shown in the connections matrix below. Note that an idividual node (neuron) can't be connected to itself.

Furthermore, both the neurons and the connections between them are said to be a layer of the network. The Hopfield NN is categorized as a one layer NN. Meaning, the entire neural network is a single layer which is the input and output layer at the same time. We simply feed the patterns to this layer of neurons, and the neurons will decide wither to fire back output or not depending on the weight matrix.

Connections Matrix
Let us assume that the input pattern we wish the network to learn is (0,1,0,1). By default, the Hopfield network will learn this pattern and its inverse (1,0,1,0). O.K so the first step now is to teach the network how to recognize this pattern. We do this by constructing the weight matrix. Think of the weight matrix as the means for the network to understand, and the mechanism for it to recognize the pattern.

Constructing the weight matrix is a simple three-step process:
  1. Convert the original input pattern to its bipolar equivalent pattern.
  2. Multiply the bipolar pattern with its transpose vector to construct the contribution matrix.
  3. Set the Northwest diagonal to zeros.
Converting the original input to its bipolar equivalent is nothing more than to represent the same patterns in (-1) and (1) because when dealing with binary digits (0) is not the inverse of (1). Rather (-1) is the inverse of (1). Thus we change all (0) in the input to (-1) as in the right figure. The bipolar equivalent now is (-1,1,-1,1).
Multiplying the bipolar vector with its transpose vector is a simple matrix operation. The resulting 4x4 matrix is nothing but the first row of the bipolar multiplied by the first column then the second column then the third and finally the fourth. Then the second row multiplied by the first column then second and so on. Finally we set the northwest diagonal to zeros to come up with the final weight matrix. This is the matrix that will do all the pattern recognition.


Each row in the weight matrix will be the weight vector of each neuron respectively. So neuron one will have a weight vector of (0,-1,1,-1) and neuron two's weight vector will be (-1,0,-1,1) and so on. The weight vector of each neuron will help decide wither the neuron should fire or not with the assistance of a threshold function. 

O.K so now we assume that the network has been trained to recognize (0,1,0,1) and during the training it constructed the weight matrix shown above. Now I will demonstrate how the system will recognize the new input (0,1,0,1). First digit (0) will be feed to neuron one and the second digit (1) will be feed to neuron two and so on. Each neuron will sum up digits from its weight vector where the input pattern is equal (1). The following should demonstrate this step for neuron one.


The first row is the input we want to recognize, and the second row is the weight vector of neuron one. We will only sum up the digits from the weight vector where the input patter is equal (1). So we should get (-1 + -1 = -2). For all the neurons we should get the following.


These values are said to be the act of each neuron. Acts by themselves don't determine if the neuron should fire or not. To decide that we should pass these values individually to a threshold function that will determine if the neuron should fire or not. Many neural network books discuss various threshold functions. For our purposes we will use the simple hyperbolic tangent function as our threshold function.


So now simply we substitute the act of each neuron in the above equation as (x) and come up with the hyperbolic tangent. If the tangent is greater than or equal to (0), the neuron fires. If the neuron fires then the equivalent output should be (1); otherwise, the equivalent output is (0). 

That's it. Now you fully understand the Hopfield Neural Network. My upcoming exercise is to make this HNN dynamic by trying to determine the size of the network during run-time. To test the network yourself you can download my Java source code and compile the files yourself. All thanks goes to Jeff Heaton for his tremendous efforts in simplifying Neural Nets.