From XML to object

We have seen how easy is to marshal a Java object to XML when using JAXB, now I am showing you how to unmarshal an XML in a (compatible) Java object using the same library.

We have this XML fragment:

<user id="42" rating="4.2">Bill</user>

And we want to get from it an instance of the class User, as defined in the previous post. The (minor) nuisance is that I have to annotate User so that JAXB knows how it should map its data member to the XML elements, values, and attributes. Once this is done, we get the job done in a matter of few lines:

public User xml2Obj(String xml) { // 1
    try {
        JAXBContext ctx = JAXBContext.newInstance(User.class); // 2
        Unmarshaller um = ctx.createUnmarshaller(); // 3

        StringReader sr = new StringReader(xml);
        User user = (User) um.unmarshal(sr); // 4
        return user;
    } catch (JAXBException e) {
        e.printStackTrace();
        return null;
    }
}

1. This function gets in input the XML to be unmarshalled, and gives back the resulting User object (or null, in case of error).
2. A JAXB context is needed to do the magic, and it should know on which class it operates.
3. A JAXB marshaller is the guy that is going to do the dirty job.
4. To keep the unmarshaller code simple, it has been designed to operate on readers. So, the XML String is passed to a StringReader to adapt it to the JAXB expectations.

The full Java source code for the User class and a Main class using it are on github. The example includes both marshalling (as seen in the previous post) and unmarshalling.

Go to the full post

From object to XML

JAXB (Java Architecture for XML Binding) provides an easy way of converting Java objects to XML. In the JAXB jargon, this is know as marshalling, where unmarshalling means the opposite action of extracting a Java object from an XML.

As a first example, let's see how to create an XML fragment like this:

<user id="42" rating="4.2">Bill</user>

from a Java class named User that has the user name, id, and rating as data member.

Even if this looks like a pretty simple job, still there are a couple of points that it could be interesting to pay attention to. Large part of the JAXB job is done by annotations, with the result that the code looks quite simple to understand at first sight, once you know what it is going on.

In this case, I want my class User to have a couple of annotations, one to state that it represents a root XML element, and the second one to let JAXB know that I want to put an annotation to the data fields, and not to their getters, to specify their XML role.

The result is something like this:

@XmlRootElement // 1
@XmlAccessorType(XmlAccessType.FIELD) // 2
public class User {
    @XmlValue
    private String name;
    @XmlAttribute
    private int id;
    @XmlAttribute
    private float rating;

    // getters and setters follow ...
}

1. This class is the root element for my XML
2. If you don't explicitly say that the accessor type should be found in the field definition, JAXB gets confused. If you comment this line out, you get an IllegalAnnotationsException, and a message saying that "Class has two properties of the same name".

Once you have defined your JAXB annotated class, it is just a matter of creating an object, and marshalling:

public String obj2xml(User user) {  
    try {
        JAXBContext ctx = JAXBContext.newInstance(User.class); // 1
        Marshaller marshaller = ctx.createMarshaller(); // 2
        marshaller.setProperty(Marshaller.JAXB_FRAGMENT, Boolean.TRUE); // 3

        StringWriter sw = new StringWriter();
        marshaller.marshal(user, sw); // 4
        return sw.toString();
    }
    catch (JAXBException e) { // 5
        e.printStackTrace();
        return "<bad />";
    }
}

1. Create a JAXB context that knows about the User class.
2. Then from the context we get a marshaller.
3. Here I want to generate just an XML fragment, if I want to generate a full XML document, I would remove this line, and the generated XML would have this header:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

4. Ask the marshaller to send its output to a StringWriter, from which the resulting XML could be extracted as a String.
5. In case of anything goes wrong, give an alarming feedback to the user (not a very polite thing to do, but here it will suffices) but still return a valid XML.

The full Java source code for the User class and a Main class using it are on github.

Go to the full post

Three solutions to the loop problem

The lack of a block scope in JavaScript leads to what is often called The Infamous Loop Problem, where we try to use the (supposed) cycle variable in a for loop to set a callback function.

Conceptually, the solution is quite easy. The trouble is caused by the loop variable, that actually does not have a local scope, so we provide to it a local scope. In JavaScript we have only function scope, so a function would help us to find a way out.

The question is, which function? Whichever it is better for you in your context, I'd say. Let's see the three answers that I guess are more natural.

In the previous post I have written a buggy piece of code that was storing a few functions when looping on an array, an then, in another for loop, it called those functions. Now I modify it to let it work as I expected, following three different approaches.

Closure in loop

This is the most idiomatic solution using "pure" JavaScript. We wrap the code in the for loop around a closure, designed just to provide a local scope for the loop variable.

function doSomething(msg) {
    console.log(msg);
}

var messages = [ "hello", 42, { pi: 3.14 } ];
var buffer = [];

for(var i = 0; i < messages.length; ++i) {
    buffer[i] = (function(j) { // 1
        return function() { // 2
            doSomething(messages[j]);
        }
    })(i); // 3
}

// ...

for(var k = 0; k < buffer.length; ++k) {
    buffer[k]();
}

1. We put in buffer the function returned by a closure, here defined, that take as input a parameter, named j, that is assigned a value defined in (3).
2. The function returned by the closure is almost the same function we defined in the original code. The difference is that I don't use anymore the loop variable, but the closure parameter.
3. This is the core of the solution. I assigned to the closure parameter the loop variable, in this way the closure captures its current value, that now has a local scope, as required.

After a while, I guess this would look as the most natural approach, but if your JavaScript mileage is low, you could be find it a bit overwhelming. In this case, maybe you could be more at ease with the following variation.

Closure in the function

The idea is to move the closure from the for loop to the recipient function. I refactor the code above, rewriting the for loop and doSomething(), renamed doSomethingElse() for the sake of clarity.

function doSomethingElse(index) {
    return function() { // 1
        console.log(messages[index]);
    }
}

// ...

for(var i = 0; i < messages.length; ++i) {
    buffer[i] = doSomethingElse(i); // 2
}

// ...

1. The closure has been moved here. Notice that this function does not run any code, but returns a function.
2. Just a simple assignment!

This code is so much readable, but I am losing the connection between the loop (2) and the reason why I need a closure in (1). Someone who reads just doSomethingElse() would probably wonder why it returns a closure instead of doing directly its job.

jQuery.each()

If we use the jQuery library, we can get the advantages of both the previous solutions using the each() method.

We use the original doSomething() function, and we don't need a closure in the for loop, jQuery.each() is a function, so it provides its own scope.

$.each(messages, function(index, value) { // 1
    buffer[index] = function() { // 2
        doSomething(value);
    }
});

1. For each element in the messages array, we call a function where the first parameter is the current index, and value the message element currently accessed.
2. There's no need of a closure, we simply assign to the buffer element a function that calls doSomething(). The capturing of local values is performed by jQuery.each().

Go to the full post

The JavaScript infamous loop problem

There is no block scope in JavaScript. Once you get used to this truth, the loop issue stops to be mystery, and you can say goodbye to a bunch of quirky behaviors in your code.

The for loop is a typical construct where many programmers get surprised by JavaScript. So I decided to write this post to make the issue as clear as I can. In the next post I present a few alternative solutions.

Simple loop through an array

Let's start looking at a plain for loop that won't give any trouble at all. I have an array of mixed objects, I want to call for each of them a function that does something not relevant here:

function doSomething(msg) { // 1
    console.log(msg);
}

var messages = [ "hello", 42, { pi: 3.14 } ]; // 2

for(var i = 0; i < messages.length; ++i) { // 3
    doSomething(messages[i]); // 4
}

1. I don't care much of what this function actually does, logging the parameter is more than enough.
2. This is the array I want to loop through.
3. A local variable, i, is declared and used as temporary location for the current element in the array.
4. The function is called for each element in the array.

As I said, this way to walking through an array works fine. Still, we should be aware of the fact that the supposed loop variable is not actually limited to that scope, but it is available all over the function scope in which the for loop is placed.

This doesn't work

Let's think to something a bit more complicated. Say that I don't want to call immediately the other function, I want to create an array of function, so that I can call them later, after I do some other task.

I could (wrongly) think to refactor the previous piece of code in this way:

function doSomething(msg) {
    console.log(msg);
}

var messages = [ "hello", 42, { pi: 3.14 } ];
var buffer = []; // 1

for(var i = 0; i < messages.length; ++i) {
    buffer[i] = function() { // 2
        doSomething(messages[i]);
    }
}

// ...

for(var j = 0; j < buffer.length; ++j) {
    buffer[j](); // 3
}

1. Temporary place where storing the functions to be called in a second time.
2. For each element in the message array, I create an unnamed function that calls doSomething().
3. And after a while I call all the functions stored in the buffer.

At a first sight, it looks like we should have the same result of the first example. But here we get just a desolating list of "undefined".

What happened here? The problem is that the loop variable is not actually such. So, when in (3) we call doSomething() through the buffer, the index is the current value (actually, the length of the message array) and not its value when in (2) we assigned the function to the buffer.

What we need to do is to capture the current value of the loop variable in (2) so that would be used in (3). We can achieve this result in a couple of different ways, as we'll see soon.

Go to the full post

Adding a DOM element

If you have to modify an existing DOM document in the fly by adding a HTML fragment, you can use the jQuery appendTo() method, that would simplify your job. Being jQuery smart enough to create a jQuery object from a HTML literal fragment, we can even operate on it before appending it.

