Friday, March 29, 2013

Scala Call-By-Value Versus Call-By-Name

This tutorial demonstrates the difference between call-by-value and call-by-name method parameters. By default, method arguments are passed call-by-value. This is the evaluation that you're probably already familiar with from Java. With call-by-value, the arguments that are passed to the method are evaluated as an expression before the control flow is passed to the method. Here are two methods with the exact same code in the method body. They simply execute a loop for five iterations, referencing the parameter "x" within each iteration. The only difference is that the first method takes a call-by-value parameter (notice the => syntax), while the second method takes a call-by-name parameter.

  def callByValue(x : Unit) = {
    for (i <- 0 until 5) {
      print(x)
    }
  }
  
  def callByName(x : => Unit) = {
    for (i <- 0 until 5) {
      print(x)
    }
  }


Now, let's see what happens to the value of the parameter when we call these two methods with an expression that increments the function value by one (i = i + 1). When we call the callByValue method, the result of the value after the function call is simply i = i + 1.


  def main(args: Array[String]) {
    var i = 0
    
    callByValue(i = i + 1)
    
    print(i)  // "1"
  }


What's happening here is that the expression i = i + 1 is being evaluated one time, before the control flow is passed to the callByValue method. However, after calling the callByName method instead of callByValue, the result of the variable "i" is 5.


  def main(args: Array[String]) {
    var i = 0
    
    callByName(i = i + 1)
    
    print(i)  // "5"
  }


The reason this is happening is because when a parameter is call-by-name, the value of the parameter is evaluated every time it's referenced in the method. It's being referenced 5 times, so the expression i = i + 1 is being executed 5 times.

Tuesday, March 26, 2013

JVM Code Generation with Jasmin

When you write your own programming language, you're tasked with writing a lexer and parser. But, once that's complete, you still have to execute the code somehow. If you're looking to target the JVM as a runtime, you need to compile your source code down to JVM bytecode, which can seem like a daunting task. However, Jasmin, which has been around for many years, is a very useful framework that makes this much easier. This tutorial takes you through the steps of creating a simple Hello World program with Jasmin. The result is a HelloWorld.class file that you can run at the command-prompt with Java. In future tutorials, I'll go through more complex examples, but you have to start somewhere. I put the full code on GitHub: https://github.com/travisdazell/Jasmin-HelloWorld


Step 1: Download Jasmin

You can download Jasmin here: http://jasmin.sourceforge.net.

Download and extract the ZIP file to your PC. I have it installed on my root, so the result is a C:\jasmin-2.4\ directory on my PC.


Step 2: Write the Jasmin code for the HelloWorld class.

Let's create a simple Hello World program and then discuss the code in more detail. Here's the complete example:

; class definition
.class public HelloWorld

; extends java.lang.Object
.super java/lang/Object

; default constructor -- public HelloWorld() { super(); }
.method public ()V
 aload_0
 invokenonvirtual java/lang/Object/()V
 return
.end method

