groovy.lang
[Java] Class Closure

java.lang.Object
  groovy.lang.GroovyObjectSupport
      groovy.lang.Closure

All Implemented Interfaces:

Cloneable, GroovyCallable, Runnable, Serializable

public abstract class Closure
extends GroovyObjectSupport

Represents any closure object in Groovy.

Groovy allows instances of Closures to be called in a short form. For example:

   def a = 1
   def c = {a}
   assert c() == 1
 

   def a = 1
   def c = {a}
   assert c.call() == 1
 

Authors:

James Strachan

John Wilson

Jochen Theodorou

Graeme Rocher

Paul King

Version:

\$Revision\$

DELEGATE_FIRST

public static final int DELEGATE_FIRST

With this resolveStrategy set the closure will attempt to resolve property references to the delegate first then the owner. For example the following code :

  class Test {
    def x = 30
    def y = 40

    def run() {
        def data = [ x: 10, y: 20 ]
        def cl = { y = x + y }
        cl.delegate = data
        cl.resolveStrategy = Closure.DELEGATE_FIRST
        cl()
        println x
        println y
        println data
    }
  }

  new Test().run()
 

will output :

     30
     40
     [x:10, y:30]
 

because the x and y variables declared in the delegate shadow the fields in the owner class.

Note that local variables are always looked up first, independently of the resolution strategy.

DELEGATE_ONLY

public static final int DELEGATE_ONLY

With this resolveStrategy set the closure will resolve property references to the delegate only and entirely bypass the owner. For example the following code :

  class Test {
    def x = 30
    def y = 40
    def z = 50

    def run() {
        def data = [ x: 10, y: 20 ]
        def cl = { y = x + y + z}
        cl.delegate = data
        cl.resolveStrategy = Closure.DELEGATE_ONLY
        cl()
        println x
        println y
        println data
    }
  }

  new Test().run()
 

will throw an error because even if the owner declares a "z" field, the resolution strategy will bypass lookup in the owner.

Note that local variables are always looked up first, independently of the resolution strategy.

DONE

public static final int DONE

IDENTITY

public static final Closure IDENTITY

OWNER_FIRST

public static final int OWNER_FIRST

With this resolveStrategy set the closure will attempt to resolve property references to the owner first, then the delegate (this is the default strategy). For example the following code :

  class Test {
    def x = 30
    def y = 40

    def run() {
        def data = [ x: 10, y: 20 ]
        def cl = { y = x + y }
        cl.delegate = data
        cl()
        println x
        println y
        println data
    }
  }

  new Test().run()
 

will output :

     30
     70
     [x:10, y:20]
 

because the x and y fields declared in the Test class the variables in the delegate.

Note that local variables are always looked up first, independently of the resolution strategy.

OWNER_ONLY

public static final int OWNER_ONLY

With this resolveStrategy set the closure will resolve property references to the owner only and not call the delegate at all. For example the following code :

  class Test {
    def x = 30
    def y = 40

    def run() {
        def data = [ x: 10, y: 20, z: 30 ]
        def cl = { y = x + y }
        cl.delegate = data
        cl.resolveStrategy = Closure.OWNER_ONLY
        cl()
        println x
        println y
        println data
    }
  }

  new Test().run()
 

will throw "No such property: z" error because even if the z variable is declared in the delegate, no lookup is made.

Note that local variables are always looked up first, independently of the resolution strategy.

SKIP

public static final int SKIP

TO_SELF

public static final int TO_SELF

With this resolveStrategy set the closure will resolve property references to itself and go through the usual MetaClass look-up process. This means that properties are neither resolved from the owner nor the delegate, but only on the closure object itself. This allows the developer to override getProperty using ExpandoMetaClass of the closure itself.

Note that local variables are always looked up first, independently of the resolution strategy.

maximumNumberOfParameters

protected int maximumNumberOfParameters

parameterTypes

protected Class[] parameterTypes

Closure

public Closure(Object owner, Object thisObject)

Closure

public Closure(Object owner)

Constructor used when the "this" object for the Closure is null. This is rarely the case in normal Groovy usage.

Parameters:

owner - the Closure owner

asWritable

public Closure asWritable()