To add a bottom line to an HTML page, I could write:

var fragment = $('<p><i>Bottom line</i></p>'); // 1
fragment.find('i').attr('class', 'z'); // 2
fragment.appendTo('body'); // 3

1. I create a P element containing an I element, containing some text.
2. Before actually adding it to my document, I can modify it. Here I get the I element and add to it an attribute, class='z'.
3. Finally, I add my fragment at the end of the BODY element.

There is no need of writing this code on three lines, I can squeeze it on just one, but I have to be careful:

$('<p><i>Bottom line</i></p>').find('i').attr('class', 'k').end().appendTo('body');

I need to call end() before appendTo(), otherwise I put to the document only the element returned by find(), and the paragraph would be lost.

Go to the full post

How andSelf() improves find()

We have seen how the jQuery methods filter() and find() differ. Now we see how to improve find() combining it to another useful method, andSelf(), that works smoothly with it.

I want to draw a box around my unsorted lists, and also around the included links. To do that, I can write this JavaScript oneliner:

$('ul').find('a').andSelf().css('border', '1px solid blue');

I select all the ULs in my document, than I find all the included A elements, and I join the two sets by calling andSelf(). Finally I call css() specifying that I want to put a thin blue line border around them.

Go to the full post

Choosing between filter and find

The .filter() and .find() jQuery methods look similar, and it could happen to mix them up. Still there is substantial difference between them, .filter() modifies the current set of elements, reducing it by applying the specified rule, while .find() operates on the children of the current set, returning a completely different set of elements.

Say that we are working on an HTML page containing a few lists, and we want to do something on some list items, the LI elements marked with a specific class, and we want to work on the links defined in any list item.

In the first case we'll use the .filter() method, since we want to refine the existing selection, for the latter .find() is the right choice, being our aim to select a new set elements among the children of the original set.

Here is a JavaScript code fragment:

var $li = $("li"); // 1

var $liK = $li.filter('.k'); // 2
console.log($liK, $liK.length);

var $a = $('a'); // 3
var $liA = $li.find('a'); // 4
var $LiA2 = $('a', $('li')); // 5
var $LiA3 = $('li a'); // 6
console.log($a, $a.length, " -", $liA, $liA.length, " -", $liA2, $liA2.length, " -", $liA3, $liA3.length);

1. Selecting all the LI elements in the current document.
2. Restricting the original set to the LI elements having class='k' as attribute.
3. All the anchor elements in the document.
4. Find the anchor elements children of LI elements.
5. Same result of (4), asking to jQuery to get all the A elements children of a LI.
6. Same of (4) and (5), and in this case probably the preferred way to the result.

Go to the full post

Selecting DOM elements

Selecting DOM elements of a given type in a document is a simple task, and we can easily do it using standard JavaScript functionality. Nevertheless, jQuery makes it even simpler.

Here is the code to get all the LI elements in the current document, both in plain JavaScript, and using jQuery:

var li = document.getElementsByTagName("li"); // 1
var $li = $("li"); // 2

console.log("li: ", li, li.length);
console.log("$li: ", $li, $li.length);

1. The getElementsByTagName() method returns a NodeList, a structure that is array-ish but does not derive from Array. It sports a property, length, that contains the number of element contained, and lets the user access each of them through the [] operator. An out of bound request is resolved to null.
2. A call to jQuery factory function returns a jQuery object that, for what we care here, is not different from a NodeList object, but it is enriched by extra-information and functionality, that could be useful in more a demanding context.

Go to the full post

When this does not work, use that

There is an issue in "this", the JavaScript keyword identifying the current object.
It works fine in an object member functions (AKA methods) but not in their inner functions. An easy way to bypass the problem requires us to create a member variable, that is often called "that" (or "self", but it is usually considered a weaker option).

Does it remember you an Abbott & Costello skit, "who's on first?", or it is just me? Anyway, an example should help clarifying the matter.

Say that we want to have an object, named calculator, keeping an internal status and providing a couple of methods, opA() and opB(), to perform some obscure calculations. The first operation is not too complicated, but opB() requires some messy stuff to be done, and we think that it would be a good idea to organize it defining an inner function that, among the other things, calls a free function.

It should be all not too complex to do, still we have to deal with the above mentioned issue.

var elaborate = (function(x) { // 1
    var cache = 0;

    return function(x) {
        cache += x;
        return cache;
    }
}());

var calculator = {
    status: 0,
    opA: function(x) { // 2
        this.status += x;
    },
    opB: function() { // 3
        var that = this; // 4
        var somethingComplicated = function() {
//            this.status += elaborate(this.status); // 5
            that.status += elaborate(that.status); // 6
        };
        
        somethingComplicated(); // 7
    }

    calculator.opA(3);
    calculator.opA(4);
    calculator.opB();
    console.log(calculator.status);
};

1. I defined elaborate() as a closure, so that it could keep its own status. See details in a previous post, static variable by closure.
2. This first method is trivial. It gets a parameter in input (assumed to be a numeric value), and adds it to the object property (status). To access the object property the keyword "this" is used. Not an issue here, for the object methods, the bind between "this" and the object itself is correctly done by JavaScript.
3. More complications here. In opB() we define a function, somethingComplicated(), that calls elaborate(), the closure defined in (1). The issue is that we can't use "this" in the body of somethingComplicated(), because "this", at that point, refers to the global scope or is undefined (if we "use strict" JavaScript, as we should).
4. "this" don't work as we would like in inner functions, but we can patch this behavior defining a local variable in the function, often called "that", that stores the value of "this" so to do as a bridge to the inner function.
5. As said above, this line doesn't work. "this" is undefined ("use strict") or points to the global scope. Hardly what you usually need.
6. This line saves the day. We use "that" to get access of the unavailable "this".
7. So we can happily call our somethingComplicated() inner method.

Go to the full post

Strictly or loosely false

Being Javascript a loosely typed language, comparing a value for its truthiness could lead to an unexpected behavior if you, well, do not expect it.

To perform a strict checking, you should use the strict comparison operator "triple equals", and you should be aware that by default the loose "double equals" operator is used.

There is a bunch of values that are loosely evaluate as false (friendly known as "falsy"):

var myUndef, // undefined
    myNull = null,
    myFalse = false,
    myEmpty = '', // empty string
    myZero = 0, // numeric zero
    myNan = parseInt('not a number'); // parsing a non numeric string returns NaN
    
if(myUndef || myNull || myFalse || myEmpty || myZero || myNan) // 1
    console.log('Unexpected');

try {
    if(myNotExisting) // 2
        console.log('Unexpected');
}
catch(e) {
    console.log(e);
}

if('false') { // 3
    console.log('Misleading');
}

1. All these values (undefined, false, empty string, zero, NaN) are loosely equals to the boolean false value, so the next line is not executed.
2. This variable was even not declared, checking it results in an exception of type ReferenceError.
3. The string 'false' is not converted to the boolean false value, and it is evaluated to true.

Go to the full post

Hello jQuery

If you are developing JavaScript's for a web application that should run in the wild, you know the pain of writing code that should run on large part of the available browsers. A common approach is delegating to a library the bore of taking care of the details, better if it has the side effect of providing a high level interface. A popular choice in this field is represented by jQuery, recently released in its 1.8 version.

Writing an Hello jQuery application is pretty easy.

Firstly, you'd better get the library on your local machine. You can fetch it following the instructions in Download jQuery.

Actually you could avoid this step and refer to a publicly available copy of it, see CDN hosted jQuery for details. Whichever strategy you follow, you should ensure your script gets access to the jQuery library. In my case, I have simply put the js file in the same directory of the html that you can see below.

My hello page pops up an alert with greetings after the HTML page is fully loaded. It is not much, but this ensures that the jQuery library is properly linked:

<html>
<head>
    <meta charset="UTF-8">
    <title>Hello jQuery</title>
    <script src="jquery-1.8.0.js"></script> <!-- 1 -->
    <script>
        $(function(){ // 2
            alert("Hello from jQuery");
        });
    </script>
</head>
    <body>
        <h1>A JavaScript/jQuery powered page</h1>
    </body>
</html>

1. I ask to the browser to go and load the jQuery library. I have put it in the current folder, so I specify just its name. In production code, it would almost certainly be somewhere else.
2. I called a function named $ (just the single character "dollar"), passing to it an anonymous function that calls the alert() function. This is quite an implicit way of calling the jQuery ready event handler. Maybe it looks more clear if I rewrite it in this way:

jQuery(document).ready(function() {
    alert("Hello from jQuery");
});

The dollar sign is a mere synonym for the jQuery() function. And, if you dig in the jquery.js code, you'll find out that passing a function to jQuery is a shortcut for calling the document ready event handler.

Putting our call to alert() in the jQuery ready() body, we ensure that it is called only after the DOM document associated to the current HTML page is fully loaded.

Go to the full post

String and regular expressions

The JavaScript String class has a few methods that could be used with RegExp. Here is a breaf introduction to them: split(), search(), match(), and replace().

split

Regular expressions make String.split() more flexible:

"1, 2, 3".split(", "); // 1
"1 ,  2 ,3".split(/\s*,\s*/); // 2

