Entire package org.gradle.util is missing from javadoc and groovydoc

Old Forum Archive Bugs
1

I was trying to look up information on org.gradle.util.ConfigureUtil and find that its entire package is not available in Javadoc or Groovydoc. Searching ConfigureUtil on the Gradle website only finds a link to something from v 0.7. Yet looking in the source zip shows that this package and many classes still exist.

2

Classes that are not in the Javadoc or Groovydoc are not considered public APIs. This is a bit confusing because ‘internal’ is used in many package names throughout the Gradle codebase but it is not exclusive of all internal classes. So if it’s not in the Javadoc it’s considered private and to be used with caution (or preferably, not at all). As far as ConfigureUtil goes you can get much of the same functionality from Project.configure() which is a public API.

3

Fair enough: however, a plugin that has been cited by Gradle as perhaps “the” canonical example of “plugin composition” , i.e. https://github.com/bmuschko/gradle-docker-plugin , uses it. See Best ways of “extending” a plugin?

This can’t be a “best practice” and still use something that should “preferably not be used at all”.

4

Touché, sir :wink:

This is the result of a plugin being written by a Gradle core developer that is used to having access to Gradle internals. Tsk, tsk @bmuschko.

In this case there is a good alternative like I mentioned, Project.configure(). Sometimes there isn’t and using internal APIs is the only option. In this case feel free to do so but you risk the possibility of us breaking stuff without notice. Another route would be to argue for introducing a public API for that specific use case. Typically just wanting access to convenience methods provided by Gradle (pretty much everything in org.gradle.util) isn’t a sufficiently strong reason to open up the API. Even the capability provided by Project.configure() can be done with just a couple lines of Groovy.

1 Like
5

Oversight on my part. ConfigureUtil is an internal API and therefore doesn’t show up in the Javadocs. Usually, these classes should end up in a package named internal. We still have to align some classes in Gradle core that don’t follow the pattern yet.

What the method basically does is to set the Closure delegate and the resolve strategy. You can just use the following code to achieve the same:

def configure(Closure closure, Object delegate) {
    closure.resolveStrategy = Closure.DELEGATE_FIRST
    closure.delegate = delegate
    closure()
}

RE: Plugin composition - this concept nothing else than the following and is not related to ConfigureUtil:

class MyPlugin implements Plugin<Project> {
    void apply(Project project) {
        project.apply('someOtherPlugin')
    }
}