Expressing optional @InputFile and @InputDirectory properties

[big-guy]

I'd like to express "this is a directory/file that is an input to my task, if it exists" with default values. This means that if the input exists, my task will use it. If it doesn't exist, that's OK. If the input is the wrong type (directory instead of a file or vice versa), I'd like to get an error.

Due to the way we validate @InputFile and @InputDirectory, it's not simple to define a property this way because we require that the file or directory exists. If a plugin doesn't define a default value, you can use @Optional and a null value for the property.

Expected Behavior

I should be able to have a property with a default value that is only validated if it exists.

Current Behavior

Property validation fails before the task executes when the directory/file does not exist.

Context

I can work around this by using @InputFiles or conditionally returning null if the path does not exist. If I use @InputFiles, it's inconvenient to use File as my property type because it makes it easy for someone to pass the wrong thing (a file vs a directory) and it looks a little odd to have @InputFiles File someProp. I could also use two properties. One that's just the File that's ignored by up-to-date checks and another that's a @InputFiles FileCollection. This still has the problem that the wrong thing could be used (file vs directory) and it's strange that I would need to use two properties.

Steps to Reproduce (for bugs)

Here's an example task that fails:

class CustomTask extends DefaultTask {
    @InputDirectory
    @Optional
    File inputDir = project.file("does-not-exist")

    @OutputFile
    File outputFile = new File(temporaryDir, "output.txt")

    @TaskAction
    void generate() {
       outputFile.text = "done"
    }
}

task customTask(type: CustomTask)

The same would apply for @InputFile.

Your Environment

This always happens.

[robbie-demuth]

Just ran into this today and I think this would be a nice improvement

[stewartbryson]

Yeah... I have to write a lot of code to get around this. I write getters that go through the logic of which parameters to use. It's really nasty.

[SUPERCILEX]

@wolfs @big-guy Actually, this seemed pretty easy to do. See #5866

[johndevs]

Until we get this cool feature, I've been working around it like so:

@Optional
@InputDirectory
final Closure<File> dir = { new File('/path/to/dir').with { it.exists() ? it : null } }

Not pretty, but is a one-liner and does the job as far as I can tell.

[wolfs]

I think that the current Gradle behaviour is consistent also with respect to properties - @optional means null for them. There is an easy workaround for returning null for a non-existant input file. It seems to be different to not specify an input file and specifying an input file which is not there.

I'll close this issue now since we don't want to change the meaning of @optional for file inputs. If you want an easier way to specify that missing input files are OK, a simple method on RegularFileProperty should be enough, right? That would instruct the RegularFileProperty to return null if the file does not exist. WDYT?

[SUPERCILEX]

@wolfs That sounds reasonable. And actually, the bug I was trying to solve was related to my property being a singleton:

val releaseNotesDir by lazy {
    File(resDir, RELEASE_NOTES_PATH).orNull()
}

That doesn't work because Gradle resolves properties multiple times. BTW, is that documented somewhere?

Instead, this is correct:

val releaseNotesDir
    get() = File(resDir, RELEASE_NOTES_PATH).orNull()

[netvl]

How do you express this for DirectoryProperty? Or even for mutable properties? As far as I understand, the above example with Closure cannot be used if the property can be set by the user.

My use case is to provide a default directory for the plugin users to write to, but if they don't need it, it shouldn't even be created, and the task can handle its absence just fine. If I just use @get:InputDirectory val someDirectory: DirectoryProperty, it fails with a validation exception if the directory does not exist.

I guess it might be possible to use a special provider which would return a null value if the directory does not exist, but it is really hacky if you want to rely on another property to compute the default value:

someDirectory.set(project.layout.buildDirectory("some-directory").flatMap {
    project.provider { if (it.asFile.exists()) it else null }
})

[adammurdoch]

We should reopen this issue, as the original use case hasn't been addressed. "optional" in the title doesn't mean @Optional, it means "I don't care if it does not exist". That is, I want a way to say, for example: This property references an input file. The property must have a value, but it's ok if the location that the value points to does not exist, I'll deal with it in the task. The location must not point to a directory.

I should be able to do the same for the other kinds of inputs, such directories, collections of regular files, etc. This way, I can apply a convention to each task for things where it's ok for the thing to not exist, or I can wire in an output from some other task where it's ok for the task to not produce anything.

I'd also like a way to say "the file that this property refers to represents the 'source' or primary input of this task, so skip the task and remove old outputs if the file does not exist". This isn't quite the same as the behaviour of @SkipWhenEmpty, but is definitely the same intent.

[dsvoronin]

We should reopen this issue, as the original use case hasn't been addressed.

Yes, please!
My case is the task that could produce file, but it's also completely normal if it doesn't.
I should define outputs during configuration anyway, so it's not an @Optional RegularFileProperty,
but @Optional with "map-hack" @Input

[lacasseio]

I reopen the issue to avoid being ignored. We can summarize the work left to do in another issue and close this one later.

[realdadfish]

Just for the people who stumble upon this and need to know how the "current" way of doing things there looks like, it's this:

open class SomeTask @Inject constructor(objects: ObjectFactory) : DefaultTask() {
    @InputFile
    @Optional
    val someOptionalFile: RegularFileProperty = objects.fileProperty()

    @TaskAction
    fun run() {
        val optionalFile: File? = someOptionalFile.orNull?.asFile
        // do your stuff here
    }
}

So, this means that if someOptionalFile is given, it must exist. If it is not given, it is null. Furthermore, RegularFileProperty has a convention(RegularFile) method that allows you to specify a default file in case it is not given.

[ZakTaccardi]

    @InputFile
    @Optional
    abstract val someOptionalFile: RegularFileProperty

@bamboo this solution does not work for me because if RegularFileProperty contains a null value, then the task dependency fails to wire up dependant tasks because the @Optional annotation treats it like there was no input provided.

[ZakTaccardi]

@pun-ky 's solution was the best workaround (as it allows you to continue to use providers on your APIs between tasks. But it shouldn't be needed!

I also used a noOp dir

@Internal
val compiledKotlinSource = objects.property(FileSystemLocation::class.java)
    .convention(layout.emptyDir)

@InputFiles
val _compiledKotlinSource = objects
    .fileCollection()
    .from(compiledKotlinSource)

private val ProjectLayout.emptyDir: Provider<Directory>
    get() = buildDir
        .map { it.dir("noOp") }
        .map {
            it.asFile.mkdirs()
            it
        }

[pun-ky]

@ZakTaccardi thanks for the confirmation

[Clashsoft]

All the workarounds presented here are either Groovy or Kotlin. Is there an idiomatic alternative in plain Java?

[wolfs]

Regarding all the workarounds above, I realized that you can add the @InputFiles annotation directly to the RegularFileProperty/RegularDirectoryProperty. So this should work:

@InputFiles
val configDir = project.objects.directoryProperty().convention("/a/b/c")

@TaskAction
fun process() {
    configDir.get().asFile.copyTo(otherDir) // as example
}

That means we have a way to express an input file which doesn't need to exist: Use @InputFiles. What Gradle doesn't have is then some additional validation that if the file exists that it is actual a file/directory.

[twarner-sofi]

I worked around this using onlyIf:

onlyIf { inputFile.orNull?.asFile?.exists() ?: false }

Because the onlyIf block runs at execution time it is safe to get() or getOrNull() on the file property.

[Malinskiy]

For Kotlin: you can also pass a sealed class without the nullable/optional types with more specific details on everything that is needed. The classes need to implement Serializable AFAIU though.