1. This is how is commonly called split(). If we are sure on how the separator is, it works fine, and returns an array of three elements containg just the numbers. But what if we have no control on the blanks? And we could have no blanks, or many of them, around a comma? You usually won't be happy with the result.
2. This is the solution. A comma is the real separator, and any blank around it is eaten out.

search()

Passing a RegExp to search() on a specified string, we get back an integer representing the index of the first match, or minus one if there is no match:

"JavaScript".search(/script/); // 1
"JavaScript".search(/Script/); // 2
"JavaScript".search(/script/i); // 3
"Here is 1 for you, 3 for me, 42 for the others.".search(/\d+/g); // 4

1. The search is by default case sensitive, so the pattern here is not found, and the function call returns -1.
2. The match is found starting on 4.
3. We can override the default, saying that we want to perform a case-insensitive search, specifying the "i" flag after the pattern. This function call returns 4.
4. The global option makes no sense in this context, and it is silently ignored. The returned value is the position of the first match, 8.

match()

The match() behavior is quite articulate. Its output should be interpreted differently accordingly to the provided input. Seeing it in action should clarify what I mean:

var s = "Here is 1 for you, 3 for me, 42 for the others.";
s.match(/\d+/); // 1
s.match(/\d+/g); // 2
"My email address is someone@not.existing.zzz".match(/(\S*)@(\S*)/);

1. We ask to match() to return just the first subsequence matching the specified pattern, in this case a string of one or more digits. It returns a vector containing one element, "1".
2. Global matching, a vector is returned containing all the matching elements, in this case three strings, "1", "3", and "42".
3. The RegExp represents an email address, first part is the sequence of not-blank characters before the "at" symbol; second part is what is after it, till we get a blank. Notice that we asked match() to capture $1 and $2 as left and right side of the "at". In this case match() returns an array containing in first position the full matching element, and in the next positions $1, $2, ...

replace()

This function returns a copy of the original string where, if the RegExp is found, it is replaced by the second parameter passed:

"... javaScript ... javascript ... Javascript ...".replace(/javascript/gi, "JavaScript"); // 1
"I want to have 'doublequotes' in this string!".replace(/'([^']*)'/g, '"$1"'); // 2

1. Notice the two flags associated to the RegExp, specifying that we are preforming a global and case insensitive search. All the three JavaScript variation in the string are found and replaced by the string passed as second argument to the function.
2. What we are saying here is: search for each {g option} sequence starting with a single quote {'}, followed by any number {*} of any character but a single quote {[^']} and a single quote, and call $1 the subexpression in the round parenthesis. Then replace what you have found with a double quote, the $1 subexpression, and another double quote.

Go to the full post

Factory pattern for a more robust constructor

A JavaScript constructor is just a simple function. It should be called through the "new" operator so that it would provide its added value of setting "this" to refer to the newly created object, inheriting from the function prototype, and returning a reference to "this" object. But what if a client programmer mistakes the sense of our construct, and calls it as a simple function?

Let's think what happens when the constructor I defined in the previous post is called directly:

function Rectangle(a, b) {
    this.a = a;
    this.b = b;
}

// ...

var rx = Rectangle(6, 7); // !! bad mistake !!

So, I forgot to use "new", and Rectangle is treated by JavaScript as a normal function call. What happens is barely that, in the global scope, two properties named a and b are created (if not already there) and set to 6 and 7. Then "undefined" is returned and assigned to the variable rx.

Is this what I really wanted to happen? Hardly so. And even in that case, I should have used a different function to make clear that it was intentional, and not a silly mistake.

I can think to a couple of ways to improve my code: signaling the user programmer that he is doing something unexpected, or silently transform his mistake in the right thing. In the first case I would typically throw an exception, in the second one I would use the factory pattern.

Throwing an exception

This is the most clean but unforgiving solution. To implement it, we check "this" in our constructor function. If it is not associated to the instance of the function, it means that the user didn't call it properly. So we raise an exception, and the let the user programmer the burden to deal with it.

function Rectangle(a, b) {
    if(!(this instanceof Rectangle))
        throw 'Remember to use "new" to call a constructor!';
    
    this.a = a;
    this.b = b;
}

// ...

try {
    var rx = Rectangle(3, 4);
}
catch(e) {
    console.log(e);
}

As I said, this is clean code, and if you have a background in languages supporting static type, you should appreciate the predictability of what it is going on here. The caller does something wrong, he gets a rigorous "no, no" back.

Still, it doesn't looks right to me, when compared to the normal JavaScript behavior.

Factory pattern

Less clean, more forgiving. If someone calls a constructor as a simple function, we patch his code on the fly, converting it to a proper constructor call. The user programmer could now create a new Rectangle calling the constructor as was originally expected, or as a normal function:

function Rectangle(a, b) {
    if(!(this instanceof Rectangle))
        return new Rectangle();

    this.a = a;
    this.b = b;
}

// ...

var rf = Rectangle(12, 2);
// ...

Your choice

I feel that using the factory pattern is more in the JavaScript way of writing code, but I guess this is a matter of which kind of application you are developing, team programming conventions, and the such.

In any case, I would suggest you to choose one of the two approaches (or three, if you think that, after all, not checking is a viable option), and keep it in all your project.

Go to the full post

JavaScript constructor

If you have a background in strong-typed programming languages (as I have, incidentally), the JavaScript concept of class could look fuzzier than expected.

Here I show a standard way of defining a class, with a variation.

You are need in your code a lot of rectangles. In C++, Java(, etc), you would define a class Rectangle, and put in it all the relevant data and method. The JavaScript approach is different: you define a function where you create its associated data properties, using the parameter passed by the user, and let the function inherit from its prototype all the other properties you need.

This function smells like a constructor, acts like it, so it is actually called constructor, and typically given a name starting with an uppercase letter to visually show that here there is something special. But remember that, from the JavaScript point of view, it is just a plain function. The magic is done when we call it through the "new" operator. It is its job to perform the association between the constructor and its prototype, and make the constructor return by default its "this" pointer.

Here is an example where I define, instantiate, and use a Rectangle:

function Rectangle(a, b) {
    this.a = a;
    this.b = b;
}

Rectangle.prototype = {
    constructor: Rectangle, // 1
    toString: function() { return "a = " + this.a + ", b = " + this.b; }, // 2
    area: function() { return this.a * this.b; },
    perimeter: function() { return 2 * (this.a + this.b); }
}
    
var r = new Rectangle(4, 10); // 3
console.log("rectangle: ", r.toString()); // 4
console.log("area: ", r.area());
console.log("perimeter: ", r.perimeter());
console.log("Is r a rectangle? ", r instanceof Rectangle); // 5
console.log("Rectangle constructor: ", Rectangle.prototype.constructor); // 6

1. Backlink from the Rectangle prototype and its constructor.
2. All the JavaScript objects have a toString() method, here we redefine it to give some useful information to this specific type.
3. This is the core of the story: we call Rectangle through the "new" operator. If we forget to do it, we do not create a new object, we simply call a function that creates a couple of properties in the global scope and returns an undefined value.
4. Now we can use r as a Rectangle object.
5. Notice that the instanceof operator performs a check of the object against a constructor. Actually it won't check if the object has been built through that constructor, but if it inherits from the constructor's prototype.
6. If you comment out the line (1), you'll see here why we need it. Defining a function prototype as showed, leads to overwriting the default constructor property, breaking the backlink to that function. So we have to reset it.

To avoid the nuisance of (6) we could create just the properties we really need, and not redefine the complete prototype:

Rectangle.prototype.area = function() { return this.a * this.b; };
Rectangle.prototype.perimeter = function() { return 2 * (this.a + this.b); };
Rectangle.prototype.toString = function() { return "a = " + this.a + ", b = " + this.b; };

Choose whichever approach you think is more suitable to you.

The weakest point in this design is in (3). Rectangle is just a function, calling it directly is not an error, from the JavaScript perspective, even if it almost ever it doesn't make much sense and leads to a disaster.

Using the factory pattern our code would be stronger, as I am going to show in the next post.

Go to the full post

Currying and binding

If you wonder where the term currying is coming form, the answer is in the Haskell Brooks Curry logician name, and it refers to the partial application of parameters to a function. In JavaScript this is done by the bind() method, defined in ECMAScript 5.

And if you wonder what is all this fuss about binding and currying, you probably don't have a background in functional programming or, as it is my case, in C++. But don't worry, it is easy to catch up, and I reckon you are going to fall in love with them too.

Say that you have written a complicated function, you spent a lot of time to develop, test, and maintain it. You are very happy with it, and your users too. Let's simulate it with something a bit simpler:

function sum(x, y) {
    return x + y;
}

Then you find out that your cool function is often used passing always only a "real" parameter, being the other just a constant. In my example, the story would be that I wrote a sum() function, but I find out that the users often need just an increase(). Duplicating the code looks a poor solution, it would be better to create an adapter that provides just a more natural interface to the user, but keep almost all the coding effort in the original function.

Here I define next(), as a synonym of sum() that always uses 1 as a first parameter, and lets the user specify the other one:

var next = sum.bind(null, 1);

console.log("original interface", sum(42, 1));
console.log("more natural solution", next(42));

Good. But what is the null I passed to bind() as first parameter?

The fact is that JavaScript() bind() is not only about currying but, as its name suggests, it also performs an optional binding of the function to a specified object. In the previous case we didn't have any object interested in this feature, so I just passed a null instead.

