When to use @Internal annotation

Help/Discuss
1

Hi, I’m developing a custom plugin that is similar with official code-quality plugins. I’m checking the document of @Internal annotation but I cannot understand the meaning.

In short, the document says that we do NOT consider annotated values when we judge the task is out-of-date or not.

But we can find strange usage in official plugins like this easily. In this case, when Checkstyle config file is updated, it means the rule is updated so the task should be treated as out-of-date.

Let me confirm that Javadoc says right and expected specification. And then, please help me to understand why @Internal annotation is used in this case. Thanks in advance & Happy new year :slight_smile:

2

This is correct. The @Internal annotation indicates that the particular property should not be considered. This is usually because the property does not affect the output or it is derived from other properties that are already considered.

The Checkstyle config is abstracted out as a TextResource. The getConfigFile() method File is derived from the config property. It could be backed by an actual file, but in some cases, there’s not a file at all and getConfigFile() creates a new temporary file with the contents of the config. It’s the config property itself that determines if the Checkstyle config is UP-TO-DATE, not the File, so @Internal is exactly what should be expected here.

1 Like
3

Understood that config is used as input.

Then in my case I don’t need the annotation. Thank you!

4

public getters need @Internal annotation and private doesn’t. But I often wonder should I use it on protected getter? I found following:

package org.gradle.api.internal;

@Deprecated // Hmm this is deprecated...
public abstract class AbstractTask implements TaskInternal, DynamicObjectAware {
    // ...

    @Internal
    protected ServiceRegistry getServices() { return this.services; }
    // ...

So I assume that I should use this for protected getters also when needed. @jjustinic: Maybe the documentation should say this also?