/*
 * Copyright 2010 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.gradle.api.tasks;

import org.gradle.api.Incubating;
import org.gradle.api.InvalidUserDataException;
import org.gradle.api.internal.file.copy.CopyAction;
import org.gradle.api.internal.file.copy.CopySpecInternal;
import org.gradle.api.internal.file.copy.DestinationRootCopySpec;
import org.gradle.api.internal.file.copy.FileCopyAction;
import org.gradle.work.DisableCachingByDefault;

import java.io.File;
import java.util.concurrent.Callable;

/**
 * Copies files into a destination directory. This task can also rename and filter files as it copies. The task
 * implements {@link org.gradle.api.file.CopySpec CopySpec} for specifying what to copy.
 *
 * <p> Examples:
 * <pre class='autoTested'>
 * task copyDocs(type: Copy) {
 *     from 'src/main/doc'
 *     into 'build/target/doc'
 * }
 *
 * //for Ant filter
 * import org.apache.tools.ant.filters.ReplaceTokens
 *
 * //for including in the copy task
 * def dataContent = copySpec {
 *     from 'src/data'
 *     include '*.data'
 * }
 *
 * task initConfig(type: Copy) {
 *     from('src/main/config') {
 *         include '**&#47;*.properties'
 *         include '**&#47;*.xml'
 *         filter(ReplaceTokens, tokens: [version: '2.3.1'])
 *     }
 *     from('src/main/config') {
 *         exclude '**&#47;*.properties', '**&#47;*.xml'
 *     }
 *     from('src/main/languages') {
 *         rename 'EN_US_(.*)', '$1'
 *     }
 *     into 'build/target/config'
 *     exclude '**&#47;*.bak'
 *
 *     includeEmptyDirs = false
 *
 *     with dataContent
 * }
 * </pre>
 */
@DisableCachingByDefault(because = "Not worth caching")
public class Copy extends AbstractCopyTask {

    @Override
    protected CopyAction createCopyAction() {
        File destinationDir = getDestinationDir();
        if (destinationDir == null) {
            throw new InvalidUserDataException("No copy destination directory has been specified, use 'into' to specify a target directory.");
        }
        return new FileCopyAction(getFileLookup().getFileResolver(destinationDir));
    }

    @Override
    protected CopySpecInternal createRootSpec() {
        return getProject().getObjects().newInstance(DestinationRootCopySpec.class, super.createRootSpec());
    }

    @Override
    public DestinationRootCopySpec getRootSpec() {
        return (DestinationRootCopySpec) super.getRootSpec();
    }

    /**
     * Uses {@link Untracked} for {@link #getDestinationDir()}.
     * <p>
     * This causes the task to ignore already existing files in the destination directory.
     * You should use this if the destination directory contains unrelated unreadable files.
     * </p>
     *
     * @since 7.3
     */
    @Incubating
    public void doNotTrackDestinationDir() {
        getOutputs()
            .dir((Callable<File>) this::getDestinationDir)
            .withPropertyName("untrackedDestinationDir")
            .untracked();
    }

    /**
     * Returns the directory to copy files into.
     *
     * @return The destination dir.
     */
    @OutputDirectory
    public File getDestinationDir() {
        return getRootSpec().getDestinationDir();
    }

    /**
     * Sets the directory to copy files into. This is the same as calling {@link #into(Object)} on this task.
     *
     * @param destinationDir The destination directory. Must not be null.
     */
    public void setDestinationDir(File destinationDir) {
        into(destinationDir);
    }
}

@@ -2981,241 +2981,508 @@
   * 
-Uses %7B@link Untracked%7D for %7B@link #getDestinationDir()%7D.%0A     * %3Cp%3E%0A     * This causes the task to ignore already existing files in the destination directory.%0A     * You should use this if the destination directory contains unrelated
+Force Gradle to ignore content in the destination directory.%0A     * This can be useful if the destination directory contains unreadable content, or special files like named pipes that Gradle cannot snapshot.%0A     * It can also be useful when copying to a location not exclusively owned by the build, for example to a common installation directory.%0A     * In the latter case calling this method will prevent Gradle from trying to snapshot a potentially large amount of content (that might also contain
  unr
@@ -3494,16 +3494,17 @@
 le files
+)
 .%0A     *
@@ -3508,12 +3508,92 @@
   * 
-%3C/p%3E
+Copy tasks with untracked outputs are never up-to-date.%0A     *%0A     * @see Untracked
 %0A   
@@ -3664,30 +3664,23 @@
 NotTrack
-DestinationDir
+Outputs
 () %7B%0A   

Improve Javadoc of `doNotTrackOutput`