To see bind() in full action, let's change a bit the startup condition. We already have an increasing function, but now it is a method, bound to an object:

var calculator = {
    step: 1,
    increase: function(x) {
        return this.step + x;
    }
};
console.log(calculator.increase(42));
calculator.step = 2; // 1
console.log("Double step: ", calculator.increase(42));

As we see in (1) it is pretty simple to change the increasing step in my calculator, but the user it is not completely happy with this solution. He didn't care of such a flexible solution, what he needs is just a function that returns its passed parameter increased by 2.

Luckily, we know that using bind() we can associate a function to different object, like this:

var step2 = calculator.increase.bind({step: 2}); 
console.log(step2(42));

We call bind() on the calculator.increase() method, and we pass to it as first (and only) parameter its new "this". In this case we don't want the step to be modifiable by the user, so we pass the object anonymously, making its reference lost to the outside world.

Go to the full post

One scope, more closures

JavaScript uses closure as an elegant way to hide a function internal status the rest of the world. It is simple to extend the concept and let more closures share the same variables.

My original sequence generator had its status defined as a property, and as such visible by everybody who had access to the function itself. I decided that was bad, and I refactored it as a closure. Cool, but the client programmer needs to modify the sequence internal status, to be able to skip ahead of a few numbers when needed.

To achieve this result, we need to do a substantial change to our code:

var sequence = (function() {
    var current = 0;
    return { // 1
        get: function() { // 2
            return current++;
        },
        skip: function(delta) { // 3
            if(delta > 0) // 4
                current += delta;
        }
    }
}());

1. The external anonymous function does not return anymore a single function, but an object containing a couple of properties, that happens to be functions.
2. The first property is named get, and it actually is our old sequence generator.
3. Here is the required improvement, a function named skip that changes the sequence generator internal status.
4. I didn't provide much error handling to the code, but I couldn't help to put at least this line, meant to avoid the user to move the sequence back and forth.

A use test for the new sequence:

for(var i = 0; i < 3; ++i)
    console.log(sequence.get()); // 1
sequence.skip(3); // 2
for(var i = 0; i < 3; ++i)
    console.log(sequence.get());

1. Get each time a new sequence number, starting from zero.
2. Skip three numbers in the sequence, before getting more numbers.

Go to the full post

Closure for static variable

Function static variable in JavaScript are easily emulated by function property. But if we want to make it private to the function, we'd better use a closure.

The first times you see a JavaScript closure at work, you could get lost in the code, but being it such a common paradigm, you are going to get used to it in almost no time:

var sequence = (function() { // 1
    var current = 0; // 2
    return function() { // 3
        return current++;
    }
}()); // 4

for(var i = 0; i < 3; ++i)
    console.log(sequence());

1. We define as a variable as ... what? There's an anonymous function definition starting here, and if we jump to (4) we see that the function is invoked just after being defined.
2. In the function body we see a local variable definition, that results being private to the function. No way anyone outside could see or modify it.
3. And here we see what our anonymous function returns: another function! This internal function does the dirty job of post-incrementing the current sequence number and returning it.
4. This means that JavaScript has to invoke the anonymous function, that returns the internal function, that returns - when called - the sequence number.

A bit contrived, isn't it? But the good news is that now we can simply call our "sequence" variable to increase and get the sequence number, exactly in the same way we called the original sequence generator. And, as required, its internal status is not visible anymore from outside.

Go to the full post

Static variable emulation

Keeping in mind that JavaScript considers functions just like specialized objects, it is easy to define something that acts like a C static variable.

As an example, let's see how we can implement and use a sequence generator:

sequence.value = 0; // 1
function sequence() {
    return sequence.value++; // 2
}

for(var i = 0; i < 3; ++i)
    console.log(sequence()); // 3

1. Define a property named value in the sequence function, initialized to zero. In this way we don't pollute the namespace in which the function is defined with a name that is used just by the function.
2. The current value is returned and then incremented.
3. Calling our function we get a new increased value each time.

This could be good enough in many case, but the fact that the internal status of the sequence function is visible and modifiable from anyone that sees the function itself could be sometimes worrisome.

A better solution, as we'll see soon, is to refactor our sequence function to become a closure.

Go to the full post

The Math object

The JavaScript developer has access to a bunch of commonplace mathematical constants and functions through the Math object. As official reference you should check the ECMA-262 5.1 standard, even if I should confess that I find more readable the Mozilla Developer page.

To calculate a circumference, it is nice to have a PI constant available:

var radius = 1;
var circ = 2 * Math.PI * radius;
console.log("Circumference is ", circ);

The resulting value should be something around 6.283185307179586.

We can convert a number to integer by approximation using round(), or we can use ceil() and floor(), to flatten the result to the left or to the right.
Let's see what happen applying these functions to the natural logarithm of 10:

var value = Math.LN10;
console.log(Math.floor(value), " <= ", value, " <= ", Math.ceil(value));
console.log("Rounding", value, " -> ", Math.round(value));

The max() and min() functions accept in input any (reasonable) number of parameters, and its returned value is the bigger or smaller one in the lot.

var values = [ -42, 5, Math.E ];
console.log(Math.max(values[0], values[1], values[2]));
console.log(Math.min(values[0], values[1], values[2]));

Min is -42, max is 5.

There are also the usual functions to calculate exponential values, Math.exp(), logarithm,

Math.log(), power, Math.pow(), a short cut for square roots, sqrt(), and the common trigonometric functions.

Playing around with JavaScript numerical functions, you can end up getting Infinity, -Infinity, and NaN.

console.log("Divide by zero:", 3 / 0); // Infinity
console.log("Divide by zero:", -3 / 0);  // -Infinity
console.log("Not a number:", 0 / 0);
console.log("Not a number:", Math.sqrt(-2)); // Nan

Go to the full post

Primitive or wrapper object?

JavaScript is a very forgiven language, we can often be very vague when considering the type of a variable. Usually we can think of primitive instances almost as if they were wrapper objects. Still there is a subtle difference, and we'd better be aware of it.

See this variable definition:

var rawStr = "test"; // 1
var objStr = new String("test"); // 2

1. A primitive string is defined.
2. A wrapper object String is defined.

The two variables could be usually considered as identical, still they are not strictly the same:

if(rawStr == objStr) // 1
    console.log("rawStr is a " + typeof(rawStr) + ", objStr is a " + typeof(objStr));
if(rawStr !== objStr) // 2
    console.log("strictly speaking, a string is not equal to an object String");

1. A raw string and a wrapper String containing the same sequence of characters are loosely seen as equal, but the typeof() operator shows that they actually have a different type (string and object).
2. If we strictly compare them, we see that they are actually different.

Same behavior applies to numbers and booleans:

var rawNum = 42;
var objNum = new Number(42);
if(rawNum == objNum)
    console.log("rawNum is a " + typeof(rawNum) + ", objNum is a " + typeof(objNum));
if(rawNum !== objNum)
    console.log("strictly speaking, a number is not equal to an object Number");

Go to the full post

Hello JavaScript, and null vs. undefined

The cool thing about JavaScript, is that you don't need almost anything to start working with it. If you reading this on a modern browser, you should have already all at hand. Maybe, if you are on Firefox, you would prefer to do download a plugin (and I'm thinking to Firebug) to have some debugging fire power. And that's it. You are ready to write your first JavaScript application.

My Hello World JavaScript application amazingly does some little more than greeting the user. It also shows what is the difference among null and undefined in this language.

If you have any reason not to use the console object, that lets you to write log without pestering the browser with a popup, you could fallback to the old, and annoying, alert() function.

Here is the HTML that I have written:

<html>
<head>
    <title>Hello JavaScript</title>
    <script type="text/javascript"></script>  <!-- script language specification -->
</head>
<body>
    <script>
        var a; // 1
        var b = null; // 2
        
        if(a == b) // 3
            console.log("undefined is loosely equal to null");
        if(a === b) // 4
            ;
        else
            console.log("undefined is strictly not equal to null");        
        
        document.write("Hello World!"); // 5
    </script>
</body>
</html>

If you are new to JavaScript there are a few interesting things to notice.

In the head section I specified the scripting language I am about to use. JavaScript is understood by a large share of browsers, and often it is assumed by default. But it is always a good idea to document that we are actually using it. Here I am writing HTML code, so the associated comment on the right is a HTML comment (less than, exclamation mark, minus minus ... minus minus, greater than).

In the body I specify a script section and in it I do a few things. Notice that here I am actually writing JavaScript code, so I follow its conventions. Among the other things, we can see that comments are in Java style, a double slash till the end of the line. I could have used also the C/C++ old-style comments (slash, star .... star, slash).
1. A variable is declared but not defined.
2. Another variable is declared, but here it is also defined, even if the associated value is just a null.
3. Undefined is similar to null, and the standard comparison operator is sort of fooled to see them as equals, so the next line is actually executed. We can see the output in the Console tab of Firebug.
4. But undefined is not the same of null, and the strict comparison operator is smart enough to detect the difference, so the next (empty) block is not executed, but we jump directly to the "else" block, and we write that log to the console.
5. In any case we politely say hello to the user.

Go to the full post

Map subsetting by keySet().toArray()

I recently faced a non-standard request, for which I implemented a solution that doesn't make me completely happy. But I have not much time to ponder of it, and it works. I write it down here, so that maybe someone (or myself in the future) could show me a better alternative.