Returns:

a version of this closure which implements Writable. Note that the returned Writable also overrides toString() in order to allow rendering the result directly to a String.

call

public Object call()

Invokes the closure without any parameters, returning any value if applicable.

Returns:

the value if applicable or null if there is no return statement in the closure

call

@SuppressWarnings("unchecked")
public Object call(Object... args)

call

public Object call(Object arguments)

Invokes the closure, returning any value if applicable.

Parameters:

arguments - could be a single value or a List of values

Returns:

the value if applicable or null if there is no return statement in the closure

clone

public Object clone()

curry

public Closure curry(Object... arguments)

Support for Closure currying.

Typical usage:

 def multiply = { a, b -> a * b }
 def doubler = multiply.curry(2)
 assert doubler(4) == 8
 

Note: special treatment is given to Closure vararg-style capability. If you curry a vararg parameter, you don't consume the entire vararg array but instead the first parameter of the vararg array as the following example shows:

 def a = { one, two, Object[] others -> one + two + others.sum() }
 assert a.parameterTypes.name == ['java.lang.Object', 'java.lang.Object', '[Ljava.lang.Object;']
 assert a(1,2,3,4) == 10
 def b = a.curry(1)
 assert b.parameterTypes.name == ['java.lang.Object', '[Ljava.lang.Object;']
 assert b(2,3,4) == 10
 def c = b.curry(2)
 assert c.parameterTypes.name == ['[Ljava.lang.Object;']
 assert c(3,4) == 10
 def d = c.curry(3)
 assert d.parameterTypes.name == ['[Ljava.lang.Object;']
 assert d(4) == 10
 def e = d.curry(4)
 assert e.parameterTypes.name == ['[Ljava.lang.Object;']
 assert e() == 10
 assert e(5) == 15
 

Parameters:

arguments - the arguments to bind

Returns:

the new closure with its arguments bound

getDelegate

public Object getDelegate()

Returns:

the delegate Object to which method calls will go which is typically the outer class when the closure is constructed

getDirective

public int getDirective()

Returns:

Returns the directive.

getMaximumNumberOfParameters

public int getMaximumNumberOfParameters()

Returns:

the maximum number of parameters a doCall method of this closure can take

getOwner

public Object getOwner()

Returns:

the owner Object to which method calls will go which is typically the outer class when the closure is constructed

getParameterTypes

public Class[] getParameterTypes()

Returns:

the parameter types of the longest doCall method of this closure

getProperty

public Object getProperty(String property)

getResolveStrategy

public int getResolveStrategy()

Gets the strategy which the closure users to resolve methods and properties

Returns:

The resolve strategy

See Also:

Closure.DELEGATE_FIRST

Closure.DELEGATE_ONLY

Closure.OWNER_FIRST

Closure.OWNER_ONLY

Closure.TO_SELF

getThisObject

public Object getThisObject()

isCase

public boolean isCase(Object candidate)

leftShift

public Closure leftShift(Closure other)

Support for Closure reverse composition.

Typical usage:

 def twice = { a -> a * 2 }
 def thrice = { a -> a * 3 }
 def times6 = thrice << twice
 // equivalent: times6 = { a -> thrice(twice(a)) }
 assert times6(3) == 18
 

Parameters:

other - the Closure to compose with the current Closure

Returns:

the new composed Closure

leftShift

public Object leftShift(Object arg)

memoize

public Closure memoize()

Creates a caching variant of the closure. Whenever the closure is called, the mapping between the parameters and the return value is preserved in cache making subsequent calls with the same arguments fast. This variant will keep all cached values forever, i.e. till the closure gets garbage-collected. The returned function can be safely used concurrently from multiple threads, however, the implementation values high average-scenario performance and so concurrent calls on the memoized function with identical argument values may not necessarily be able to benefit from each other's cached return value. With this having been mentioned, the performance trade-off still makes concurrent use of memoized functions safe and highly recommended. The cache gets garbage-collected together with the memoized closure.

Returns:

A new closure forwarding to the original one while caching the results

memoizeAtLeast

public Closure memoizeAtLeast(int protectedCacheSize)

