Categories in Groovy

1. Overview

We may sometimes wonder if we can add a few additional handy methods to compiled Java or Groovy classes where we don't have the ability to modify the source code. As it turns out, a Groovy category lets us do just that.

Groovy is a dynamic and powerful JVM language that has numerous Metaprogramming features.

In this tutorial, we'll explore the concept of categories in Groovy.

2. What Is a Category?

Categories are a metaprogramming feature, inspired by Objective-C, that allows us to add extra functionality to a new or existing Java or Groovy class.

Unlike extensions, the additional features provided by a category aren't enabled by default. Therefore, the key to enabling a category is the use code block.

The extra features implemented by a category are only accessible inside the use code block.

3. Categories in Groovy

Let's discuss a few prominent categories that are already available in the Groovy Development Kit.

3.1. TimeCategory

The TimeCategory class is available in the groovy.time package that adds a few handy ways to work with Date and Time objects.

This category adds the capability to convert an Integer into a time notation like seconds, minutes, days, and months.

Also, the TimeCategory class provides methods like plus and minus for easily adding Duration to Date objects and subtracting Duration from Date objects, respectively.

Let's examine a few handy features provided by the TimeCategory class. For these examples, we'll first create a Date object and then perform a few operations using TimeCategory:

def jan_1_2019 = new Date("01/01/2019")
use (TimeCategory) {
    assert jan_1_2019 + 10.seconds == new Date("01/01/2019 00:00:10")
    assert jan_1_2019 + 20.minutes == new Date("01/01/2019 00:20:00")
    assert jan_1_2019 - 1.day == new Date("12/31/2018")
    assert jan_1_2019 - 2.months == new Date("11/01/2018")
}

Let's discuss the code in detail.

Here, 10.seconds creates the TimeDuration object with the value of 10 seconds. And, the plus (+) operator adds the TimeDuration object to the Date object.

Similarly, 1.day creates the Duration object with the value of 1 day. And, the minus (-) operator subtracts the Duration object from the Date object.

Also, a few methods like now, ago, and from are available through the TimeCategory class, which allows creating relative dates.

For instance, 5.days.from.now will create a Date object with the value of 5 days ahead of the current date. Similarly, 2.hours.ago sets the value of 2 hours before the current time.

Let's look at them in action. Also, we'll use SimpleDateFormat to ignore the boundaries of time while comparing two similar Date objects:

SimpleDateFormat sdf = new SimpleDateFormat("dd/MM/yyyy")
use (TimeCategory) {
    assert sdf.format(5.days.from.now) == sdf.format(new Date() + 5.days)

    sdf = new SimpleDateFormat("dd/MM/yyyy hh:mm:ss")
    assert sdf.format(10.minutes.from.now) == sdf.format(new Date() + 10.minutes)
    assert sdf.format(2.hours.ago) == sdf.format(new Date() - 2.hours)
}

Therefore, using the TimeCategory class, we can write simple and more readable code using the classes we already know.

3.2. DOMCategory

The DOMCategory class is available in the groovy.xml.dom package. It offers a few handy ways to work with Java's DOM object.

More specifically, DOMCategory allows GPath operations on DOM elements, allowing easier traversal and processing of XMLs.

At first, let's write a simple XML text and parse it using the DOMBuilder class:

def baeldungArticlesText = """
<articles>
    <article core-java="true">
        <title>An Intro to the Java Debug Interface (JDI)</title>
        <desc>A quick and practical overview of Java Debug Interface.</desc>
    </article>
    <article core-java="false">
        <title>A Quick Guide to Working with Web Services in Groovy</title>
        <desc>Learn how to work with Web Services in Groovy.</desc>
    </article>
</articles>
"""

def baeldungArticlesDom = DOMBuilder.newInstance().parseText(baeldungArticlesText)
def root = baeldungArticlesDom.documentElement