Developing for Java 6, using just the core functionality. It is given a map of Strings and whatever, and an index of one of its elements, we want to reduce the original map to a subset such as: (1) the resulting map would contain 10 elements maximum, (2) the element given by index would be the first, (3) the traversing map order is preserved.

We don't know the actual type of the map object in input, we know only that it implements the Map interface, meaning that we can't use the handy SortedMap.subMap() method.

My first idea was iterating on the map associated entry set, removing all the items before the index, then executing a dummy loop for ten times, before removing the tail elements (if any). It works, but the central dummy loop is quite boring.

So I opted for going through the keySet map, converting it to an array, so that I could randomly access any element in it:

String[] keys = (String[])myMap.keySet().toArray(new String[myMap.size()]); // 1
for(int i = 0; i < first; ++i) // 2
    myMap.remove(keys[i]);

for(int i = first + max; i < keys.length; ++i) // 3
    myMap.remove(keys[i]);

1. This line is painful. Given a myMap object (it instantiates a class that implements the Map interface, as described above), we call on it keySet(), that returns a set, on it we call the toArray() method, that converts it to an array. I have already written something on the toArray() involuted syntax, using this overload we can specify the actual type of the returned array. 2. Assuming first is an int variable, representing the index of the elements we are interesting it, defined before this code snippet. Here we are removing the leading elements. 3. The max variable stores the maximum number of elements we want to have in the resized map. The effect is removing all the trailing elements.

Go to the full post

Per-queue message time-to-live (TTL)

One of the RabbitMQ protocol extension to the AMQP specification is that we can specify the messages lifetime on a queue. This is done setting the x-message-ttl argument to a non-negative integer value, representing the time to live in milliseconds.

For instance, if we want to use a queue named "ttl", with a time to live of half a second, we could write something like this (I use Java 7, as you can deduce from the diamond operator):

public class SendRecTTL {
    private final static String QUEUE_NAME = "ttl";
    private final static int TTL = 500;
    private Map<String, Object> args = new HashMap<>();

    public SendRecTTL() { args.put("x-message-ttl", TTL); }

    // ...

