March 29, 2015

Software artifact management with code generation


In this post, I’d like to express my opinion and present what I learnt as “best practices” through my experience when it comes to managing software project artifacts, and strategies for generating file types out of different types.

Throughout the software development process, artifacts of different types are created. Some become part of the final product, while others serve informational or organizational purposes during the process only; they typically don’t get delivered as part of the product.

Creating an artifact is always time-consuming. Depending on the artifact type and the amount of information it stores, this time can vary considerably. Thus one should aim to only create a minimum of artifacts and to use whatever artifact type is most suited to store the information one wants to keep.

As with other processes in software engineering, automation can and should be used to increase productivity when generating artifacts. Automating artifact generation both increases productivity and decreases probability of error in the process. The simplest strategy clearly is to “generate everything”. But if we take a closer look at the differences between software development artifacts, we can come up with some more detailed best practices for artifact generation.

I will here specifically address the two biggest challenges with artifact generation: its implementation and artifact synchronization.

Know your artifacts

Artifacts can be distinguished by type and function.

Rough categories can be used to differ various types: Text documents (e.g. Word documents), source code (e.g. Java source code files), structured information (e.g. XML files), compiled files (e.g. JAR archives). We shall come back to these different types later.

More important is the distinction by function into the two categories of “human artifacts” and “machine artifacts”.
  • A human artifact is actively worked on by humans. Its creation involves a creative thinking process which cannot be automated by a machine.
  • A machine artifact is basically of no use for humans, but for technical reasons, its existence is required by the technology / framework the project is built upon.

Opportunities for automated artifact generation

There are a couple of variations on how human and machine artifacts can be connected with each other:

No auto-generation

A human artifact is also a machine artifact and vice versa. This is the typical situation of “no automated artifact generation at all”: an artifact is created (and, optionally, worked with) by humans and interpreted by the machine.

This is quite an unlucky situation for both humans and machines: Unless very trivially encoded, artifacts are typically either very hard to read for humans or machines, and there are only a few simple formats which might satisfy both. However, this is quite a common situation. Most prominent examples include XML, HTML, CSS, even source code (as it’s interpreted by the IDE for syntax highlighting and the like).

This is typically a great opportunity to separate that artifact into one which is created by humans, and another, generated from the first, which is then interpreted by the machine, thus making both parties happy, as shown in the next paragraph.

Human-to-machine-generation

This is the most straightforward application of artifact generation: An artifact is created by humans, and then converted into a format which fits the machine’s needs to interpret it. The most typical example here is source code (as it’s compiled to bytecode / machine code by the compiler).

Note that in this situation, the human artifacts stays the actively maintained one. It is thus easy to simply re-create and overwrite the machine artifact created from a former version of the human artifact.

Machine-to-human-generation

This is an anti-pattern you want to avoid. Typically, extracting information from a machine-artifact into human-readably form is hard, and automating it can also be a challenge. A typical example is a hex code file you have to search for information, or an error log.

However, if you are in this situation, you really should try to automate it unless reading the file format is trivial. Typically, there are existing “viewers” for common machine code artifacts available. If there aren’t, creating a viewer or a machine-to-human-generator once will on the long run be more efficient that manually interpret the file every time. Here you can take advantage of the fact that machine files follow clearly defined grammar rules which you can use to build your generator.

Circles

This is what you want to avoid at all costs. It’s typically the outcome of a poor artifact management strategy. This situation typically starts out with a human artifact being converted into a machine artifact, but then that latter either is edited directly by humans (thus turned into a human artifact) or used as a base to generate other human artifacts. In this situation, synchronization is no more assured, which may form a considerable source for errors.

As a typical example, take this (real-world) situation:
  1. A web service is described in a Word document after negotiations with third party software vendors, and handed over to the engineers to implement it. They implement the web service, based on the information in the Word document (a non-automated human-to-machine-generation), the outcome of which is a web service descriptor (e.g. a WSDL file).
  2. However, as implementation proceeds, slight changes are directly incorporated into the WSDL file. After that, the team is forced to extract the updated service contract from the WSDL file into a human-readable Word file (a non-automated machine-to-human-generation) in order to inform the third party software vendors about the final implementation of the web service.
In this situation, information is brought back from the generated artifact in the originally generating artifact (or even into a third one). Without having one clear “primary” artifacts, changes are hard to synchronize, and introducing automation is typically hard if not impossible, if it involves artifact types which clearly target a human audience, such as Word files.

Here, the better strategy is to break up the circle and instead transform it into a chain:
  1. The Word file description of the web service is actually turned into a WSDL file (which typically happens manually). After this point, the original Word document is abandoned and not updated any further.
  2. As the web service is then edited by the engineers, it actually becomes another semi-human-semi-machine artifact. It is now the “primary” artifact in the process.
  3. As the WSDL is tolerably readable by the engineers, but not by the third party software vendors, it must be turned into a “truly” human-readable format. Note that even though this format must be agreed on by all the parties involved, it must not match the original Word file format. In this situation, I would suggest choosing a format for which generation out of the WSDL file can be automated, e.g. using a WSDL-to-HTML generator. Note that here, the WSDL file stays the “primary” artifact, and all subsequent updates would happen there, with the possibility to re-generate the “human-readable” (e.g. HTML) outcome at any time.

Even better would be a chain such as this:

Here, the Word file is turned into another human/engineers-readable file from which both the machine file (WSDL) and the final human-readable service description (HTML) can be generated.

However, this will typically require a custom-made file generator which will be discussed below.

Choosing the right file type

When it comes to choosing the right file type for storing information, the choice is by its nature much freer for “human” files as the type of “machine” files will be preset be the technology / framework in use, thus there is only an indirect choice by using the right technology. Hence, do not underestimate this impact during technology assessment!

Keep it simple

For human files, on the other hand, we can really choose the file type which best suits our needs:
  • It has the most simple format.
  • It has the most insignificant overhead, i.e. we just need to provide actual information with the least amount of meta-data.
  • If there’s the need to convert from / to machine artifacts, or to use it both as a human and machine artifact, conversion should be easy and easily automatable.
Note that the first two points actually could be outweighed by a more “chatty” file format with great tool support which automates all the boilerplate meta-data generation. Keep in mind though, that this will make you dependent on that tool. If you don’t have it or if it’s complicated to apply it in a certain situation (e.g. when browsing plain request / response log messages in a server console) you might still face the full complexity of the original file format.

As a rule of thumb, however, simplicity is key: The file really should only include the amount of meta-data which is absolutely critical for the job.

That’s why I would prefer e.g. a Java .properties file over a JSON file, and a JSON file over an XML file.

In certain situations, the best strategy might even be to build your own file format. This brings two major advantages:
  • You can keep the format as simple and as concise as you need it.
  • You can generate it into any other format of your choice as long as you create the generator yourself.
Using some fairly modern tools, creating a file converter / code generator for your own “domain specific language” (DSL) is quite simple. For example, the Groovy programming language provides a wide range of tools extending the Java language for DSL code generation. I will probably illustrate modern code generation practices in a future blog post…

Thus it’s really your choice, based on comparing effort and benefit. Take for example a quite complicated XML format such as WSDL. Actual information in that file is maybe lower than 25%. The rest is code duplication and boilerplate noise. If you had a custom tool that would allow you to just input the information and generate the rest for you, productivity would be drastically increased, and probability of errors would be lowered.

Keep it the same

Another factor to keep in mind is that you want to work with as few different file format types as possible, in particular when it comes to the most complex ones. In an ideal world, you would even have only one file format, and generate the rest out of it. Of course, this is not realistic.

