groovy.lang
[Java] Annotation Type Category
java.lang.Object
groovy.lang.Category
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
@GroovyASTTransformationClass("org.codehaus.groovy.transform.CategoryASTTransformation")
public @interface Category
Transforms an instance-style Groovy class or interface to become a static-style
conventional Groovy category.
Groovy categories are the original mechanism used
by Groovy when augmenting classes with new methods. Writing categories required
using a class writing style where all methods were static and an additional
self parameter was defined. The self parameter and static nature of the methods
disappeared once applied by Groovy's metaclass framework but some regarded
the writing style as a little noisy. This transformation allows you to write
your categories without the "apparent noise" but adds it back in during
compilation so that the classes appear as normal categories.
It might seem strange writing your class/object enhancements using a succinct
notation, then having "noise" added, then having the noise removed during
category application. If this worries you, then you may also like to consider
using Groovy's ExpandoMetaClass mechanism which avoids
the category definition altogether. If you already have an investment in
categories or like some of the other features which categories currently give you,
then read on.
The mechanics: during compilation, all methods are transformed to static ones with an additional
self parameter of the type you supply as the annotation parameter (the default type
for the self parameters is Object which might be more broad reaching than
you like so it is usually wise to specify a type).
Properties invoked using 'this' references are transformed so that
they are instead invoked on the additional self parameter and not on
the Category instance. (Remember that once the category is applied, the reverse
will occur and we will be back to conceptually having methods on the this
references again!)
Classes conforming to the conventional Groovy category conventions can be used
within use statements or mixed in at compile time with the @Mixin
transformation or at runtime with the mixin method on classes.
An example showing a use statement (allowing fine-grained application of
the category methods):
@Category(Integer)
class IntegerOps {
def triple() {
this * 3
}
}
use (IntegerOps) {
assert 25.triple() == 75
}
Or, using the @Mixin flavor for compile-time "mixing in" of the methods:
@Category(List)
class Shuffler {
def shuffle() {
def result = new ArrayList(this)
Collections.shuffle(result)
result
}
}
@Mixin(Shuffler)
class Sentence extends ArrayList {
Sentence(Collection initial) { super(initial) }
}
def words = ["The", "quick", "brown", "fox"]
println new Sentence(words).shuffle()
// => [quick, fox, The, brown] (order will vary)
Or, instead of using @Mixin, try "mixing in" your methods at runtime:
// ... as before ...
class Sentence extends ArrayList {
Sentence(Collection initial) { super(initial) }
}
Sentence.mixin Shuffler
// ... as before ...
- Authors:
- Alex Tkachman
Copyright © 2003-2010 The Codehaus. All rights reserved.