Here, the root object contains all the child-nodes of the DOM. Let's traverse these nodes using the DOMCategory class:

use (DOMCategory) {
    assert root.article.size() == 2

    def articles = root.article
    assert articles[0].title.text() == "An Intro to the Java Debug Interface (JDI)"
    assert articles[1].desc.text() == "Learn how to work with Web Services in Groovy."
}

Here, the DOMCategory class allows easy access of nodes and elements using dot operations provided by GPath. Also, it provides methods like size and text to access the information of any node or element.

Now, let's append a new node to the root DOM object using DOMCategory:

use (DOMCategory) {
    def articleNode3 = root.appendNode(new QName("article"), ["core-java": "false"])
    articleNode3.appendNode("title", "Metaprogramming in Groovy")
    articleNode3.appendNode("desc", "Explore the concept of metaprogramming in Groovy")

    assert root.article.size() == 3
    assert root.article[2].title.text() == "Metaprogramming in Groovy"
}

Similarly, the DOMCategory class also contains a few methods like appendNode and setValue to modify the DOM.

4. Create a Category

Now that we've seen a couple of Groovy categories in action, let's explore how to create a custom category.

4.1. Using Self Object

A category class must follow certain practices to implement additional features.

First, the method adding an additional feature should be static. Second, the first argument of the method should be the object to which this new feature is applicable.

Let's add the capitalize feature to the String class. This will simply change the first letter of the String to upper-case.

At first, we'll write the BaeldungCategory class with a static method capitalize and String type as its first argument:

class BaeldungCategory {
    public static String capitalize(String self) {
        String capitalizedStr = self;
        if (self.size() > 0) {
            capitalizedStr = self.substring(0, 1).toUpperCase() + self.substring(1);
        }
        return capitalizedStr
    }
}

Next, let's write a quick test to enable the BaeldungCategory and verify the capitalize feature on the String object:

use (BaeldungCategory) {
    assert "norman".capitalize() == "Norman"
}

Similarly, let's write a feature to raise a number to the power of another number:

public static double toThePower(Number self, Number exponent) {
    return Math.pow(self, exponent);
}

Finally, let's test our custom category:

use (BaeldungCategory) {
    assert 50.toThePower(2) == 2500
    assert 2.4.toThePower(4) == 33.1776
}

4.2. @Category Annotation

We can also use @groovy.lang.Category annotation to declare a category as an instance-style class. When using the annotation, we must supply the class name to which our category is applicable.

The instance of the object is accessible using this keyword in a method. Hence, the self object is not required to be the first argument.

Let's write a NumberCategory class and declare it as a category with the @Category annotation. Also, we'll add a few additional features like cube and divideWithRoundUp to our new category:

@Category(Number)
class NumberCategory {
    public Number cube() {
        return this*this*this
    }
    
    public int divideWithRoundUp(BigDecimal divisor, boolean isRoundUp) {
        def mathRound = isRoundUp ? BigDecimal.ROUND_UP : BigDecimal.ROUND_DOWN
        return (int)new BigDecimal(this).divide(divisor, 0, mathRound)
    }
}

Here, the divideWithRoundUp feature divides a number by the divisor and rounds up/down the result to the next or previous integer based on the isRoundUp parameter.

Let's test our new category:

use (NumberCategory) {
    assert 3.cube() == 27
    assert 25.divideWithRoundUp(6, true) == 5
    assert 120.23.divideWithRoundUp(6.1, true) == 20
    assert 150.9.divideWithRoundUp(12.1, false) == 12
}

5. Conclusion

In this article, we've explored the concept of Categories in Groovy — a metaprogramming feature that can enable additional features on Java and Groovy classes.

We've examined a few categories like TimeCategory and DOMCategory, which are already available in Groovy. At the same time, we've explored a few additional handy ways to work with the Date and Java's DOM using these categories.

Last, we've explored a couple of ways to create our own custom category.

As usual, all the code implementations are available over on GitHub.