A good strategy is to identify a small set of “primary file formats” you want to work with, and try to generate all the other formats from them. These should typically be the most simple file formats, or the ones your team is most familiar with.

If we take the WSDL file type as the example again, in a Java project, a possible strategy would be to use a Java-to-WSDL-generator: As all your engineers are fluent in the Java language, why introduce another language instead of letting your engineers stick to what they know best?

Choosing the right generator

Of course, the choice of an automated generator / converter depends on the file type chosen, thus the same rules apply as presented in the last section:
  • Keep it simple: Consider writing your own generator if any existing one leaves you with a considerable amount of boilerplate code.
  • Keep it the same: A generator should translate from a very simple, familiar file format to a more complex one, never the other way around. Thus write your source file in the language your are familiar with, and translate it to whatever “foreign language” the machine needs.
Key is here to use the right tool for the job. You don’t want to introduce a generator which is more intricate to work with than the actual file it would generate! Thus, some requirements for any code generator / converter are:
  • It does introduce the least amount of complexity to your tool chain.
  • It scales with your requirements, e.g it is easily extendable to support more output options.
Again, in certain situations, it may be your best bet to opt for a custom file generator which you build yourself.

Let’s take the WSDL to HTML example again. Yes, there are quite a few tools which provide WSDL-to-HTML conversion (or more generally speaking, XML-to-HTML conversion, e.g. based on XSLT), but most of them are probably rather complex to use, offer limited customization, require license payments or / and are closed source. In this scenario, you may as well opt for a custom solution considering both WSDL / XML parsing and HTML generation can be done pretty easily with some modern programming languages, providing you with full control over the actual conversion process. Again, see Groovy’s support for XML /  HTML processing as an example.

Considering aspects such as ease of development and maintainability, I would thus prefer e.g. a Groovy-based solution over XSTL.

Enabling Continuous Delivery

Integrating your (custom) generator into your project build tool chain will even allow you to significantly speed up and unify your deployment process, which is, amongst other automation techniques, a key ingredient for Continuous Delivery best practices.

Conclusion

Writing complex code artifacts in unfamiliar code formats is an exhausting, error-prone task. Clever engineers will do what they are best at: write code to automate file conversion. As in other software engineering disciples such as testing, automation done right will increase productivity and robustness when it comes to project artifacts management.

Investing in a custom-made file generator may be worth while by further increasing everyday productivity, especially as the costs for creating custom DSL code generators are quite low using modern technology and tools.

Last but not least, incorporating code generation in your deployment pipeline and thus tearing out manual translation steps is key when you want to move towards Continuous Delivery.

As always, please share your thoughts on this topic in the comments section below! Do you agree with my pro-“code generation” opinion? I would be particularly interested in hearing your most memorable experience when relying on or skipping code generation.

March 22, 2015

Groovy by example: Writing a builder (part 2 of 2)


This article contains an in-depth study of Groovy’s BuilderSupport class and a tutorial to create custom builder classes as well as some associated best-practices I found useful. Make sure to check out part 1 first.

Implementing BuilderSupport

With what we know about BuilderSupport now, we can implement a basic builder for our household model:
class HouseholdBuilder extends BuilderSupport {
    private static final String MODEL_PACKAGE = "ch.codebulb.groovybyexample.buildersupport.model"
    
    private static final Map SUPPORTED_MODELS = [
        build: ArrayList,
    ].withDefault {
        Class.forName("${MODEL_PACKAGE}.${it.capitalize()}")
    }
    
    @Override
    public void setParent(Object parent, Object child) {
        if (parent == child) return
        parent << child
    }
    
    @Override
    public Object createNode(Object name) {
        return createNode(name, null, null);
    }

    @Override
    public Object createNode(Object name, Object value) {
        return createNode(name, null, value);
    }

    @Override
    public Object createNode(Object name, Map attrs) {
        return createNode(name, attrs, null);
    }

    @Override
    public Object createNode(Object name, Map attrs, Object value) {
        try {
            def instance
            if (!value) {
                instance = SUPPORTED_MODELS[name].newInstance()
            }
            else {
                instance = SUPPORTED_MODELS[name].newInstance(value)
            }
            attrs.each {k, v -> instance."$k" = v}
            return instance
        }
        catch (ClassNotFoundException ex) {
            if (value && !attrs) {
                current."$name" = value
                return current
            }
            else {
                throw ex
            }
        }
    }
}

We can then invoke and test it like so:
assert [createDemoHousehold()] == new HouseholdBuilder().build {
    household(address: "main street 42") {
        car("VW", price: 15000)
        room {
            name("living room")
            furniture(name: "TV", price: 2000)
            furniture(name: "sofa", price: 1000)
        }
    }
}

In the builder implementation, I used a reflection-based dynamic solution to retrieve the class we want to create a node instance of, which I will presently explain.

Note that this solution enables the model classes to be pure POJOs; the “container” models must provide a leftShift(…) method, but that’s all.

createNode(…)

As in the example code, you will typically implement only one of the createNode(…) methods and implement the others as pure delegates.

In the actual implementation, you will implement one or both of these use cases:
  • The builder method call should add a new node, as in furniture(name: "TV", price: 2000);
  • The builder method call should set a property of the current node, as in name("living room").
Hence, you will typically implement createNode(…) as a giant switch-case where the name argument is the switch candidate: Based on the name, you will then either create a new node of the appropriate class, or call the appropriate setter on the current node.

I implemented a dynamic solution here to serve both cases without having to specify the individual case branches. This will allow to use new or updated model classes immediately, without changes to the builder (open/closed principle compliant).

First of all, I specified all SUPPORTED_MODELS classes to be either an ArrayList or one of the classes in my model package. I associated the ArrayList implementation explicitly with the build builder call (I will explain this in the “best practices” section below), and through the withDefault(…) GDK method, I let the builder choose a model class at runtime based on the method name for any other builder calls.

In createNode(…) I also distinguish whether a value argument has been provided or not. If so, we assume this argument to be the one constructor call argument. The attrs arguments are used to set the properties of the newly-created node instance, as if it were a Map constructor call.

Finally I have to cover the second use case where createNode(…) should not create a new instance, but just update a property on current. Here, I can detect this case by finding that no class for the given node name has been found. Then, I use the value argument to set the property in question.

Note that in this latter case, I access and modify the current property directly. This should be considered a hack. Because BuilderSupport updates the current property automatically, we would normally not access this property ourselves. But this technique comes in handy if we want to override the BuilderSupport default – that any createNode(…) call would always result in the creation of a new property node. Note also that in this special case, I return the altered current node.

setParent(…)

The setParent(…) method should really not be more than a mere delegate to either the child setting its parent, or the parent setting its child. If you use a swich/case here, you violate the open/closed principle. Note that your model classes must thus provide a common (implicit) interface; in this example, it’s the leftShift(…) method.

Because of how I implemented the use case of createNode(…) actually altering a property of the current node instead of creating a new node, I must here handle the special case that the parent node is again returned as the child node. In this case, of course, I don’t do anything.

Best practices and additional tricks

Use a containing collection

In most cases I found it useful to use the “outermost” builder method to build a List wrapper around whatever model is built by the builder. That’s why in the example, build() returns a List. This makes it easy to use the builder for building an arbitrary number of models. Otherwise you would have to invoke the builder multiple times. So you can now do:
new HouseholdBuilder().build {
    household(address: "main street 42")
    household(address: "main street 44")
}

Without that containing collection, you would have to write:
new HouseholdBuilder().household(address: "main street 42")
new HouseholdBuilder().household(address: "main street 44")

Because the household(…) method returns the node instance it created, you cannot chain another household(…) method – it would be interpreted as a method call on the Household object returned.