        channel.queueDeclare(QUEUE_NAME, false, false, false, args);

A message sent to this queue would expire after half a second, and would be considered "dead".

I have written a simple test application for the current RabbitMQ version (2.8.2) that sends and receives a message on such a queue. Adding a sleep between the two actions, we can see what happen if the delay is too big.

Better if your code is prepared to not receive anything, not hanging forever:

QueueingConsumer.Delivery delivery = consumer.nextDelivery(1000);
if(delivery == null)
{
    // ...

Full Java source code on github.

Go to the full post

Hello Maven

As a primer on Maven, there is nothing better than the Five Minutes Getting Started Page on its Apache site. Here you could find just a few extra notes I jotted down when I was reading it.

Once you have downloaded and unzipped the Maven package on your machine, you could run this basic command:

mvn --version

to ensure it is up and ready.

The most common issues you could have at this time are:

• you can't see Maven from your current directory
• Maven can't see Java

Ensure that the environment variables PATH and JAVA_HOME are properly set to avoid this problems. PATH should include also the Maven bin folder, and JAVA_HOME should refer to your preferred base JDK directory (notice that JDK is required, JRE is not enough).

Create a project

You can create a Java project from scratch running this Maven command (it is a single line, even if I split it to make it more readable):

mvn archetype:generate -DgroupId=package.name -DartifactId=app.name
-DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

I have used "helloMaven" as artifact id, and "hello" as group id. The artifact id is the root directory where all the stuff related to this you application will be stored, and the group id is the name of a package that would be created, and where a simple hallo App would be created by Maven.

Proxy issue?

Maven tries to connect to its remote repository to get what it needs and couldn't be found locally (or for a newer version of it). If you get an error here, it is often due to a proxy issue.

If you do have such problem, you should have a look at the settings.xml file in the conf directory in you Maven installation.

In the "proxies" section you should create a "proxy" block containing all the information required to go through your proxy. In its minimal form it looks something like this:

<proxy>
  <protocol>http</protocol>
  <host>your.proxy</host>
  <port>80</port>
</proxy>

When Maven works fine, you get a directory structure based in the specified artifactId, that would contain in its first level a src folder and a pom.xml

The Project Object Model (if you wonder what pom stands for) XML that I got is:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>hello</groupId>
  <artifactId>helloMaven</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>helloMaven</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

Project build

To build our project we run:

mvn package

The result is published in the "target" folder. And, if we had no error, we can run our application in this way:

java -cp target/helloMaven-1.0-SNAPSHOT.jar hello.App

Notice that the JAR name is built putting together the artifact id and the version field, as stored in the POM.

Go to the full post

JMS Request-Reply

Implementing the Request-Reply messaging pattern with ActiveMQ is not complicated. The client component sends a request to the server on the dedicated queue, it attaches to it, as properties, the destination queue where it expects to find the reply, and a correlation id to uniquely identify the request-reply couple. The server uses these information to generate a consistent reply.

The complete Java source code is on github, here I comment just what I think are the most interesting part of the code.

This it the client, after establishing a connection to the broker:

Destination destination = session.createQueue(REQUEST_QUEUE_NAME); // 1
MessageProducer producer = session.createProducer(destination);
Destination dRep = session.createTemporaryQueue(); // 2
TextMessage message = session.createTextMessage(arg);
message.setJMSCorrelationID(UUID.randomUUID().toString()); // 3
message.setJMSReplyTo(dRep); // 4
producer.send(message);
// ...
MessageConsumer consumer = session.createConsumer(dRep); // 5
Message reply = consumer.receive(); // 6
// ...

1. The queue where the requests are sent.
2. A second queue, for the replies. We could have used a "normal" queue, but it is more common to create a cheaper temporary queue for this task.
3. We could keep track by hand of the unique message ids generated by the application, or we could delegate to Java the generation of an unique id, as I did here.
4. The queue to be used as destination for the reply is stored in the JMSReplyTo message property.
5. A consumer is created on the reply queue.
6. And the client patiently waits for an answer from the server.

The interesting part of the server is where it replies to the client:

if(message instanceof TextMessage) {
    TextMessage answer = session.createTextMessage(); // 1
    answer.setText("Reply to " + ((TextMessage) message).getText());
    answer.setJMSCorrelationID(message.getJMSCorrelationID()); // 2
    MessageProducer producer = session.createProducer(null); // 3
    producer.send(message.getJMSReplyTo(), answer);
}

1. The message to be sent as answer.
2. The correlation id is sent back to the client.
3. A producer with no associated queue is created, we are going to explicitly set the destination in its send() method using the JMSReplyTo message property.

Go to the full post

Embedding a broker by BrokerService

Instead of having the ActiveMQ broker as a standalone process, we could decide to have it embedded in one of our Java processes. The other processes would access it in the same way as before, but from other threads within, we could send and receive messages to the broker using the faster internal vm protocol.

A possible advantage of this solution is that the broker could be programmatically configured before it starts, and we could have a logic to determine when to stop it:

BrokerService broker = new BrokerService();
broker.setBrokerName("myBroker");
broker.setDataDirectory("data/"); // 1
// ...
broker.addConnector("tcp://localhost:61616"); // 2
broker.start(); // 3
// ...
broker.stop(); // 4
// ...

1. For a default setup, in the data directory it is created a folder for the broker (using its name, in this case we set it to "myBroker") containing a folder where the KahaDB files for message persistence are stored.
2. Let's our broker to be mimic of a standard broker.
3. When the broker setup is completed, we start it.
4. Shutting down the broker.

The complete Java source code for this example is on github.

Go to the full post

Selecting messages by custom properties

A JMS message comes with a number of standard properties, providing information on the associated message. For example, each message comes with a message id that could be fetched calling getJMSMessageID(). Besides, we can use custom properties to enrich a message in any way we think make sense for our specific case. An interesting aspect of custom properties is that we can use them to discriminate on which message a consumer should receive.

Think to an application where the producer generates messages for the best offers we have in our hardware store. The consumer could be interested in all or only in a subset of them. For this reason, it could be useful to put in the message payload just a generic description, and use custom properties to store structured information, as the product name and its price.

In this way the consumer could easily specify if it wants to get all the messages, or create a selector on the custom properties. The rules to create a selector are coming by simplification from the SQL conditional expressions.

The complete Java source code of this example is on github, it is written for ActiveMQ, so you should have this MOM installed and working on your development environment.

The producer delegates the most interesting part of its job to the send() method, that creates a message, fills it with specific data, and then send it to its associated queue:

TextMessage message = session.createTextMessage();
message.setText(txt);
message.setStringProperty(PROP_DES, des); // 1
message.setDoubleProperty(PROP_PRICE, price); // 2
producer.send(message);

1. Create a String property named as defined in the first parameter ("Description"), and containing the value stored in the second one ("Pins" and "Nails" in my test example).
2. The PROP_PRICE (actually, "Price") property is of type double.
In this test it is handy using a MessageListener, as discussed in a previous post, so that all the relevant messages are consumed by its onMessage() method:

logger.info("{}: {}", PROP_DES, message.getStringProperty(PROP_DES)); // 1
logger.info("{}: {}", PROP_PRICE, message.getDoubleProperty(PROP_PRICE)); // 2
logger.info("Message id: {}", message.getJMSMessageID()); // 3
logger.info("Message: {} ", ((TextMessage) message).getText());

1. The PROP_DES property is retrieved from the message, as the String that it is.
2. PROP_PRICE is a double, but we could have managed it as a String, calling getStringProperty(). ActiveMQ knows how to convert the internal double value to a String, so this cast works fine. If we tried to do the other way round, extracting a double from (1), we would have got a NumberFormatException.
3. There is not much use for this line here, but it is just to show a standard JMS property at work.

We need just one fundamental step, telling the JMS Session that the consumer has to get only some message:

switch (arg) {
    case "Nails":
    case "Pins":
        filter = PROP_DES + " = '" + arg + "'"; // 1
        consumer = session.createConsumer(destination, filter);
        break;
    case "Cheap":
        filter = PROP_PRICE + " < 15"; // 2
        consumer = session.createConsumer(destination, filter);
        break;
    default:
        consumer = session.createConsumer(destination); // 3
        break;
}

1. The string "Description = Nails" (or "Description = Pins") is passed in the next line to the session as a message selector for the consumer that has to be created. Only the messages true under that condition are delivered to this consumer.
2. Same as above, but the condition is now "Price < 15".
3. A "normal" consumer is created, with no associated selector.

Go to the full post

Asynchronous Hello ActiveMQ consumer

It is simple to modify the hello ActiveMQ example to change the consumer from syncronous to asyncronous.

If we want to asynchronously consume a message, we have to create a class that implements the JMS MessageListener interface, something like:

private class MyMessageListener implements MessageListener {
    @Override
    public void onMessage(Message message) {
        if(message instanceof TextMessage) {
            try {
                logger.info("Received {} ", ((TextMessage) message).getText());
            } catch (JMSException e) {
                logger.error("Can't extract text from received message", e);
            }
        }
        else
            logger.info("Unexpected non-text message received.");
    }
}

Then the consumer code changes only slightly:

MessageConsumer consumer = session.createConsumer(destination);
consumer.setMessageListener(new MyMessageListener()); // 1
try{ Thread.sleep(1000); } catch(InterruptedException e) {} // 2

1. Associate to the consumer an instance of our listener.
2. Usually we should implement a more sophisticated way of keeping alive the consumer till all the relevant messages are consumed. But for this simple example sleeping for a second should be enough.

The Java source code for the hello producer-consumer example, both in the synchronous and asynchronous flavor, is on github.

Go to the full post

Hello ActiveMQ

Writing an hello application with ZeroMQ is very easy, RabbitMQ requires a bigger effort, and ActiveMQ is not complicated, but probably the less immediate in the company. This escalation in complication is reflected also in the system's responsiveness (ZeroMQ is blazing fast and, compared to it, ActiveMQ could seem slow) but is well repaid by a higher level of offered services.

It is impossible to say in abstract which Message Queue structure is "better". It is more a matter of selecting the adequate one for specific environment requirements. A reason to decide for ActiveMQ is often that it implements the JMS specification.

In any case, say that we have already decided, and we have installed ActiveMQ on on our machine. Now it is time to write an hello application.

ActiveMQ is bundle with SLF4J as logger. I have talked of the trickiness in their relation in a previous post, so let's assume this is not an issue anymore. If you don't even know what SLF4J is, you could have a look at another post where I have written some notes on its installation.

Producer

The following code is all you need to establish a connection to the ActiveMQ broker and put a text message on a queue:

ConnectionFactory factory = new ActiveMQConnectionFactory(); // 1
Connection connection = null;
try {
    connection = factory.createConnection(); // 2
    connection.start();
    Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE); // 3
    Destination destination = session.createQueue(QUEUE_NAME); // 4
    MessageProducer producer = session.createProducer(destination); // 5
    TextMessage message = session.createTextMessage(arg); // 6
    producer.send(message); // 7
    logger.info("Sending: {}", message.getText()); // 8
} catch(JMSException ex) {
    ex.printStackTrace();
} finally { try { if(connection != null) connection.close(); } catch (JMSException e) {} } // 9

1. Since no address is specified, ActiveMQ assumes we want to connect to default broker, on localhost:61616.
2. A new connection to the browser is created and, in the next line, started.
3. On a connection we create a session, that could be transactional. Here we don't need it, so we pass "false" as first parameter. The second parameter specify if we want to acknowledge explicitly the message consume or not. Here we let ActiveMQ to take care of this.
4. Where the message is going to be sent. If the queue specified does not exist, ActiveMQ creates it for us.
5. The producer is an object created by the session for a specified destination that takes care of the message move from this client to the broker.
6. A text message is created from a String (in this case "arg" is the variable containing it).
7. The producer sends the message.
8. Remember that we are using SLF4J as a logger, if you wander about the strange syntax in the string, you may be interested in the post I have written on the efficiency reason for it.
9. Whatever happens in the try block, we want the connection to be closed.

Consumer

Consuming a message on ActiveMQ is not much different than producing it:

MessageConsumer consumer = session.createConsumer(destination); // 1
Message message = consumer.receive(1000); // 2
if(message == null)
    logger.info("No pending message on {} queue.", QUEUE_NAME);
else if(message instanceof TextMessage) // 3
    logger.info("Received: {}", ((TextMessage)message).getText());
else // 4
    logger.info("Unexpected non-text message consumed.");

1. First difference, we create a consumer on the session.
2. A message is consumed. The passed parameter is a timeout. If no message is waiting for us on the queue, and nothing arrives in a second, the consumer returns a null.
3. In the producer we created a text message, so we expect it to be of the same type here. If this is what we have, we work with it.
4. If we get here we are perplexed: who put a non-textual message on our queue?

You you want to play with the complete source Java code, you can find it on github.

Go to the full post

Installing ActiveMQ

What you need to run ActiveMQ on your machine is a recent Java development kit, and ActiveMQ itself. You can find the latter in the official Apache ActiveMQ download page, and you can get more information on the process in the related Getting Started page.

The ActiveMQ broker is ready to run out of the box, on its default port 61616, simply running a batch file in its binary folder. In my case, I have installed ActiveMQ on Windows XP (I know, we are in 2012, but this ancient operating system is still alive and kicking) in a folder named C:\dev\apache-activemq-5.5.1, and I run its broker executing from a shell in that folder the command

bin\activemq

As a feedback I get some log information including a notification of the JVM used, and on the started ActiveMQ components and subsystems. For the sake of testing the installation, the two most interesting lines are:

INFO | Listening for connections at: (your machine):61616
...
INFO | ActiveMQ Console at http://0.0.0.0:8161/admin

Whenever you want to check if the connection is still alive, you can run netstat, as I did here:

netstat -na|find "61616"
 TCP    0.0.0.0:61616          0.0.0.0:0              LISTENING

Meaning: the port 61616 on localhost is listening for a TCP connection. All is running as expected.

Besides, we can access the ActiveMQ console from our favorite browser at the http://localhost:8161/admin address, and see there a number of administrative information on the broker.

Go to the full post

ActiveMQ 5.5 and SLF4J 1.6

Working on a simple Hello World example for ActiveMQ, I bumped in a conflict between this Apache Message-Oriented-Middleware (MOM) and the SLF4J logging system. It is nothing serious, but I guess it is worth to enter in some detail on this issue.

SLF4J is the used as logger by ActiveMQ. Unfortunately, still in version 5.5, the SLF4J bundled version is 1.5, that's a pity, because starting from SLF4J version 1.6 if you place no binder in your application classpath, the NOP logger is assumed. The effect is that all your log goes to a logical respective of /dev/null, as to say, it disappears in thin air. That's no fun, but better than the behavior of 1.5: crashing miserably with an error like this:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for
 further details.
Exception in thread "main" java.lang.NoClassDefFoundError: 
    org/slf4j/impl/StaticLoggerBinder
        at org.slf4j.LoggerFactory.getSingleton(LoggerFactory.java:230)
...

So, you really have to plug in a binder. I already had at hand a 1.6 plugin, I tried to used it, but I got another error:

SLF4J: The requested version 1.6 by your slf4j binding is not compatible
 with [1.5.5, 1.5.6, 1.5.7, 1.5.8, 1.5.9, 1.5.10, 1.5.11]

No compatibily.

There are a couple of solution to this issue. Or you use a plugin for that specific version, or you put the SLF4J API jar of your choice in your classpath before the ActiveMQ full jar.

I opted for the second choice, and my classpath is now referring to these jar - in this order:

• slf4j-api-1.6.4.jar
• activemq-all-5.5.1.jar
• slf4j-simple-1.6.4.jar

Actually, the SLF4J plugin could be in any place, but it is crucial that the API SLF4J jar is before the ActiveMQ one.

Go to the full post

Improved RPC by JSON

If the data exchange is meant to use only strings, the basic RPC support provided by RabbitMQ is more than adequate, and the StringRpcServer class makes it even easier. But what if we want to use other data types? The rabbit answer to this question is JSON-RPC. This RPC protocol based on JSON is implemented in a couple of classes, JsonRpcServer and JsonRpcClient, that take care of the low leve details and let us free to use RPC in a more natural way.

To get acquainted to it, I went through the JSON-RPC example provided in the test folder of the source RabbitMQ distribution, package com.rabbitmq.examples, files HelloJsonService.java, HelloJsonClient.java, and HelloJsonServer.java. I have reworked it and you can see my commented version in this post, full Java source code is available on github.

The service

The JSON-RPC interface between client and server is represented by a service, that exposes to the client which methods are available on the server:

public interface JsonSvc {
    String greeting(String name);
    int sum(List<Integer> values);
}

This interface is going to be implemented by a class, I called it MyJsonSvc, used internally by the RPC server.

The client

In the client, the service is used to provide access to the server functionality, as shown here:

// ...
JsonRpcClient client = new JsonRpcClient(channel, "", QUEUE_NAME, RPC_TIMEOUT_ONE_SECOND); // 1
JsonSvc service = (JsonSvc)client.createProxy(JsonSvc.class); // 2

System.out.println(service.greeting("Rabbit")); // 3

List<Integer> numbers = new ArrayList<>();
numbers.add(1);
numbers.add(2);
numbers.add(3);
System.out.println("1 + 2 + 3 = " + service.sum(numbers));
// ...
client.publish(null, null); // 3

1. A JSON-RPC client is created, specifying a channel, a queue, and also an optional timeout in milliseconds.
2. This is the core of the example, the rabbit JSON-RPC client creates a proxy for the passed interface, then we can use it in our client as shown below.
3. We could still use the client as a plain RpcClient client, bypassing the JSON layer. Here we are sending an empty message with no associated properties.

The server

Implementing the JSON-RPC capabilities in the server is straightforward:

// ...
channel.queueDeclare(QUEUE_NAME, false, false, false, null);
JsonRpcServer server = new MyRpcServer(channel, QUEUE_NAME, JsonSvc.class, new MyJsonSvc()); // 1

System.out.println("JSON-RPC server is up.");
server.mainloop(); // 2
// ...

1. We create a JsonRpcServer object specifying a service on which it would operate, and the interface that it should use to access it.
2. Then we start looping on it.

You have surely noticed in the code here above that I didn't create a plain JsonRpcServer, but a mysterious MyRpcServer. I did that because I wrote the client to be a bit smarter than usual, calling not only the JsonSvc methods, but also sending a plain (empty) message. To give the server a way to manage it as expected (in this case an empty message is seen as a signal to terminate the server run), I have to add functionality to the JsonRpcServer, as we already have seen for StringRpcServer. Actually, all we need is just reimplementing handleCast(), so that we can react correctly to an empty message:

// ...
private class MyRpcServer extends JsonRpcServer {
    // ...
    @Override
    public void handleCast(byte[] requestBody)
    {
        if(requestBody.length == 0) {
            System.out.println("Empty message, terminating.");
            terminateMainloop();
        }
    }
}

Go to the full post

RPC for strings

Writing a RabbitMQ RPC (Remote Procedure Call) application is not difficult, still we have to deal with a few internal details that could easily be hidden in a utility class. Actually, Rabbit gives us two hierarchies designed for that, based on com.rabbitmq.client.RpcServer and com.rabbitmq.client.RpcClient.

RpcClient is flexible enough to be used directly in most cases, while the RpcSever has to be adapted to the effective application requirements. The example of this post is based on the HelloClient - HelloServer classes included in the source RabbitMQ distribution (you should find them in the test directory, in the com.rabbitmq.examples package). The Java source code for my variation is available on github.

The client sends a string message to the server, and receives back a response. It could also send an empty message, that would be interpreted by the server as a command to shutdown, and in this case no answer is expected.

We delegates to RpcClient all the low level details, and this is the slim resulting code:

// ...
RpcClient service = new RpcClient(channel, "", QUEUE_NAME); // 1

if(arg.equalsIgnoreCase("x")) { // 2
    System.out.println("Terminating server");
    service.publish(null, null);
}
else {
    String result = service.stringCall(arg); // 3
    System.out.println(result);
}
// ...

1. Instantiate an RPC client that is going to work on the specified channel and queue. The second parameter, not used here, is reserved for the exchange; in that case the third parameter would be used for the routing key.
2. If the user pass an x (upper or lowercase) we interpret it as a request to shut the server down. In this case we the raw RpcClient.publish() method, that expects two parameter, the properties associated to the message, and the message itself, as an array of bytes. In this case both of them are null.
3. Usually we rely on RpcClient.stringCall(), that wraps a complete exchange with the server. The passed message is sent, and when the reply arrives is passed back to the caller.

The server it a bit more complicated. Firstly we need to specialize the StringRpcServer, we could create an anonymous inner class on the fly, but here I wrote it as a plain inner class, aiming to readability:

private class MyRpcServer extends StringRpcServer {
    public MyRpcServer(Channel channel, String queueName) throws IOException {
        super(channel, queueName);
    }