; main method -- public static void main(String args[]) { ... }
.method public static main([Ljava/lang/String;)V
 .limit stack 2     ; we're allocating 2 items we plan to put on the stack
 
 ; push System.out onto the stack
 getstatic java/lang/System/out Ljava/io/PrintStream;
 
 ; push the constant "Hello World" string onto the stack
 ldc "Hello World"
 
 ; print the result that's on the top of the stack
 invokevirtual java/io/PrintStream/println(Ljava/lang/String;)V
 return
.end method


Let's review the Jasmin code so that you get an understanding of what's involved. The first two lines are fairly self-explanatory. We're just defining the name of the Java class and its superclass. In this example, the superclass is just java.lang.Object.


; class definition
.class public HelloWorld

; extends java.lang.Object
.super java/lang/Object


Note the use of the slash (/) in the package structure. That's one of the differences between actual Java code and Jasmin. The next step is to define the default constructor.


; default constructor -- public HelloWorld() { super(); }
.method public()V
 aload_0
 invokenonvirtual java/lang/Object/()V
 return
.end method

The last section of code is our main method. Within this method, the first thing we do is specify the size of the stack for the method. In our case, we only need a stack size of 2, because we're only going to be putting System.out and the constant "Hello World" string on the stack. The last step is to print the result that's on top of the stack and return.


; main method -- public static void main(String args[]) { ... }
.method public static main([Ljava/lang/String;)V
 .limit stack 2     ; we're allocating 2 items we plan to put on the stack
 
 ; push System.out onto the stack
 getstatic java/lang/System/out Ljava/io/PrintStream;
 
 ; push the constant "Hello World" string onto the stack
 ldc "Hello World"
 
 ; print the result that's on the top of the stack
 invokevirtual java/io/PrintStream/println(Ljava/lang/String;)V
 return
.end method


Step 3: Save the file and compile it to bytecode

Save the file as HelloWorld.j and then run the following command from the command-prompt:


C:\> java -jar "C:\jasmin-2.4\jasmin.jar" HelloWorld.j

The output will be a HelloWorld.class file that you can run using Java!


Wednesday, March 20, 2013

Implementing a Content-Based Router Using Camel

Often times, we're faced with the problem of routing a message at run-time based on the content of the message. Consider the following example. Let's say we receive all incoming orders in a single queue. However, we have two order processing services. The first service processes our normal customer orders, but we have a separate service that processes orders placed internally by employees. How do we solve this problem? A content-based router pattern solves this problem of determining where to route a message at run-time. Here's an example of a Content-Based Router implementing the example I described (the image is credited to http://www.enterpriseintegrationpatterns.com/ContentBasedRouter.html).




Thankfully, it's extremely easy to implement a content-based router pattern in Camel. If you're not familiar with using Camel, refer to my tutorial on Implementing Pipes and Filters Using Camel. It's a different integration pattern, but it walks through the basics of using Camel.

Now that you're familiar with Camel, let's look at how you would define a content-based router in your Camel route.


    <!-- content based router -->
    <route>
        <!-- get message from JMS ORDERS.INCOMING queue -->
        <from uri="activemq:queue:ORDERS.INCOMING">

            <!-- route the order to the correct queue -->
            <choice>
                <when>
                    <simple>${header.type} == 'customer'</simple>
                    <to uri="activemq:queue:ORDERS.CUSTOMER"></to>
                </when>
                <when>
                    <simple>${header.type} == 'employee'</simple>
                    <to uri="activemq:queue:ORDERS.EMPLOYEE"></to>
                </when>
            </choice>
        </from>
    </route>

Tuesday, March 19, 2013

Web Service Client in Java Using JAX-WS

This tutorial describes how to consume a SOAP web service in Java using JAX-WS. For this tutorial, we'll create a client application that makes a call to a SOAP service hosted on wsf.cdyne.com.

  1. The first step is to import the WSDL of the web service to create the client proxy code. From the command prompt, navigate to the directory where you want to generate the client code and type: "wsimport -s . http://wsf.cdyne.com/WeatherWS/Weather.asmx?WSDL". After running this command, you'll find a \com\cdyne\ws\weatherws directory has been created with a number of .java and .class files.


  2.  
  3.  Next, we'll write a simple Java class and main method to invoke the web service.
  4.   public class WeatherTest {
      
        public static void main(String args[]) {
            Weather weather = new Weather();
          
            WeatherSoap weatherSoap = weather.getWeatherSoap();
          
            ForecastReturn forecastReturn = weatherSoap.getCityForecastByZIP("56701");
          
            ArrayOfForecast arrayOfForecast = forecastReturn.getForecastResult();
            List<Forecast> forecasts = arrayOfForecast.getForecast();
          
            for (Forecast forecast : forecasts) {
                System.out.println(forecast.getDate().toString() + " " + forecast.getDesciption());
            }
        }

    }


  5. The output from this program is:
    2013-03-14T00:00:00 Mostly Cloudy
    2013-03-15T00:00:00 Snow
    2013-03-16T00:00:00 Partly Cloudy
    2013-03-17T00:00:00 Partly Cloudy
    2013-03-18T00:00:00 Snow
    2013-03-19T00:00:00 Partly Cloudy
    2013-03-20T00:00:00 Partly Cloudy

Monday, March 18, 2013

AES CBC Mode Encryption

If you've used javax.crypto to do encryption, then you're familiar with the code below that obtains an instance of a Cipher (note that the code below is written in Scala).

val encryptCipher = Cipher.getInstance("AES/CBC/PKCS5Padding", BouncyCastleProvider.PROVIDER_NAME)

The first parameter to getInstance is where you specify the type of encryption you want to use. In the example above, I'm using AES encryption in CBC mode This tutorial explains what CBC mode really means and what's happening under the hood.

AES encryption starts by dividing the plaintext message into 128-bit blocks. The result looks something like this:


Once the message has been divided into 128-bit blocks, the message is encrypted using CBC mode. CBC mode stands for "Cipher Block Chaining" mode. In pseudo-code, the steps of the CBC algorithm are as follows:

1. A random initialization vector (IV) is generated and then XORed with Message[0].
2. The result of the XOR operation is fed into the encryption function E(k, m) where k is the encryption key and m is result of the XOR operation.
3. The result of the encryption function becomes the first 128-bit block of the ciphertext (ciphertext[0]).
4. ciphertext[0] is then XORed with Message[1].
5. The result of the XOR operation is fed into the encryption function E(k, m) where k is the encryption key and m is the result of the XOR operation.
6. This continues until the entire message has been encrypted.

Here's what CBC mode AES encryption looks like with a picture:




You can see why it's called cipher block "chaining", as the result of each encryption function is chained to the XOR of the next plaintext message block. Note that if the message can't be divided evenly into 128-bit blocks, the last plaintext block is padded to make it 128-bits. If, however, the message divides evenly into 128-bits, the plaintext message is appended with a dummy block of 128-bits before encryption.

In a future blog post, I'll describe how AES encryption with CTR mode works, and how it differs from CBC mode.

Sunday, March 17, 2013

Implementing Pipes and Filters Using Camel

Pipes and Filters is an integration pattern that solves the problem of having to process a job or task in a series of sub-tasks. If you're not familiar with pipes and filters, read my post on describing the design: Pipes and Filters - Integration Pattern.

This tutorial describes how to implement the pipes and filters integration pattern using Apache Camel. The source code is on GitHub: https://github.com/travisdazell/camel-pipes-and-filters

The key component of this application is the Camel route that's defined in spring-context.xml:

<camelContext xmlns="http://camel.apache.org/schema/spring">

  <!-- pipes and filters example -->
  <route>
 <!-- get message from JMS FOO.BAR queue -->
 <from uri="activemq:queue:FOO.BAR" />

 <!-- use the simple language to transform the input to upper case -->
 <transform>
  <simple>${body.toUpperCase()}</simple>
 </transform>
 
 <!-- route the input to the messageReceiver bean, which will modify the message slightly -->
 <to uri="bean:messageReceiver?method=processMessage"/>
 
 <!-- route the output from the messageReceiver bean to the output console -->
 <to uri="stream:out"/>
  </route>

</camelContext>


This route has four steps/filters. The pipeline begins when a JMS message is posted on the FOO.BAR queue. Next, I'm using Camel to convert the message body to upper-case. The third step in the pipeline sends the result of the upper-case transformation to a Spring bean with an ID of "messageReceiver". Notice the use of "?method=processMessage". This allows us to route the message to the processMessage() method on the messageReceiver bean. The last step of the pipeline is to output the results of the processMessage() method to the console.

In summary, the following items are the main components when implementing the pipes and filters integration pattern in Camel:

  1. Defining the Camel route. In this example, I'm using Spring to define the route.
  2. The result of the first step is the input to the second step. The result of the second step is the input to the third step. And so on...
  3. Use the following Camel URI to route a specific message in a Java class, where {beanId} is substituted with the ID of the Spring bean and {methodName} is the name of the method in the bean.
uri="bean:{beanId}?method={methodName}"

Wednesday, March 13, 2013

Scala Parser Combinators - Part 2

Scala Parser Combinators - Part 3 >


In Part 1 of Scala Parser Combinators, I introduced Scala parsers and gave an example of a trivial DSL that parsed arithmetic operations. I also demonstrated how to evaluate the language and print the results of the parsing operation. I'm going to expand on this example by showing how to transform the flat result string into a useful set of structures.

Rather than simply printing the results of the parsing operation, let's look at how we would evaluate the arithmetic operation to compute the result. For example, rather than parsing "9*8+21/7" and printing "(9~Some((*~(8~Some((+~(21~Some((/~(7~None))))))))))", we would like the parser to return "75".

Before we begin, though, it's important to understand what something like "(9~Some((*~(8~Some((+~(21~Some((/~(7~None))))))))))" really means in the world of Scala. Let's look at a subset of this string, "(9~Some((*~(8~None))))". This is the result of parsing "9*8". The first part that looks interesting is the "9~Some(...)". In the previous tutorial, we defined the following rule in our parser:

def expr: Parser[Any] = number ~ opt(operator ~ expr )

It's clear that "number" is evaluating to "9" and "~" is being printed out verbatim (which you should recall is used in Scala parsers to join parts of the grammar). However, what's with "Some(...)"? Well, whenever Scala parses an opt(x) statement, it will evaluate it as either Some(...) or None, both of which are subclasses of Option. That makes since... the opt(x) statement evaluates to an Option.

Instead of having our parser return a bunch of ~ and options, let's look at transforming the parser results into something more useful. Again, looking at our current parser rule:

def expr: Parser[Any] = number ~ opt(operator ~ expr )

We need to modify this parser definition to have it return an Int instead of Any. This is simple:

def expr: Parser[Int] = ...

The next step is to compute the result of the arithmetic operation. Our grammar rule allows for either a single number or a number followed by an arithmetic operator and another number. If we're dealing with a single number, we need to tell the parser to convert the result to an Int. To do this, we make the following modification to our parser rule:

def expr: Parser[Int] = (number ^^ { _.toInt }) ...

The ^^ just tells the parser to execute the code that follows it, contained in {...}. All we're doing is converting it to an Int.

Next, we need to tell the parser what to do when it encounters a number, or when it encounters a number followed by an operator and another number. For this, we need to define the integer operation for each situation (single integer value, addition of two values, subtraction of two values, division of two values, and multiplication of two values).

Again, we start by adding ^^ to our rule to include the Scala code that we want to execute in these situations. The result is:

def expr: Parser[Int] = (number ^^ { _.toInt }) ~ opt(operator ~ expr ) ^^ {
    case a ~ None => a
    case a ~ Some("*" ~ b) => a * b
    case a ~ Some("/" ~ b) => a / b
    case a ~ Some("+" ~ b) => a + b
    case a ~ Some("-" ~ b) => a - b
}

There are five cases we're handling. The first is the situation where we have just a single integer (a ~ None). When we have an Int with None after it, we simply evaluate the integer value as-is. The second situation is when we have an integer being multiplied by another integer (a ~ Some("*" ~ b)). In this case, we simply perform a * b. We then proceed to define the rules for division, addition, and subtraction.

The key take-aways from this tutorial are:
  • You define the type that your parser rule is returning within the brackets of the Parser[ ] definition. In this example, it's an Int.
  • You can add custom Scala code to operate on the parser results with ^^ { ... }

This works great for this simple arithmetic DSL. However, for anything more involved than this simple example, we most likely need to build a parse tree (or better yet, an AST) that we can process. I cover an introduction to parse trees in the next tutorial on Scala Parser Combinators.

Thursday, March 7, 2013

Scala Parser Combinators - Part 1

Scala Parser Combinators - Part 2  >


Scala ships with a parser library for writing your own lexers and parser from within Scala. It's a really nifty mechanism for writing DSLs embedded within a Scala program. For this example, let's write a parser that parses simple mathematical expressions, such as "1+9*8" and "4*6/2-5". An EBNF grammar for this language would look like this:

digit ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

number ::= digit | digit number

operator ::= "+" | "-" | "*" | "/"

expr ::= number (operator expr)?


To start writing a parser with the Scala parsing library, we write a class that extends the Parsers trait. Here's an example of a class that extends RegexParsers, a subtrait of Parsers.

class ExprParser extends RegexParsers {
    val number = "[1-9][0-9]+".r

    def expr: Parser[Any] = number ~ opt(operator ~ expr )

    def operator: Parser[Any] = "+" | "-" | "*" | "/"
}


The only difference between the Scala definition of the valid tokens and the EBNF definition is the following:
  • Scala utilizes a "~" between each token
  • Instead of using a "?" like you would in EBNF, Scala uses the keyword "opt"
  • Although this isn't used in the Scala code shown above, instead of using a "+" to denote repetition as you would in EBNF, Scala uses the keyword "rep"
 To run this parser, we simply invoke the inherited parse method that's part of the inherited Parsers trait.

 def main(args : Array[String]) {
    val parser = new ExprParser

    val result = parser.parseAll(parser.expr, "9*8+21/7")

    println(result.get)
}


The result of this println will be:

(9~Some((*~(8~Some((+~(21~Some((/~(7~None))))))))))


Of course,this isn't a very useful result at this point. However, it sets the foundation for writing a parser in Scala using the parser library. Check out Part 2 on Scala Parser Combinators, where we expand on this topic and look at how to modify this result into something that's more useful.

Using ActiveMQ as an XMPP (Jabber) Messaging Server

This tutorial demonstrates how to use ActiveMQ as a message broker for XMPP (Jabber). In this tutorial, we'll install ActiveMQ and use it for our message broker (i.e. server). We'll then use the Spark instant messaging client to create a chat room so that we can send and receive messages between IM clients.

The first step is installing ActiveMQ. For this example, we'll install everything on a Windows PC. Follow these steps to install ActiveMQ:

1. Go to http://activemq.apache.org and click the download link on the right-hand side of the page.
2. Click the link to download most recent stable version (5.7.0 at the time of this writing).
3. Click on the download link for the Windows distribution.



4. Unzip the download to a directory on your PC. I have it unzipped on the root of my C: drive.
5. Open the \apache-activemq-5.7.0\conf\activemq.xml file in an editor.
6. Edit the "transportConnectors" section of the configuration file by adding the XMPP transport.

        <transportConnectors>
               ...
               <transportConnector name="xmpp" uri="xmpp://0.0.0.0:61222"/>
        </transportConnectors>


7. From the command prompt, run \apache-activemq-5.7.0\bin\activemq



Now that you have ActiveMQ installed and the XMPP transport running on port 61222, open the following URL in your browser to view the ActiveMQ web console: http://localhost:8161/admin/



At this point, ActiveMQ is running and waiting for XMPP messages to arrive. We just need an IM client installed to start sending messages. Download and install Spark (http://www.igniterealtime.org/downloads/download-landing.jsp?file=spark/spark_2_0_0.exe). Note that I'm using v2.0.0.

After installing Spark, open it and enter the following at the login screen. Of course, you can use your own name, but put @localhost after your username and put "localhost" for the server.


Next, click on the "Advanced" link at the bottom of the login dialog. Within this screen, un-check the box for "Automatically discover host and port" and enter "localhost" for the Host and "61222" for the Port. Click OK.


Now click the "Login" button. After logging in, you'll see the following screen.






Next, we need to create a chat room. The chat room will auto-magically become a JMS Topic on the ActiveMQ server. From within Spark, there is a button underneath the "Online" indicator to "Join Conference Room". After clicking that button, you'll see the following dialog.



Next, click on the button for "Create or Join Room". You'll see the following dialog where you'll enter the name of the JMS Topic. I chose to name it CHAT.ROOM.





After clicking the "Create" button, click the "Join" button on the next dialog.


The next dialog will display the chat room window and show that you've joined the room.





The next step is to publish an IM message and watch it appear in our Spark client. To test this, go back to your browser where you have your ActiveMQ web console (http://localhost:8161/admin/). Click on the menu link that says "Topics". You'll see a list of JMS Topics on your ActiveMQ server and one of them will be the CHAT.ROOM Topic that you just created. Click on the link for that Topic.


After clicking on that link, you can post a message to the Topic by entering a message in the text area and clicking the "Send" button.


Now, if you go back to your Spark IM client, you'll see the message has been received by the client. That's it!

Wednesday, March 6, 2013

Pipes and Filters - Integration Pattern

Arguably one the simplest integration problems we encounter is having to process a complex job in a sequence of steps. Most of these problems are part of a workflow requirement. Examples include processing an order, approving a purchase order, and applying a credit to an account. Each of these business problems usually requires a series of steps to be performed in a certain sequence. This integration problem can be easily solved using Pipes and Filters. Here's an example of Pipes and Filters being applied to the processing of an incoming order (image is credited to http://www.eaipatterns.com/PipesAndFilters.html).





Essentially, Pipes and Filters is just a breakdown of a requirement into a series of connected steps. Each step is called a "filter" and the transitions between two filters is called a "pipe". When faced with having to process a large job in a series of processing steps, you should consider implementing the Pipes and Filters pattern.

It's important to implement a Pipes and Filters pattern in such a way that makes it easy to add and remove filters at any location in the process. To achieve this flexibility, I recommend using a framework such as Camel. Camel makes it very easy to add, remove, replace, or rearrange the processing steps with very little work and risk to your project. Read my tutorial on Implementing Pipes and Filters Using Camel to learn how Apache Camel makes this easy to implement and maintain.