Use a static factory method

We can use a static factory method as a shorthand for instantiating a new builder instance, like so:
HouseholdBuilderPlus.build { household(address: "main street 42") }
A static method similar to this one will do the trick:
public static List build(Closure closure) {
    return new HouseholdBuilderPlus().invokeMethod("build", closure)
}

Note that we used the dynamic invokeMethod(…) call here only because the static and non-static “build” methods have signature collisions, and a call to the method would simply end in a StackOverflowError. This is not required if you name your static method different than any builder method.

Use convenience methods

A method invocation to a builder typically gets delegated to the appropriate createNode(…) method. However, we can always override this behavior by simply adding additional methods to our builder class. This can come in handy, e.g. to provide “templates” for frequently used structures:
HouseholdBuilderPlus.build {
    household(address: "main street 42") {
        livingRoom {
            furniture(name: "TV2", price: 2000)
        }
    }
}

Here, for example, we use a “living room” template we defined as a method in our builder:
public livingRoom(String roomName="living room", Closure closure) {
    room {
        name(roomName)
        furniture(name: "TV", price: 2000)
        furniture(name: "sofa", price: 1000)
        closure?.call()
    }
}

Note that we can even offer a customizable template e.g. by accepting method arguments or by accepting and invoking a closure parameter, just as we did here.

Use Groovy code

Before defining tons of convenience methods, keep in mind that your builder DSL still is 100% valid Groovy code. This means that the caller can use arbitrary Groovy code structures, such as variable access, conditionals and loops inside the builder syntax. Clever use of these possibilities should reduce the need for templates. For example:
HouseholdBuilderPlus.build {
    household(address: "main street 42") {
        2. times { car("VW", price: 15000) }
    }
}

Use Auto-to-String

A convenient addition to our builder DSL would be that we don’t need to enclose Strings in opening and closing quotes. Using some meta-programming, this is actually quite easy. If the caller would just omit the quotes without further actions, Groovy would throw an exception because it would treat the String as the name of a property of the builder which it cannot resolve. Luckily, we have the propertyMissing(String) method which can override this behavior:
public String propertyMissing(String name) {
    // replace camelCase with "whitespace separated"
    name.replaceAll (/[A-Z](?=[a-z])/) {" ${it.toLowerCase()}"}
}

Now we can omit quotes for simple Strings (e.g. “living room”, “TV”, etc.):
HouseholdBuilderPlus.build {
    household(address: "main street 42") {
        car(VW, price: 15000)
        room {
            name(livingRoom)
            furniture(name: TV, price: 2000)
            furniture(name: sofa, price: 1000)
        }
    }
}

You should consider this option only if your builder DSL makes use of many single Strings. You should disable it while you debug your builder.

Use other dynamic features

By combining the power of the BuilderSupport implementation and Groovy’s meta-programming capabilities, you can build a truly dynamic DSL for your builder, just as we discussed it above for some example applications.

Using ObjectGraphBuilder

With ObjectGraphBuilder, Groovy features a similar highly dynamic builder to build object structures as we’ve implemented from scratch in the Implementing BuilderSupport section.

Building a simple structure of arbitrarily structured POJOs with ObjectGraphBuilder is as simple as:
new ObjectGraphBuilder(
    classLoader: this.class.classLoader,
    classNameResolver: "ch.codebulb.groovybyexample.buildersupport.model",
).household(address: "main street 42") {
    car(name: "VW", price: 15000)
    room(name: "living room") {
        furniture(name: "TV", price: 2000)
        furniture(name: "sofa", price: 1000)
    }
}
Note however that this builder doesn’t support “building” properties nor any other to the previously discussed more sophisticated techniques. However, you can of course base your own Builder implementation on ObjectGraphBuilder rather than on plain BuilderSupport and then build the previously discussed additional features as you need them! Also note that ObjectGraphBuilder itself comes with various options to customize builder behavior.

Conclusion

The internals of BuilderSupport are not obvious. As it’s one of Groovy’s most powerful feature for DSL creation, it’s worth a closer look. Once you grasped its concept, implementing basic custom builders with BuilderSupport is really straightforward whilst the tool will scale with your requirements thanks to its highly dynamic nature.

I hope this article will help you kick-start your own builder implementation. Feel free to check out the example source code at GitHub. Please let me know in the comments section below whether you found this article useful, and bring in any improvement suggestions.

Updated March 13, 2016: “Using ObjectGraphBuilder” section added.


Pages: 1 2

Groovy by example: Writing a builder (part 1 of 2)



This article contains an in-depth study of Groovy’s BuilderSupport class and a tutorial to create custom builder classes as well as some associated best-practices I found useful. Note: The example source code is available on GitHub.

Groovy has native syntactic support for builder structures – which really takes the builder design pattern to the next level. With its nested syntactic elements, a builder is perfect to describe any hierarchically built structure. For some typical use cases of structured models, Groovy provides out-of-the-box builder implementations. Examples include:
Apart from that, Groovy also offers a means to create your own builder. If you have your own structured business model, a builder might offer the perfect API to easily and concisely build instances of your model, e.g. in UnitTests. The only precondition is that your model is structured in a “1 parent to 1-n children” hierarchy.

In order to implement our own builder, we have to extend the BuilderSupport class. We simply have to implement some “business” methods of that class, and it will behave like a true structure builder at runtime. In this article, I will concentrate on how to design you own BuilderSupport sub-class with some stress on BuilderSupport’s internal mechanisms. This will allow us to take the Groovy builder syntax even further; we will also use some meta-programming to enhance our implementation.

The goal

For a simple use case let’s assume we have a model which represents a household, accompanied with insurance information:

  • a household has one or more rooms, and one or more cars associated with it;
  • a room has one or more pieces of furniture.
If we’d like to instantiate an example Household object, e.g. in a UnitTest, we would have to write a ridiculous amount of code in plain old Java; something like:
protected Household createDemoHousehold() {
    Household household = new Household("main street 42");
    household.getCars().add(new Car("VW", 15000));
    Room livingRoom = new Room("living room");
    livingRoom.getFurniture().add(new Furniture("TV", 2000));
    livingRoom.getFurniture().add(new Furniture("sofa", 1000));
    household.getRooms().add(livingRoom);
    return household;
}

Just for a household with a car and two pieces of furniture! This code is very hard to read. Luckily, with Groovy’s basic syntax, we can already lighten things a bit:
protected Household createDemoHousehold() {
    Household household = new Household("main street 42")
    household << new Car("VW", 15000)
    Room livingRoom = new Room("living room")
    livingRoom.furniture << new Furniture("TV", 2000)
    livingRoom.furniture << new Furniture("sofa", 1000)
    household.rooms << livingRoom
    return household
}

Now at least, the getter / setter chaos is gone, but this code still is very procedural whereas we’d like to describe a model in a declarative way, just as we would using some structured document format.

Here is what we’d like to end up with:
HouseholdBuilderPlus.build {
    household(address: "main street 42") {
        car(VW, price: 15000)
        room {
            name(livingRoom)
            furniture(name: TV, price: 2000)
            furniture(name: sofa, price: 1000)
        }
    }
}

We can do this in about a hundred lines of code with Groovy’s BuilderSupport.

The basics of BuilderSupport

First of all let’s think about how Groovy builders work. Obviously, there’s no magic involved. If we examine above builder structure we see that when thinking in Groovy syntax, it could be translated into nested method calls where the closure parameter of a method can contain other method calls. Thus we could actually implement a builder on our own by just handling this kind of closure nesting.