    @Override
    public String handleStringCall(String request) { // 1
        System.out.println("Input: " + request);
        return "Hello, " + request + "!";
    }

    @Override
    public void handleCast(byte[] requestBody) // 2
    {
        if(requestBody.length == 0) {
            System.out.println("Empty message, terminating.");
            terminateMainloop(); // 3
        }
    }
}

1. The standard case, a string is received from the client, here we use it to generate the result, and we send it back to the caller.
2. Less commonly, we want to consume the message received from the client without sending back anything.
3. This is the method to call to terminate the looping on the RPC server, exactly what we need here.

The server itself instantiates its RPC server object and let it looping on the messages arriving from the clients:

// ...
channel.queueDeclare(QUEUE_NAME, false, false, false, null);

StringRpcServer server = new MyRpcServer(channel, QUEUE_NAME);
System.out.println("RPC server is up");
server.mainloop();
// ...

RpcServer.mainLoop() loops indefinitely on RpcServer.processRequest() that checks if both correlationId and replyTo are set among the request properties. If so, RpcServer.handleCall() is called, and its returned value is published back to specified queue. Otherwise, RpcServer.handleCast() is called.

Go to the full post

Fibonacci RPC client

In this RPC (remote procedure call) RabbitMQ Fibonacci application, once written the server component, we are almost done.

The client simply has to send a message to the server, and just sits there waiting for the answer. The variation is that I wrote such a powerful client that could even kill the server. To do that it just has to send an empty message. This is not a very safe behavior, but it is handy to show how to manage uncommon messages, at least in the RPC by messaging pattern, where the client doesn't wait for an answer.

Here is the most interesting part of the client code, you could also have a look to the source code for the complete Java class, that contains both server and client functionality:

// ...
if(arg.equalsIgnoreCase("x")) {
    System.out.println("Terminating Fibonacci server");
    channel.basicPublish("", RPC_QUEUE_NAME, null, null); // 1
}
else {
    String queueName = channel.queueDeclare().getQueue();
    QueueingConsumer consumer = new QueueingConsumer(channel);
    channel.basicConsume(queueName, true, consumer); // 2

    String id = UUID.randomUUID().toString(); // 3
    BasicProperties props = new BasicProperties.Builder().correlationId(id).replyTo(queueName).build(); // 4
    channel.basicPublish("", RPC_QUEUE_NAME, props, arg.getBytes()); // 5
    System.out.println("Reply to " + queueName + ", " + id);

    System.out.print("fibonacci(" + arg + ") = ");
    while (true) { // 6
        QueueingConsumer.Delivery delivery = consumer.nextDelivery();
        if (delivery.getProperties().getCorrelationId().equals(id)) { // 7
            System.out.println(new String(delivery.getBody())); // 8
            break;
        }
    }
}
// ...

1. This is the killer empty message for the RPC Fibonacci server.
2. An implicit acknowledgment is enough in this case.
3. As explained talking about the server, a unique correlation id is used to ensure the matching between request and reply. Here we generate it using the UUID facility.
4. The correlation id and the name for the specific queue created exclusively for this client is passed to the server in the properties associated to the message.
5. Message and properties are sent.
6. We loop indefinitely, discarding all the messages that are not relevant.
7. That's it! The correlation id matches.
8. In the message body we find the reply to our question, and we can terminate.

Go to the full post

Fibonacci RPC server

As a first example of RabbitMQ RPC (remote procedure call) application, I have studied the Fibonacci generator provided in the RabbitMQ official tutorial. Here you can find my version of the rabbit Fibonacci server, the rabbit Fibonacci client is in the next post.

I put both client and server in the same class, and you could get the complete Java source code from github.

The server waits indefinitely on a queue, named "rpc_queue", for inputs to be used to calculate a Fibonacci number. It consumes just a message at time, and sends an explicit acknowledgment to the broker when it completes the elaboration. All of this is not very useful here, but it could be seen as a hint for a future redesign where more Fibonacci calculators are available to the huge population of clients requesting this awesome service.

The server accepts only input in the range MIN_INPUT .. MAX_INPUT, and interprets an empty message as a terminator. All the other possible messages are rejected.

Sending the result to the client is a bit tricky. We need the client to tell the server on which queue it is waiting for this answer, and this is not enough. Since a client could send more than one request, at least theoretically, we need to get and send back an identifier, that would correlate the request to the response. This is done putting these values in a properties object associated to the message.

This is the most interesting part of the resulting code:

// ...
try {
    // ...

    channel.queueDeclare(RPC_QUEUE_NAME, false, false, false, null); // 1
    channel.basicQos(1); // 2

    QueueingConsumer consumer = new QueueingConsumer(channel);
    channel.basicConsume(RPC_QUEUE_NAME, false, consumer); // 3

    System.out.println("RPC Fibonacci calculator is ready");

    boolean terminator = false;
    while (true) {
        String response = ""; // 4

        QueueingConsumer.Delivery delivery = consumer.nextDelivery(); // 5

        try {
            String message = new String(delivery.getBody());
            if(message.isEmpty()) { // 6
                System.out.println("Empty message, terminating");
                terminator = true;
                break;
            }

            int n = Integer.parseInt(message);
            System.out.println("Calculating fibonacci(" + message + ")");
            if(n < MIN_INPUT || n > MAX_INPUT)
                response = "N/A";
            else
                response += fibonacci(n); // 7
        }
        catch (Exception e){
            e.printStackTrace();
        }
        finally {
            if(!terminator) { // 8
                BasicProperties bp = delivery.getProperties(); // 9
                String corrId = bp.getCorrelationId(); // 10
                String replyQueue = bp.getReplyTo(); // 11
                System.out.println("Replying to " + replyQueue + ", " + corrId);
                
                BasicProperties replyProps = new BasicProperties.Builder().correlationId(corrId).build();
                channel.basicPublish("", replyQueue, replyProps, response.getBytes()); // 12
            }
            channel.basicAck(delivery.getEnvelope().getDeliveryTag(), false); // 13
        }
    }
}
catch  (Exception e) {
    e.printStackTrace();
}
finally {
    try{ if(connection != null) connection.close(); } catch(IOException e) {}
}

1. The queue used by this application only.
2. No prefetch is done, just one message is picked up at time.
3. Explicit acknowledgment when the output is generated.
4. It is handy to initialize the response to an empty string, so that we can concatenate the resulting Fibonacci number to it.
5. Wait a client's request.
6. Special case, the client asks the server to shutdown.
7. Call the actual Fibonacci generator.
8. Usually we send back a message to the caller, only in case of termination there is no need of sending back anything.
9. In the delivery we have an object where the properties of the message are stored.
10. We use the correlation id the identify uniquely a request coming from a client
11. In the reply to field we expect to see the queue where the client wants us to put the result.
12. This is the main line in the post. We publish the response to the queue passed by the client, specifying in the properties the correlation id of its request.
13. Only now we can say to the broker it could get rid of the message we read on (5).

Go to the full post

RabbitMQ message acknowledgment

To understand better how it works, could be useful compare the behavior of a very simple rabbit consumer when the acknowledgment flag is set to true or false in the Channel.basicConsume() call.

I have written a stripped down example where the producer puts a message in a queue and then quits. The consumer works with automatic or explicit acknowledgment accordingly to an input value is provided to it. Looking at the code, we can see how the changes are very localized. We specify that the QueueingConsumer for the channel/queue is in one mode or the other, and then, if an explicit ack is required, we give it when the job is done:

// ...
QueueingConsumer consumer = new QueueingConsumer(channel);
channel.basicConsume(QUEUE_NAME, autoAck, consumer); // 1

QueueingConsumer.Delivery delivery = consumer.nextDelivery();
// ...

if(!autoAck) { // 2
    channel.basicAck(delivery.getEnvelope().getDeliveryTag(), false);
    // ...
}

1. Here we specify if an handshake is required (autoAck sets to false) or if we rely on the standard auto-acknowledging RabbitMQ policy.
2. When we are done with the message, and if we are not in auto-acknowledgment mode, we give our explicit acknowledgment to the rabbit broker.

The complete Java code is on github.

Go to the full post

Always close a RabbitMQ connection

I see now that in the previous rabbit examples I have missed to ensure that a connection would always be closed at the end of the program. The result is that a rabbit process, under some specific circumstance, could unhappily hang until an interrupt terminates its sad life. Remember not to do the same mistake in your production code.

The typical (bad) code is something like:

// ...
try {
    Connection connection = factory.newConnection(); // 1
    Channel channel = connection.createChannel();

    // ...

    connection.close(); // 2 !! BAD !!
}
catch(IOException e) {
    // ...
}

1. A connection is created and open
2. The connection is closed

The issue is that in case of an exception after (1) but before (2), the cleanup connection code is not called, since the control jumps directly to the catch section.

The solution is pretty easy, we should add a finally clause, and clean the connection there:

// ...
try {
    Connection connection = factory.newConnection();
    // ...
    // 1
}
catch(IOException e) {
    // ...
}
finally { // 2
    try{
        if(connection != null) connection.close();
    } catch(IOException e) {} // 3
}

1. The connection cleanup is not done here anymore.
2. The finally section is always execute, whatever happens above.
3. For what said in (2), we should ensure the connection has been actually been instantiate, before calling its close() method. Besides, we have to try-catch it, since it could throws an IO exception.

For tiny test applications, this is not such an important remark. It is probably better stressing other points and leaving out this detail. But in real code, forgetting to adequately protect the connection cleanup procedure could lead to serious problems.

Go to the full post

Passive or active queues?

In the previous RabbitMQ examples I have written, I have always declared queues calling Channel.queueDeclare(). But it is also possible to do it calling Channel.queueDeclarePassive(). As you could easily guess, the first method is for an active queue declaration, and the second for a passive one. The point of this post is: what a passive queue is and how to choose between declaring a queue as passive or active.

If you play with queue setting, one day or another you will end up getting an exception, due to the fact that once a queue is created, you can't access it specifying a different setting:

java.io.IOException
    at com.rabbitmq.client.impl.AMQChannel.wrap(AMQChannel.java:106)
    at com.rabbitmq.client.impl.AMQChannel.wrap(AMQChannel.java:102)
    at com.rabbitmq.client.impl.AMQChannel.exnWrappingRpc(AMQChannel.java:124)
...    
Caused by: com.rabbitmq.client.ShutdownSignalException: channel error;
 reason: {#method<channel.close>(reply-code=406, reply-text=PRECONDITION_FAILED - 
 parameters for queue 'ack' in vhost '/' not equivalent, class-id=50, method-id=10),
 null, "[B@19d3b3a"}
    at com.rabbitmq.utility.ValueOrException.getValue(ValueOrException.java:67)