Creates a caching variant of the closure with automatic cache size adjustment and lower limit on the cache size. Whenever the closure is called, the mapping between the parameters and the return value is preserved in cache making subsequent calls with the same arguments fast. This variant allows the garbage collector to release entries from the cache and at the same time allows the user to specify how many entries should be protected from the eventual gc-initiated eviction. Cached entries exceeding the specified preservation threshold are made available for eviction based on the LRU (Last Recently Used) strategy. Given the non-deterministic nature of garbage collector, the actual cache size may grow well beyond the limits set by the user if memory is plentiful. The returned function can be safely used concurrently from multiple threads, however, the implementation values high average-scenario performance and so concurrent calls on the memoized function with identical argument values may not necessarily be able to benefit from each other's cached return value. Also the protectedCacheSize parameter might not be respected accurately in such scenarios for some periods of time. With this having been mentioned, the performance trade-off still makes concurrent use of memoized functions safe and highly recommended. The cache gets garbage-collected together with the memoized closure.

Parameters:

protectedCacheSize - Number of cached return values to protect from garbage collection

Returns:

A new function forwarding to the original one while caching the results

memoizeAtMost

public Closure memoizeAtMost(int maxCacheSize)

Creates a caching variant of the closure with upper limit on the cache size. Whenever the closure is called, the mapping between the parameters and the return value is preserved in cache making subsequent calls with the same arguments fast. This variant will keep all values until the upper size limit is reached. Then the values in the cache start rotating using the LRU (Last Recently Used) strategy. The returned function can be safely used concurrently from multiple threads, however, the implementation values high average-scenario performance and so concurrent calls on the memoized function with identical argument values may not necessarily be able to benefit from each other's cached return value. With this having been mentioned, the performance trade-off still makes concurrent use of memoized functions safe and highly recommended. The cache gets garbage-collected together with the memoized closure.

Parameters:

maxCacheSize - The maximum size the cache can grow to

Returns:

A new function forwarding to the original one while caching the results

memoizeBetween

public Closure memoizeBetween(int protectedCacheSize, int maxCacheSize)

Creates a caching variant of the closure with automatic cache size adjustment and lower and upper limits on the cache size. Whenever the closure is called, the mapping between the parameters and the return value is preserved in cache making subsequent calls with the same arguments fast. This variant allows the garbage collector to release entries from the cache and at the same time allows the user to specify how many entries should be protected from the eventual gc-initiated eviction. Cached entries exceeding the specified preservation threshold are made available for eviction based on the LRU (Last Recently Used) strategy. Given the non-deterministic nature of garbage collector, the actual cache size may grow well beyond the protected size limits set by the user, if memory is plentiful. Also, this variant will never exceed in size the upper size limit. Once the upper size limit has been reached, the values in the cache start rotating using the LRU (Last Recently Used) strategy. The returned function can be safely used concurrently from multiple threads, however, the implementation values high average-scenario performance and so concurrent calls on the memoized function with identical argument values may not necessarily be able to benefit from each other's cached return value. Also the protectedCacheSize parameter might not be respected accurately in such scenarios for some periods of time. With this having been mentioned, the performance trade-off still makes concurrent use of memoized functions safe and highly recommended. The cache gets garbage-collected together with the memoized closure.

Parameters:

protectedCacheSize - Number of cached return values to protect from garbage collection

maxCacheSize - The maximum size the cache can grow to

Returns:

A new function forwarding to the original one while caching the results

ncurry

public Closure ncurry(int n, Object... arguments)

Support for Closure currying at a given index. Parameters are supplied from index position "n". Typical usage:

 def caseInsensitive = { a, b -> a.toLowerCase() <=> b.toLowerCase() } as Comparator
 def caseSensitive = { a, b -> a <=> b } as Comparator
 def animals1 = ['ant', 'dog', 'BEE']
 def animals2 = animals1 + ['Cat']
 // curry middle param of this utility method:
 // Collections#binarySearch(List list, Object key, Comparator c)
 def catSearcher = Collections.&binarySearch.ncurry(1, "cat")
 [[animals1, animals2], [caseInsensitive, caseSensitive]].combinations().each{ a, c ->
   def idx = catSearcher(a.sort(c), c)
   print a.sort(c).toString().padRight(22)
   if (idx < 0) println "Not found but would belong in position ${-idx - 1}"
   else println "Found at index $idx"
 }
 // =>
 // [ant, BEE, dog]       Not found but would belong in position 2
 // [ant, BEE, Cat, dog]  Found at index 2
 // [BEE, ant, dog]       Not found but would belong in position 2
 // [BEE, Cat, ant, dog]  Not found but would belong in position 3
 