But we don’t want to re-invent the wheel here, thus we’ll use the BuilderSupport base class which cares about the handling of nested structures. We only need to provide two instructions by implementing two methods:
  • createNode(…): How to translate a builder method call to a node constructor invocation (this method comes in four overloaded flavors);
  • setParent(parent, child): How to associate a newly-created node to its surrounding parent node.

To understand this better, let’s see BuilderSupport’s behavior in action by implementing a simple demo builder:

class DemoBuilder extends BuilderSupport {
    @Override
    public void setParent(Object parent, Object child) {
        println "parent $parent << child $child"
    }
    
    @Override
    public Object createNode(Object name) {
       return createNode(name, null, null);
    }

    @Override
    public Object createNode(Object name, Object value) {
       return createNode(name, null, value);
    }

    @Override
    public Object createNode(Object name, Map attrs) {
       return createNode(name, attrs, null);
    }

    @Override
    public Object createNode(Object name, Map attrs, Object value) {
        println "* node $name with args $attrs and value $value."
        return name
    }
}

If we invoke it like so:
new DemoBuilder().build {
    household(adress: "main street 42") {
        car(name: "VW", price: 15000)
        room {
            name("living room")
            furniture(name: "TV", price: 2000)
            furniture(name: "sofa", price: 1000)
        }
    }
}
…it will print out this result:
* node build with args null and value null.
* node household with args [adress:main street 42] and value null.
parent build << child household
* node car with args [name:VW, price:15000] and value null.
parent household << child car
* node room with args null and value null.
parent household << child room
* node name with args null and value living room.
parent room << child name
* node furniture with args [name:TV, price:2000] and value null.
parent room << child furniture
* node furniture with args [name:sofa, price:1000] and value null.
parent room << child furniture

Now what is actually going on here?

In order to grasp the mechanisms of BuilderSupport it’s crucial to understand that the implementation is stateful. The current property always holds the most recently created node. This also explains why we always need to create a new builder instance; builder methods can’t be static.

Thus when we invoke a simple method on the builder, say name("living room"), it is essentially translated to:
def parent = current
current = createNode("name", "living room")
setParent(parent, current) 

Note that depending on the signature of the method we invoked, the corresponding createNode(…) flavor will be chosen:
method() => createNode(method)
method(value) => createNode(method, value)
method(Map args) => createNode(method, args)
method(value, Map args) => createNode(method, args, value)

The return value of the respective method is then assigned to the builder’s current property, as shown above.

Note that the closure object at the end of each method call is of course not handed to the respective createNode(…) call: Instead, it is evaluated, thus serving as the nesting mechanism for inner structures.

Whatever createNode(…) call is chosen, the newly-created node will then immediately be invoked alongside the former “current” node in the setParent(…) method. This method has no return value. It is just responsible for creating the “child” link between the formerly-created and the newly-created node. This is why you can literally build a builder for any structure with a well-defined parent-child relationship!

More about BuilderSupport

There are a few things we can find out when observing the various createNode(…) signatures:

First of all, the name of the method we invoke in the builder is part of the information sent to the createNode(…) handler. This means that we can truly react to dynamic method calls.

Most importantly, we find that the range of method call signatures supported by the builder is actually strictly limited to the four signatures listed above. What if we use a non-compliant method signature such as this...?
method(value1, value2) => createNode(???)

I’m tempted to try this out:
new DemoBuilder().build {
    household(adress: "main street 42") {
        car("VW", 15000)
    }
}

As expected, we run into an exception:
groovy.lang.MissingMethodException: No signature of method: 
ch.codebulb.groovybyexample.buildersupport.DemoBuilderTest.car() 
is applicable for argument types: (java.lang.String, java.lang.Integer) values: [VW, 15000]

This is very good because it means that we can enhance our builder with whatever additional methods we’d like to support. For example, we can add:
public Object car(String name, int price) {
    return createNode("car", [name: name, price: price]);
}

To make the example work again. We could thus also make use of meta-programming to allow arbitrary method calls at runtime.

Pages: 1 2

March 15, 2015

Top tips and links for JSF developers



This is my JSF link list which has proven useful in 5+ years working in that technology. We’ll go from decision making through tool usage to troubleshooting.

Decide: JSF or not?

Even back in the day when JSF 1.0 came out, competing web frameworks have already existed; in the 201* decade, with the rise of client-side JavaScript-based frameworks, a new fundamental choice has been introduced: Whether you want to go with a server-side, or a client-side framework.

Don’t take a rash decision here! It will ultimately decide whether your project will succeed or not. You do not want to find yourself stuck with a tech stack which doesn’t fit your needs anymore halfway through the project. Thus don’t just say: “We do JSF, because everyone does / because we’ve always done it”. Take your time for a thorough assessment.

There are far too many web frameworks, and far too many aspects to consider that I could give you any sensible advice in this short section. I can however give you some food for thought:
Other forces which may make you consider a JSF-based solution include:
  • Additional architectural / security challenges may arise from expose your business logic (middle tier / backend) through a public API to the client.
  • Performance / security considerations when the client UI is built in the web browser when compared with a server-side solution which sends the finished plain HTML site to the client.
  • Maturity of the Java ecosystem (c.f. the technology section below) which may not yet be reached by “up and coming” JavaScript-based solutions.
  • “Isomorphic” use of Java to write both UI controller and service interface code.
  • Existing Java knowledge in your team.
If you do consider choosing any server-side framework, or JSF, specifically, one very general “rule of thumb” I would give from my experience is that for “classical”, form-based applications, JSF holds good. This typically applies to scenarios where you port legacy systems such as former Swing / Excel macro / COBOL / [insert horrible technology here] applications to the web. If, however, a rich, dynamic, responsive, real-time desktop-like behavior of your application is key, I would strongly advice you to check a client-side alternative. I will probably elaborate more deeply on my JSF experience in a future blog post...

Learn: Best resources

As JSF by now is a very mature technology, there are tons of useful resources out there. Two of the best blogs out there are:
  • BalusC: StackOverflow legend and JSF mastermind, the creator of OmniFaces. Provides in-depth tutorials and battle-proven advice.
  • mkyong: Another very experienced JSF guru. His blog provides many very clear, easy-to-follow tutorials for common JSF tasks.
The following list is IMHO a must-read for any JSF development team member. Any JSF developer must be highly familiar with these topics and design patterns:
Also, there is a very elaborate JSF link list on ZEEF.com (a knowledge / link sharing platform actually created by BalusC, and programmed in JSF itself).

Note that however, reading though a link list doesn’t substitute reading introductory books, or attending training classes.
Moreover, it is vitally important that you and your team agree on clear standards on how to use these and other basic JSF features (plus features of accompanying technologies). One of the challenges in JSF development is that there are various ways of achieving a given goal, and some of them might violate clean JSF application design. Stick to what eminent experts say, and later adapt, if sensible.

Install: Tools you want to use

First of all, you want to use NetBeans IDE in your project, unless you already have Eclipse IDE expert knowledge in your team or an IntelliJ license at hand. This is what NetBeans offers:
  • It’s very fast and very stable
  • Everything Java EE comes out-of-the-box and preconfigured
  • Preconfigured HotDeployment with Maven on e.g. GlassFish server
  • Many useful features are preconfigured, such as XHTML / EL auto-complete, CRUD controller / view code generation, integrated DB viewer, CSS preprocessors, and more…
Then, you also want to use JRebel for instant re-deploys within milliseconds, without session invalidation. To cite Joel Spolsky: “Top notch development teams don't torture their programmers.” (source)

You’ll also want to make sure that your JVM / server environment is exactly the same from development till production. This will save you from having to analyze your program’s bytecode if you run into some JVM implementation deviations. The traditional approach here is to manually make sure to have the same software installed on every machine, but nowadays there are more modern solutions such as Docker / Vagrant virtualization.

