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/cookbooksrc/main/resources/META-INF/servicesbuild.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:
- Inside the
src/main/groovy/org/groovy/cookbookdirectory, we need to create theDateExtentions.groovyfile 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]] } } - In order for the extension to become active when it is added to the classpath, we need to create a special descriptor file called
org.codehaus.groovy.runtime.ExtensionModuleand place it under thesrc/main/resources/META-INF/servicesdirectory:moduleName=groovy-extension moduleVersion=1.0 extensionClasses=org.groovy.cookbook.DateExtensions staticExtensionClasses=
- Now you are ready to compile the extension JAR with the following standard command:
gradle clean build
- At this point, we can create a test script to verify that our extension actually works and that the
Dateclass actually has thegetMonthNamemethod. Define adate.groovyfile in the project's root directory with the following content:def now = new Date() println now.monthName
- Run the script from the same directory with the
groovycommand:groovy -cp ./build/libs/* date.groovy - Depending on your locale and date, the script should print the name of the current month:
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.
- Groovy's User Guide pages about extension modules: http://docs.codehaus.org/display/GROOVY/Creating+an+extension+module