...

In this case I tried to access a queue called "ack", declared in the default virtual host, passing the parameter "autodelete" set to true, where it was created with false.

When this happens, you could have a look to the RabbitMQ administrator, specifically in the Queues tab, to get all the available information on your queue.

But back to the main theme of the post.

If a queue is declared passively, RabbitMQ assumes it already exists, and we just want to establish a connection to it. What if you call Channel.queueDeclarePassive() and the queue is not there? I guess you already know the answer, you get a fat exception:

java.io.IOException
    at com.rabbitmq.client.impl.AMQChannel.wrap(AMQChannel.java:106)
    at com.rabbitmq.client.impl.AMQChannel.wrap(AMQChannel.java:102)
    at com.rabbitmq.client.impl.AMQChannel.exnWrappingRpc(AMQChannel.java:124)
...
Caused by: com.rabbitmq.client.ShutdownSignalException: channel error;
 reason: {#method<channel.close>(reply-code=404, reply-text=NOT_FOUND -
 no queue 'ack' in vhost '/', class-id=50, method-id=10), null, "[B@140fee"}
    at com.rabbitmq.utility.ValueOrException.getValue(ValueOrException.java:67)
...

Close to the exception shown above, but here the reply text is a NOT_FOUND that shows clearly what the problem is. Rabbit was running happily assuming the queue was there, but actually it wasn't.

So, we use a passive queue declare when we can safely assume the queue is already there, and its non-existence would considered an exceptional, almost catastrophic, event.

The safer active queue declaration has the obvious downside of being more expensive, and requiring the user to provide the setting each time a queue declaration is issued. An hybrid approach (active on the server, passive on the client) could make sense if the application has a rigid protocol ensuring that a component would always start before the other(s).

Go to the full post

ConnectionFactory setting by URI

In the previous post we set properties on a RabbitMQ ConnectionFactory constructing an object and then calling all the relevant setter on it. Sometimes it is handier to directly create a ConnectionFactory object passing an URI in its constructor.

We can use both a standard Java URI object, as defined in the java.net package, or a String in the expected AMQP format. Let's say that we already have the URI as a string, and we can pass it to our rabbit application, we can use this information directly:

private ConnectionFactory getFactory(String uri) throws IOException { // 1
    ConnectionFactory factory = new ConnectionFactory();
    try {
        factory.setUri(uri); // 2
    } catch (URISyntaxException|NoSuchAlgorithmException|KeyManagementException e) {
        throw new IOException("Can't set connection factory URI", e); // 3
    }
    return factory;
}

1. We expect uri to be something like "amqp://user:password@127.0.0.1:6391/test", where "test" is the name of our virtual host. We are not forced to specify all parts in the AMQP URI, but the host name must be passed if at least one property among username, password, or port is given.
2. The passed URI is carefully checked, and three different exceptions could be thrown to acknowledge a specific error.
3. The error handling here is very loose, any passible exception is converted in an IOException and forwarded to the caller. The reason for this is just keeping the code simple, since I don't care much of having such detailed information on the reason for failure. This shouldn't be an optimal choice for production code.

Producer and consumer should be slightly changed to try-catch also on this method:

public void consumer(String uri) {
    try {
        ConnectionFactory factory = getFactory(uri);
        Connection connection = factory.newConnection();
        
        // ...

        connection.close();
    }
    catch (IOException|InterruptedException e) {
        e.printStackTrace();
    }
}

Go to the full post