More than often, problems will show up at the client (web browser) level first, so it’s clear that you want to have web development extensions installed in your browser. For Firefox, I use and recommend Firebug plus the Web Developer toolbar.

Addressing software development as a whole, you also typically want to use good tools to help you sketch and document your UI design and software architecture:
  • For UML modelling, I recommend the free, open source tool UMLet (which I also use throughout my blog posts).
  • For UI mockups, I recommend the free, open source tool Pencil (which I also use throughout my blog posts).
There are of course more sophisticated tools available, but these are in general so complex to use (and typically expensive) that they turn out to be actually counter-productive for about 80% of what you will ever use them for. I would always advice to stick with the most simple tool available, and only upgrade when required.

Set up: Technologies you want to use

There are a couple of very good accompanying technologies and frameworks you want to include in your JSF application stack. Not doing so would potentially violate DRY as it would force you to re-invent the wheel and program a homegrown solution for what is already covered by mature, wide-spread and supported frameworks.
  • First of all, you want to use a UI component framework. There are disputed opinions on those frameworks, but apparently, PrimeFaces offers the most sophisticated UI bling and is the most wide-spread whereas RichFaces seems the most robust choice. Under no circumstances you will want to write UI components on your own if there’s a library for that. Oh, and whatever component library you go for: it is mandatory that you get the full-blown (“call us and we’ll fix it”) support package. Otherwise, you will find yourself fixing other people’s frameworks bugs, which is arguably even more nerve-wracking than programming everything yourself. You will make extensive use of the UI framework’s capabilities, and you will potentially have to cross its limitations!
  • If you’re opting for PrimeFaces, you should also include PrimeFaces extensions which provides additional UI components as well as some ease of development util functionality.
  • In any case you want to include the OmniFaces library. Developed by BalusC (see the recommended blogs / links above), this library provides a wide range of features which will greatly increase ease of development, help you reduce boilerplate code and provide default best-practices implementations for many common JSF-related issues. This is a very robust, well-documented library!
  • As an act of shameless self-promotion, I’d also suggest you take a look at CrudFaces. This is a JSF component library / framework I’m currently developing (November 2015) which provides a robust but lean framework to build (optionally RESTful) PrimeFaces-based JSF applications according to well-known best-practices alongside a wide range of generally useful JSF components. It especially offers a great, save starting point for newly-built JSF projects.
  • You want to have a decent “glue” framework to connect your UI with your backend. This will typically be a Java EE CDI implementation such as JBoss Seam Weld (or the Spring framework) + optionally the CDI extension framework Apache DeltaSpike (thanks to Thomas Andraschko for pointing this out!).
  • On a more basic level, you typically want to include a “common Java util” library unless you’re lucky enough to bode on a Java 8+ basis where common functionality like String joining and Date arithmetics can be achieved in an “ease of development” compliant way. Otherwise (as well as for some more sophisticated functionality) you’ll need third party libraries (e.g. Apache Commons, Google Guava, Joda-Time). The rule to maintainability is here: Try using Java 8 functionality first, then try a 3rd party library, and only if nothing meets your requirements, code it yourself. Just add a new library as the need arises.
  • Optional: A “conversation scope” bean scope extension. This comes in handy in a situation where the request scope is too short-living, but view scope is too broad. Such a conversation scope is included in the Java EE CDI specification; if your middle tier tech stack is based on Spring, you’ll be forced to use 3rd party extensions such as Apache MyFaces Orchestra.
  • Optional: PrettyFaces for advanced RESTful, bookmarkable URLs.
  • You want to make sure you can use EL 2.2+ features such as method invocation with parameters. In projects with a decent tech stack, this shouldn’t be a problem nowadays; otherwise, search for help on how to activate EL 2.2 in your environment.
  • Whenever you’re forced to write JavaScript code, you want to use jQuery for convenience. Note that jQuery comes bundled with PrimeFaces already.
  • You want to include a CSS preprocessor such as Saas or LESS. This will greatly reduce boilerplate CSS code and ensure its long-term maintainability.
  • Use Twitter Bootstrap for your overall CSS layout. This will greatly reduce the pain and increase maintainability when it comes to default UI design tasks such as aligning and arranging components.

Code: Common problems and troubleshooting

No matter how well you set up your tool chain, you will almost certainly run into problems when developing more sophisticated webapps. Here’s a collection of solutions for common problems which helped me when in trouble:

Question: For no apparent reason, the server renders crap. What!?

Answer:
  • Restart the server, and clean / deploy from scratch. Trust me, there’s a good chance that everything will be fine afterwards.
  • Make sure no EL expression is erroneous. Common EL errors include additional whitespaces, e.g. value="#{myController.myProperty }"
  • Make sure the web.xml <context-param> javax.faces.FACELETS_SKIP_COMMENTS is set to true. Otherwise, sections of XHTML you commented out may still render empty placeholders which may tear apart your layout. Also, it may be a security risk to render XHTML comments to the output website. You should always activate this option.

Question: A commandLink/commandButton/ajax backing bean action/listener method not invoked

Answer: This is exhaustively addressed by BalusC in this StackOverflow answer: SO: commandLink/commandButton/ajax backing bean action/listener method not invoked.

I would add to that list that you also check:
  • Every input / action component has a legal “id” attribute.
  • Make sure that process / update attributes (for PrimeFaces commonButton) or execute / render (for JSF commandButton) point to the components you want to include in submit / re-rendering. Note that when using PrimeFaces, commandButton uses ajax per default. In order to disable ajax, you need to add the ajax="false" attribute.
  • If update (PrimeFaces) / render (JSF) is set to "@form", make sure that the component to be re-rendered is actually part of the same form as is the command component.
  • As an addition to “No UIInput value validation/conversion error should have been occurred.”: Note that if you have a multi-step click-path (e.g. open a dialog, then click a button in the dialog), a validation/conversion error could have occurred in the dialog opening already; depending on the ajax configuration, the dialog might just show up, but no subsequent actions are processed until the error is resolved. In that case, make sure validation/conversion errors are processed (i.e. they are shown in <h:message> components) for the entire click-path.
  • Make sure that when invoking a “controller” backing bean, that class is properly registered as a JSF bean (including a scope definition), e.g. it is annotated with javax.inject.@Named and @javax.enterprise.context.SessionScoped (Java EE), or with @org.springframework.stereotype.Controller and @org.springframework.context.annotation.Scope("session") (Spring), or a similar configuration.

When combining on a PrimeFaces p:commandButton update="…" with immediate="true", nothing happens.

Setting immediate="true" is the standard solution to suppress input validation.

Actually, setting immediate="true" skips the entire UPDATE_MODEL phase in the JSF life cycle; thus, an AJAX update is never processed. This is thus not a valid solution for PrimeFaces <p:commandButton> which uses AJAX by default; it only works with explicit ajax="false".

For AJAX <commandButtons>, use process="@none" instead. For AJAX <p:commandButtons>, process (which corresponds to the render attribute on vanilla JSF <f:ajax> tags) determines which values get submitted in the request to the server; it defaults to @form which submits all values in the surrounding form. Hence, if you submit @none, no value gets submitted, and no value can thus get validated.

Because with @none, not even the button press itself will be submitted, you also don’t need any server-side method.

However, in case you also need to reset potential validation errors from previous form submits (i.e. clean previous validation messages), which is typically desired for “reset / clean" button functionality, you need to use a different strategy: Use the dedicated <p:resetInput> tag within the button is question, and make sure the button is executed (process="@this"). Hence, the default solution for an AJAX with “reset / clean" functionality is
<p:commandButton value="clear"
     update="@form" process="@this">
 <p:resetInput target="@form" />
