How many times have you dreamed of adding a new method to a final class or to a class that you don't even have sources for? With Groovy, you are given the ability to do so. That's all possible thanks to Groovy's extension methods. The original class stays untouched and Groovy takes care of catching extended method calls.
In fact, we have already seen examples of this feature in some of the recipes in Chapter 2, Using Groovy Ecosystem, for example, the Using Java classes from Groovy and Embedding Groovy into Java recipes, and we'll see more in coming recipes of this book. Groovy extends many of the standard JDK classes (for example, java.io.File
, java.lang.String
, java.util.Collection
, and so on). It's one of the many cool Groovy features that makes working with some old Java APIs a pleasant business.
In this recipe, we are going to cover the mechanism of creating an extension module to an existing Java class, and then using that class inside Groovy with added functionality.
For our demonstration, we are going to extend the java.util.Date
class with a new method. To build the extension, we will use the Gradle build tool that we already encountered in the Integrating Groovy into the build process using Gradle recipe in Chapter 2, Using Groovy Ecosystem. Let's assume we have the following simple project structure:
src/main/groovy/org/groovy/cookbook
src/main/resources/META-INF/services
build.gradle
The build.gradle
looks as simple as is:
apply plugin: 'groovy' dependencies { compile localGroovy() }
Let's define the extension module contents and verify that it works with a sample script:
src/main/groovy/org/groovy/cookbook
directory, we need to create the DateExtentions.groovy
file with the following content:package org.groovy.cookbook import static java.util.Calendar.* import java.text.DateFormatSymbols class DateExtensions { static String getMonthName(Date date) { def dfs = new DateFormatSymbols() dfs.months[date[MONTH]] } }
org.codehaus.groovy.runtime.ExtensionModule
and place it under the src/main/resources/META-INF/services
directory:moduleName=groovy-extension moduleVersion=1.0 extensionClasses=org.groovy.cookbook.DateExtensions staticExtensionClasses=
gradle clean build
Date
class actually has the getMonthName
method. Define a date.groovy
file in the project's root directory with the following content:def now = new Date() println now.monthName
groovy
command:groovy -cp ./build/libs/* date.groovy
July
Groovy dynamically loads all extension modules upon startup and makes the methods defined by those available on instances of the target classes. In our case, it's the same old Date
class.
If we try to execute the date.groovy
script without the classpath containing the extension module, we'll get an ugly error:
Caught: groovy.lang.MissingPropertyException: No such property: monthName for class: java.util.Date groovy.lang.MissingPropertyException: No such property: monthName for class: java.util.Date at date.run(date.groovy:2)
Extension methods existed in Groovy before v2.0. Most of the magical GDK functionality (for example, additional methods available on the java.lang.String
or java.io.File
classes) is implemented in that way. But since Groovy 2.0, creating and packaging your own extension modules became possible.
Extension modules also work if you use the @Grab
annotations to append classpath dependencies to your scripts (see the Simplifying dependency management with Grape recipe in Chapter 2, Using Groovy Ecosystem).
You can also append static methods to the classes. The mechanism works in the exactly same way with the only small exception that you need to use staticExtensionClasses
in the module descriptor to refer to the class implementing those extensions. Also, if your module defines both static and non-static extension points, then those should be located in different classes.
That's not the only way to extend existing classes. Another approach is to use metaclass facilities at runtime. This technique is discussed in more detail in Chapter 9, Metaprogramming and DSLs in Groovy.