Parameters:

n - the index from which to bind parameters (may be -ve in which case it will be normalized)

arguments - the arguments to bind

Returns:

the new closure with its arguments bound

See Also:

curry(Object...)

ncurry

public Closure ncurry(int n, Object argument)

Support for Closure currying at a given index.

Parameters:

argument - the argument to bind

Returns:

the new closure with the argument bound

See Also:

ncurry(int, Object...)

rcurry

public Closure rcurry(Object... arguments)

Support for Closure "right" currying. Parameters are supplied on the right rather than left as per the normal curry() method. Typical usage:

 def divide = { a, b -> a / b }
 def halver = divide.rcurry(2)
 assert halver(8) == 4
 

Parameters:

arguments - the arguments to bind

Returns:

the new closure with its arguments bound

See Also:

curry(Object...)

rcurry

public Closure rcurry(Object argument)

Support for Closure "right" currying.

Parameters:

argument - the argument to bind

Returns:

the new closure with the argument bound

See Also:

rcurry(Object...)

rightShift

public Closure rightShift(Closure other)

Support for Closure forward composition.

Typical usage:

 def twice = { a -> a * 2 }
 def thrice = { a -> a * 3 }
 def times6 = twice >> thrice
 // equivalent: times6 = { a -> thrice(twice(a)) }
 assert times6(3) == 18
 

Parameters:

other - the Closure to compose with the current Closure

Returns:

the new composed Closure

run

public void run()

setDelegate

public void setDelegate(Object delegate)

Allows the delegate to be changed such as when performing markup building

Parameters:

delegate - the new delegate

setDirective

public void setDirective(int directive)

Parameters:

directive - The directive to set.

setProperty

public void setProperty(String property, Object newValue)

setResolveStrategy

public void setResolveStrategy(int resolveStrategy)

Sets the strategy which the closure uses to resolve property references. The default is Closure.OWNER_FIRST

Parameters:

resolveStrategy - The resolve strategy to set

See Also:

Closure.DELEGATE_FIRST

Closure.DELEGATE_ONLY

Closure.OWNER_FIRST

Closure.OWNER_ONLY

Closure.TO_SELF

throwRuntimeException

protected static Object throwRuntimeException(Throwable throwable)

trampoline

public Closure trampoline(Object... args)

Builds a trampolined variant of the current closure. To prevent stack overflow due to deep recursion, functions can instead leverage the trampoline mechanism and avoid recursive calls altogether. Under trampoline, the function is supposed to perform one step of the calculation and, instead of a recursive call to itself or another function, it return back a new closure, which will be executed by the trampoline as the next step. Once a non-closure value is returned, the trampoline stops and returns the value as the final result. Here is an example:

 def fact
 fact = { n, total ->
     n == 0 ? total : fact.trampoline(n - 1, n * total)
 }.trampoline()
 def factorial = { n -> fact(n, 1G)}
 println factorial(20) // => 2432902008176640000
 

Parameters:

args - Parameters to the closure, so as the trampoline mechanism can call it

Returns:

A closure, which will execute the original closure on a trampoline.

trampoline

public Closure trampoline()

Builds a trampolined variant of the current closure. To prevent stack overflow due to deep recursion, functions can instead leverage the trampoline mechanism and avoid recursive calls altogether. Under trampoline, the function is supposed to perform one step of the calculation and, instead of a recursive call to itself or another function, it return back a new closure, which will be executed by the trampoline as the next step. Once a non-closure value is returned, the trampoline stops and returns the value as the final result.

Returns:

A closure, which will execute the original closure on a trampoline.

See Also:

trampoline(Object...)

Copyright © 2003-2011 The Codehaus. All rights reserved.