</p:commandButton>
For vanilla JSF component, there is a similar component provided by OmniFaces.

Question: Cannot find component with expression “foo” referenced from “bar”

Answer: Again, see this very helpful thorough answer by BalusC on StackOverflow: SO: Cannot find component with expression “foo” referenced from “bar” - <f:ajax> contains unknown id “foo” cannot locate it in context of component “bar”

Question: Component id has already been found in the view when using conditional rendered attribute

Answer: Yes, BalusC has a solution for that here: SO: JSF Conditional includes, cause Component ID has already been found in the view

Question: dataTable (JSF / PrimeFaces): The class 'foo' does not have the property 'bar'.

Answer: Make sure that the name chosen for the var attribute of dataTable is unique within the page, e.g. it is not used by any other component, a <ui:param> tag, or the like. Otherwise, the var declaration defined in the dataTable would be ignored and the existing value would be taken to populate the table.

For example, this declaration would cause an error:
<ui:param name="item" value="bla"/>
<h:dataTable value="#{myController.models}" var="item">
...

Conclusion

This blog post provided a very high-level view on JSF application implementation only. It really boiled down to a link list of useful introductory material as well as “quick help” reference. I found this link list really helpful throughout my JSF development carreer, so I thought it’s worth sharing it here.

Programming in JSF is not easy; when it comes to non-trivial tasks, you really need profound knowledge of all your frameworks as well as the underlying technologies. Also note that in this article, we really only concentrated on front-end programming whereas in reality, JSF development typically is deeply interweaved with business tier components (“controllers”, “services”), and even with back-end services such as transactions, persistence, and validation. In any of these abstraction layers, issues may arise which may crawl up all the way to the UI layer, making it hard to locate and thus to solve any given issue.

Please let me know in the comments section whether you found the information in this post useful. If you know other excellent sources for any JSF-related topic I forgot to mention, feel free to share them below. Also please leave me a comment if you’re actually interested in more JSF stuff; then I will probably publish more in-depth JSF-related blog posts in the future.

Updates:
  • March 20, 2015: Included Java EE CDI and Apache DeltaSpike references.
  • May 3, 2015: Included a reference to my new blog post about Validation, I18N and accessibility.
  • May 17, 2015: Included a reference to my new blog post about RESTful JSF with POST-redirect-GET.
  • May 31, 2015: “Decide” chapter updated.
  • November 15, 2015: “Code: Common problems and troubleshooting” chapter updated; link to CrudFaces added.
  • December 13, 2015: Intro / “Decide” / “Install” / “Setup” chapters updated.

March 8, 2015

10 most useful Groovy features (part 2 of 2)


I dedicate my first blog post ever to the programming language I do like the most: Groovy. Here, I’d like to share what in my opinion are the top 10 most useful features that JVM language offers (which Java doesn’t offer). Here goes part 2, make sure to check out the first part here.

6. AST transformations

In Groovy:
@TupleConstructor
@EqualsAndHashCode
@ToString(includePackage=false)
@Sortable // as of 2.4, does not work with fields, only properties
private static class Address {
    final String street
    final int number
}

public static String intoString() {
    return new Address("Main Road", 42).toString()
}

public static boolean equals() {
    return new Address("Main Road", 42) ==
        new Address("Main Road", 42)
}

public static List<String> sort() {
    return sort(new Address("Second Street", 1), new Address("Main Road", 43), 
        new Address("Main Road", 42))
}

public static List<String> sort(Object... input) {
    return input.sort()*.toString()
}
In Java:
private static class Address implements Comparable<Address>{
    private final String street;
    private final int number;

    public Address(String street, int number) {
        this.street = street;
        this.number = number;
    }

    public String getStreet() {
        return street;
    }

    public int getNumber() {
        return number;
    }

    @Override
    public int hashCode() {
        int hash = 5;
        hash = 29 * hash + Objects.hashCode(this.street);
        hash = 29 * hash + this.number;
        return hash;
    }

    @Override
    public boolean equals(Object obj) {
        if (obj == null) {
            return false;
        }
        if (getClass() != obj.getClass()) {
            return false;
        }
        final Address other = (Address) obj;
        if (!Objects.equals(this.street, other.street)) {
            return false;
        }
        if (this.number != other.number) {
            return false;
        }
        return true;
    }

    @Override
    public String toString() {
        return "AstGroovy$Address(" + street + ", " + number + ")";
    }

    @Override
    public int compareTo(Address obj) {
        int last = this.street.compareTo(obj.street);
        return last == 0 ? ((Integer)this.number).compareTo(obj.number) : last;
    }
}

public static String intoString() {
    return new Address("Main Road", 42).toString();
}

public static boolean equals() {
    return new Address("Main Road", 42).equals(new Address("Main Road", 42));
}

public static List<String> sort() {
    return AstGroovy.sort(new Object[]{
        new Address("Second Street", 1), 
        new Address("Main Road", 43), 
        new Address("Main Road", 42)});
}
AST transformations do well deserve their place in this top 10 list as they are true boilerplate-code-killers. Technically speaking, they provide a means to declaratively manipulate bytecode generation at compile time through annotations. What sounds very fancy at first is very simple in its application: Groovy comes with a bunch of built-in annotations, which, when applied to classes (or methods, or other artifacts, respectively) will manipulate the outcome of the compiled class. As these annotations have full access to the abstract syntax tree (AST), they can literally add, remove or replace any piece of code.

Although you could theoretically build your very own transformations, in practice, you will typically just rely on the 20+ highly useful AST annotations which you get out of the box. Most of them allow you to specify declaratively what would, in Java, take a considerable amount of boilerplate code.

In the example, we use some annotations to create a constructor, to implement equals() / hashCode(), toString(), and even the Comparable interface. Note also that as these modifications take place in the compile phase, their result is perfectly statically typesafe.

As you can see, this drastically decreases the amount of boilerplate code necessary to create similar outcome in pure Java. Of course, you would typically use your IDE to generate those methods, but then your code will still suffer from diminished maintainability due to the boated source code.

7. String interpolation

In Groovy:
public static String getString(String input) {
    return "Input String is $input with ${input.size()} characters."
}
In Java:
public static String getString(String input) {
    String pattern = "Input String is {0} with {1} characters.";
    return MessageFormat.format(pattern, input, input.length());
}
Even though Formatter provides some more convenient means to concatenate Strings in Java, that language still should have native support for String interpolation. Actually, any major language should have that.

In Groovy, again, this feature is built in (labeled as GString), and it does certainly increase code readability. Groovy also features additional syntactical sugar for String construction, such as escaped Strings and multiline Strings.

8. switch / “in” operator

In Groovy:
public static String switchCase(Object input) {
    switch (input) {
        case "S":
            return "It's the String 'S'."
        case {it in String && (it as String).startsWith('S')}:
            return "It starts with 'S'."
        case ~/^[A-Z].*/:
            return "It starts in upper case."
        case String:
            return "It's a String."
        case Integer:
            return "It's an Integer."
        default:
            return "It's anything else."
    }
}
In Java:
public static String switchCase(Object input) {
    if (input.equals("S")) {
        return "It's the String 'S'.";
    }
    if (input instanceof String) {
        String stringInput = (String) input;
        if (stringInput.startsWith("S")) {
            return "It starts with 'S'.";
        }
        if (stringInput.matches("^[A-Z].*")) {
            return "It starts in upper case.";
        }
        return "It's a String.";
    }
    if (input instanceof Integer) {
        return "It's an Integer.";
    }
    return "It's anything else.";
}
In Java, the switch/case statement is the most concise way to centrally specify a case differentiation. However, as the switch candidate is limited to enums or Strings (as of Java 8), the actual benefit of that construct is drastically limited.

In Groovy, on the other hand, the switch is performed by applying the in operator on the candidate for every case branch. Now, said in operator is predefined for the most commonly used JDK types such as String, collections, and others, to evaluate to some kind of “affiliation” query; e.g. when queried with a collection, it is evaluated whether the candidate is an element of the collection, when queried with a class, it is evaluated whether the candidate is of that class, when queried with a closure, it is evaluated whether the closure, when called with the candidate as its argument, returns true, and so on.

As you can imagine, this transforms the switch/case statement in Groovy from an elegant, but mostly useless structure into a structure which is actually both elegant and very powerful. It’s actually that powerful that one might consider an else if statement in Groovya code smell because you can typically make the implementation of even some sophisticated conditional statements much more readable by using a single switch/case statement. Plus, you are free to override the in operation for any of your classes. Can we have that in Java, please?

9. GPath XML / JSON parser

We use an excerpt from the Maven project pom.xml as an example XML input:
<?xml version="1.0" encoding="UTF-8"?>
<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/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>ch.codebulb</groupId>
    <artifactId>Top10GroovyFeatures</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>
    <dependencies>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.10</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.codehaus.groovy</groupId>
            <artifactId>groovy-all</artifactId>
            <version>2.4.0</version>
        </dependency>
    </dependencies>
    <name>Top10GroovyFeatures</name>
</project>
In Groovy:
@CompileDynamic
public static String parseJunitScope() {
    def project = new XmlSlurper().parseText(XML_INPUT)
    return project.dependencies.dependency.find {it.groupId == "junit"}.scope
}
In Java:
public static String parseJunitScope() {
    try {
        DocumentBuilderFactory dbFactory = DocumentBuilderFactory.newInstance();
        DocumentBuilder dBuilder = dbFactory.newDocumentBuilder();
        Document doc = dBuilder.parse(new InputSource(new StringReader(XML_INPUT)));
        doc.getDocumentElement().normalize();
        
        XPathFactory xPathFactory = XPathFactory.newInstance();
        XPath xPath = xPathFactory.newXPath();
        XPathExpression xPathExp = xPath.compile("/project/dependencies/dependency[groupId='junit']/scope");
        return (String) xPathExp.evaluate(doc, XPathConstants.STRING);
        
    } catch (ParserConfigurationException | SAXException | IOException | XPathExpressionException ex) {
        throw new RuntimeException(ex);
    }
}
That meme on the right pretty much summarizes it. XML / JSON parsing in Groovy means no boilerplate code, and straight XPath node selection instead, thanks to the clever combination of native XPath support (in the so-called “GPath” syntax) and node selection through closures on Iterable node collections.

This syntax works for both XML and JSON whereas it’s worth noting that as of version 2.3, Groovy features one of the fastest JSON parsers on the JVM.

So, even though it’s not every day  you parse XML, this clearly is a potential Java-killer when it comes to it, thus deserving its place in this top Groovy feature list.

10. Spread-dot-operator

In Groovy:
protected static final List<String> INPUT_LIST = ["a", "b", "c"].asImmutable()

public static List<String> spreadDot() {
    return INPUT_LIST*.toUpperCase()
}
In Java:
private static final List<String> INPUT_LIST = SpreadDotGroovy.INPUT_LIST;
        
public static List<String> spreadDot() {
    return INPUT_LIST.stream().map(String::toUpperCase).collect(Collectors.toList());
}
Sure, it’s a tiny feature (you could actually take it as syntactic sugar for Iterable’s collect() method), but it’s very helpful when trying to keep code clear and concise. Again, this works in static compilation, too, which makes one wonder why Java misses that useful little operator.

Thus, I added this one particular feature to that list really due to its global applicability and wide-spread usefulness.

Conclusion

Groovy introduces a vast amount of additional functionality and syntax whilst still resembling close to its Java roots. For me, Groovy’s greatest achievement is that it both extends and, at the same time, simplifies Java-like programming as does no other JVM language, which provides a smooth learning curve as well as a gradual migration path for Java projects.

Here, I presented ten of my favorite Groovy features in very loose graduation, and still, of course, that list could go on and on. Especially the list’s last item has been the toughest choice as there are just so many more features which could make it to that list because they are just about equally as helpful, depending on your project and use case. Examples include syntactic simplifications such as omitting the end-of-line colon, default imports, default visibility, == equals, but also things like operator overloading, ranges and builders.

Now this article has quite turned into a “Groovy vs. Java” competition, which clearly was biased towards Groovy. But please don’t get me wrong! Java still is a very useful language, and it shines especially in environments with strong robustness / performance criteria. After all, Groovy has never been designed as a Java replacement, but rather, as an complementary technology. However, it would be ignorant not to carefully examine which technology best fits any given project, thus introducing Groovy for where it really shines. I firmly believe that the future of JVM programming is of a polymorph nature, where multiple languages are used in conjunction, each one bringing in its own strength.

What do you think about this list? Do you agree with my “top Groovy feature” rating? Please let me know which features you missed on my list, and list your own favorite Grooyv features in the comment section below.

If you are interested in the details of the code samples used in this article, you can check them out on GitHub alongside JUnit equality tests.

Updated June 7, 2015: Included a reference to my new blog post about Java 8 lambdas vs. Groovy closures.


Pages: 1 2

10 most useful Groovy features (part 1 of 2)

I dedicate my first blog post ever to the programming language I do like the most: Groovy. Here, I’d like to share what in my opinion are my top 10 most useful features that JVM language offers (which Java doesn’t offer).

This is not an easy choice. Groovy just comes with too many little “syntactic sugar” additions as well as full-blown features which turn many annoying, bloated Java development tasks really into a breeze, increasing ease of development and maintainability by drastically decreasing the amount of boilerplate code. I found it easier to come up with this list if I asked myself: if, for whatever reason, Groovy wouldn’t be there anymore, which of its features would I miss most?

I actually could as well ask: which Groovy features do I miss most in non-Groovy (Java) projects? But in that situation I typically try to avoid this questions as it would naturally lead to immediate frustration… So let’s think in Groovy, again – here goes my list:

1. Collection literals

In Groovy:
public static List<?> getList() {
    return [1, 2, 3, [4, 5]]
}

public static Map<String, Integer> getMap() {
    return [
        John: 30,
        Alice: 40,
        Mike: 50,
    ]
}
In Java:
public static List<?> getList2() {
    return new ArrayList<>(Arrays.asList(1, 2, 3, 
            new ArrayList<>(Arrays.asList(4, 5)))
    );
}

public static Map<String, Integer> getMap() {
    Map<String, Integer> ret = new HashMap<>();
    ret.put("John", 30);
    ret.put("Alice", 40);
    ret.put("Mike", 50);
    return ret;
}
First and foremost, this is literally (pun intended!) the feature I miss most in non-Groovy projects. Collections are just everywhere! In Java, they are very unpleasant and cumbersome to work with. With Groovy’s literal syntax however, initializing a collection is very natural and highly readable. Of course, this also works when statically compiled, and therefore, I sincerely hope to see this syntactic enhancement in Java one day!

Note that whilst seriously simplifying a simple ArrayList initialization, Groovy especially makes initialization of LinkedHashMaps far easier and far more readable than equivalent Java code. To a much broader extend, this is true for nested collection structures as well.

2. GroovyBeans properties

In Groovy:
private static class Person {
    String name
    int age
    boolean active
    Person father
}

public static List<?> getPropertiesList() {
    Person person = new Person(name: "Tim")
    person.age = 20
    person.active = true
    
    // set grandfather
    person.father = new Person(name: "Tim's father")
    person.father.father = new Person(name: "Tim's grandfather")
    
    return [person.name, person.age, person.active, person.father.father.name]
}
In Java:
private static class Person {
    private String name;
    private int age;
    private boolean active;
    private Person father;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public boolean isActive() {
        return active;
    }

    public void setActive(boolean active) {
        this.active = active;
    }

    public Person getFather() {
        return father;
    }

    public void setFather(Person father) {
        this.father = father;
    }
}

public static List<?> getPropertiesList() {
    Person person = new Person();
    person.setName("Tim");
    person.setAge(20);
    person.setActive(true);
            
    // set grandfather
    person.setFather(new Person());
    person.getFather().setName("Tim's father");
    person.getFather().setFather(new Person());
    person.getFather().getFather().setName("Tim's grandfather");
    
    return new ArrayList<>(Arrays.asList(
        person.getName(), person.getAge(), person.isActive(),
        person.getFather().getFather().getName()
    ));
}
Whenever you need a more sophisticated data structure than a simple collection, you’re using an object as a container. But even though in Java, everything resolves around object access, and even though Java denotes the concept of a JavaBean as a structure which encapsulates properties, the language still lacks direct syntactic support for both declaring and accessing a bean’s properties, a feature present in many other wide-spread programming languages. For instance, C# knows the concept of accessors which implement getter / setter access to properties.

In Java, we still have to manually write getters / setters (even though we typically generate them in the IDE, including all drawbacks of generated code), and the syntax to access properties is still cumbersome.

Groovy, on the other hand, addresses both issues:
  • Declaring a field as a property is trivial: just omit the visibility modificator, and getters / setters will be weaved into bytecode;
  • Access is trivial: just use “GPath” style dot-notion to access properties (which works for all Groovy and Java classes “JavaBean” compliant properties).
Additionally, Groovy offers an extra map-constructor for all properties of a class.

Note how, in the example, access for all properties in Groovy is unified (including boolean properties), and how particularly fluent and highly maintainable code for accessing nested properties is. Also note that thanks to these enhancements, even in this simple example, the number of Groovy code lines is less than half the amount of Java code lines!

3. Closures

In Groovy:
public static List<String> collect() {
    return INPUT_LIST.collect {it.toUpperCase()}
}

public static List<String> collectMultiStatement() {
    return INPUT_LIST.collect {String ret = it.toUpperCase(); ret}
}
In Java:
public static List<String> collect() {
    return INPUT_LIST.stream().map(it -> it.toUpperCase())
            .collect(Collectors.toList());
}

public static List<String> collectMultiStatement() {
    // Mind the brackets, the return keyword and the conclusive semicolon!
    return INPUT_LIST.stream().map(it -> {String ret = it.toUpperCase(); return ret;})
            .collect(Collectors.toList());
}
In Java 8, the language proudly introduced the so-called “lambda expressions”, which are basically method references, enabling a more functional programming style.

This feature actually has been present in Groovy ever since its earliest versions, where it’s known as “closures”, thus being interweaved closely into the Groovy JDK (“the GDK”), especially in the Collections framework.

As a matter of fact now, Groovy closure syntax is still much more concise and intuitive than its “newer” Java 8 lambda counterpart. Yet, most of what makes closures easier to read and write than lambdas works also in statically compiled mode. I would even claim that writing code in Groovy closures makes it easier to read than using procedural loop instructions, whilst in Java, using lambdas would actually make it harder to read.

For instance, observe how even in this basic (although artificial) examples, the Groovy syntax is much shorter and simper.

Meanwhile I’ve also posted an in-depth comparison between closures and lambdas.

4. GDK enhancements

In Groovy:
public static String getAt() {
    INPUT_LIST[-1] = "Z"
    return INPUT_LIST[-1]
}

public static List<Integer> flattenList() {
    return INPUT_NESTED_LIST.flatten() as List<Integer>
}
In Java:
public static String getAt() {
    INPUT_LIST.remove(INPUT_LIST.size()-1);
    INPUT_LIST.add("Z");
    return INPUT_LIST.get(INPUT_LIST.size()-1);
}

public static List<Integer> flattenList() {
    return flattenList(INPUT_NESTED_LIST);
}

private static List<Integer> flattenList(List<?> list) {
    List<Integer> ret = new ArrayList<>();
    for (Object elem : list) {
        if (elem instanceof List) {
            ret.addAll(flattenList((List<?>) elem));
        }
        else {
            ret.add((Integer) elem);
        }
    }
    return ret;
}
Having covered, so far, these omnipresent syntactic simplifications Groovy brings in, I would judge the numerous enhancements Groovy provides for most JDK classes the next big advantage. Groovy introduces many additional methods as well as first-class operators for many of the classes in the JDK which is hence called the “GDK” instead.

These enhancements serve both simplification and unification of existing functionality. Several special operators are introduced for a more concise application of existing method calls, and especially for the collection classes, for String and File class, and for many more, a great amount of functionality has been implemented in a single method call which you would otherwise have to implement by hand (typically in a rather anti-pattern static “util class” style) or introduce non-standardized 3rd party libraries.

Many of these additional methods do of course work seamlessly with Groovy closures, but there are also numerous simple util methods as well.

5. Dynamic typing

In Groovy:
private static final List<?> INVENTORY = [
    new Car(), new Car(),
    new TV(), new TV(), new TV()
]

private static class Car {
    public final int cost = 10000
}

private static class TV {
    public final int cost = 1000
}

@CompileDynamic
public static int sumDynamic() {
    return INVENTORY.sum { it.cost } as int
}
In Java:
private static final List<?> INVENTORY = new ArrayList<>(Arrays.asList(
    new Car(), new Car(),
    new TV(), new TV(), new TV()
));

private static class Car {
    public final int cost = 10000;
}

private static class TV {
    public final int cost = 1000;
}

public static int sumDynamic() {        
    return INVENTORY.stream().mapToInt(it -> {
        if (it instanceof Car) {
            return ((Car)it).cost;
        }
        else if (it instanceof TV) {
            return ((TV)it).cost;
        }
        else {
            throw new IllegalArgumentException("Unexpected type: " + it);
        }
    }).sum();
}
Whilst completely optional since Groovy 2.0, dynamic typing can greatly help you reducing boilerplate code as you can simply omit type specifications, if you so whish. Some Groovy developers will even advocate type-free programming per default whilst others would encourage you to stay within type safety as long as its advantages justify some more boilerplate code.

A typical use case of dynamic typing is presented in the example: Pure data-holder objects, that can for technical reasons not be embedded in a common inheritance hierarchy, with identically named properties need to be processed. In Java, you are forced to check and cast an object even if you know that a given method is present; in Groovy, due to its dynamic type system known as “duck typing”, you are free to call any method on any object. Groovy developers will in this situation assure program robustness through extensive UnitTests.

If you still have a bad feeling about leaving the security of compile-time type checking, just think of it as an additional “emergency” tool you have in your pocket for exactly those situations, as illustrated by the example. By way of comparison, the Fantom JVM language, originally strictly statically typed, features a “dynamic invoke” operator to invoke functions dynamically for “when a static type system gets in the way of an elegant solution”. This, of course, is the very opposite approach of the one that Groovy takes, for the latter is dynamic by default. Still, it proves that one point: In Groovy (and in Fantom) you have the opportunity to override static typing if this is useful for your specific situation. In other JVM languages such as Java or Scala, you simply cannot do this. It has been decided by the language specification that static typing is the only right solution for any situation.

Head on to page 2!

Pages: 1 2