/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.netbeans.api.java.project.runner;

import java.io.IOException;
import java.text.MessageFormat;
import java.util.Collection;
import java.util.Map;
import java.util.logging.Logger;
import org.netbeans.api.java.classpath.ClassPath;
import org.netbeans.api.java.platform.JavaPlatform;
import org.netbeans.api.project.Project;
import org.netbeans.spi.java.project.runner.JavaRunnerImplementation;
import org.openide.execution.ExecutorTask;
import org.openide.filesystems.FileObject;
import org.openide.util.Lookup;
import org.openide.util.Parameters;

/**
 * <p>Class that allows to execute given file(s). API clients can check whether given
 * command is support, by calling
 * {@link #isSupported(String)} and execute the command by calling
 * {@link #execute(String, Map)}. Please consult documentation of particular
 * commands for the list of supported properties.</p>
 *
 * The following "standard" properties are supported by most commands (unless stated otherwise):
 * <table>
 * <tr><td>{@link #PROP_EXECUTE_FILE}      </td> <td>file to be executed (optional)</td> <td>{@link String} (absolute path) or {@link FileObject}</td></tr>
 * <tr><td>{@link #PROP_WORK_DIR}          </td> <td> working directory, project directory of execute.file will be used if missing </td> <td> {@link String} or {@link FileObject} or {@link java.io.File}</td></tr>
 * <tr><td>{@link #PROP_CLASSNAME}         </td> <td> class to execute, will be autodetected from execute.file if missing </td> <td> {@link String}</td></tr>
 * <tr><td>{@link #PROP_EXECUTE_CLASSPATH} </td> <td> execute classpath, will be autodetected from execute.file if missing </td> <td> {@link ClassPath}</td></tr>
 * <tr><td>{@link #PROP_PLATFORM_JAVA}     </td> <td> java tool which should be used for execution, will be autodetected from platform property if missing </td> <td> {@link String} or {@link FileObject} or {@link java.io.File}</td></tr>
 * <tr><td>{@link #PROP_PLATFORM}          </td> <td> java platform on which the class should be executed, default if missing, not needed if platform.java is set </td> <td> {@link JavaPlatform}</td></tr>
 * <tr><td>{@link #PROP_PROJECT_NAME}      </td> <td> name of the current project, will be autodetected from execute.file if missing </td> <td> {@link String}</td></tr>
 * <tr><td>{@link #PROP_RUN_JVMARGS}       </td> <td> JVM arguments </td> <td> {@link Iterable} of {@link String}s</td></tr>
 * <tr><td>{@link #PROP_APPLICATION_ARGS}  </td> <td> application arguments </td> <td> {@link Iterable} of {@link String}s</td></tr>
 * </table>
 * 
 * @see JavaRunnerImplementation
 * @since 1.22
 *
 * @author Jan Lahoda
 */
public final class JavaRunner {

    /**
     * <p>"Test" run the given file. Classfiles produced by the Java infrastructure will be
     * executed.</p>
     *
     * <p>These properties are should be set in the properties, or inferable: {@link #PROP_EXECUTE_CLASSPATH},
     * {@link #PROP_CLASSNAME}, {@link #PROP_PLATFORM_JAVA}, {@link #PROP_WORK_DIR}, {@link #PROP_RUN_JVMARGS}
     * and {@link #PROP_APPLICATION_ARGS}.</p>
     *
     * @since 1.22
     */
    public static final String QUICK_RUN = "run";

    /**
     * <p>"Test" run the given file in the debugging mode. Classfiles produced by the Java infrastructure will be
     * executed.</p>
     *
     * <p>These properties are should be set in the properties, or inferable: {@link #PROP_EXECUTE_CLASSPATH},
     * {@link #PROP_CLASSNAME}, {@link #PROP_PLATFORM_JAVA}, {@link #PROP_WORK_DIR}, {@link #PROP_RUN_JVMARGS}
     * and {@link #PROP_APPLICATION_ARGS}.</p>
     *
     * <p>Property <code>stopclassname</code> can be set to a classname to support starting debugger using
     * the Step Into command.</p>
     *
     * @since 1.22
     */
    public static final String QUICK_DEBUG = "debug";
    
    /**
     * <p>"Test" run the given file in the profiling mode. Classfiles produced by the Java infrastructure will be
     * executed.</p>
     *
     * <p>These properties are should be set in the properties, or inferable: {@link #PROP_EXECUTE_CLASSPATH},
     * {@link #PROP_CLASSNAME}, {@link #PROP_PLATFORM_JAVA}, {@link #PROP_WORK_DIR}, {@link #PROP_RUN_JVMARGS}
     * and {@link #PROP_APPLICATION_ARGS}.</p>
     *
     * @since 1.44
     */
    public static final String QUICK_PROFILE = "profile";
    
    /**
     * <p>"Test" run the given test. Classfiles produced by the Java infrastructure will be
     * executed.</p>
     *
     * <p>These properties are should be set in the properties, or inferable: {@link #PROP_EXECUTE_CLASSPATH},
     * {@link #PROP_CLASSNAME}, {@link #PROP_PLATFORM_JAVA}, {@link #PROP_WORK_DIR} and {@link #PROP_RUN_JVMARGS}.</p>
     *
     * <p><strong>application.args</strong> property is not supported.</p>
     *
     * @since 1.22
     */
    public static final String QUICK_TEST = "junit";

    /**
     * <p>"Test" run the given test in the debugging mode. Classfiles produced by the Java infrastructure will be
     * executed.</p>
     *
     * <p>These properties are should be set in the properties, or inferable: {@link #PROP_EXECUTE_CLASSPATH},
     * {@link #PROP_CLASSNAME}, {@link #PROP_PLATFORM_JAVA}, {@link #PROP_WORK_DIR} and {@link #PROP_RUN_JVMARGS}.</p>
     * 
     * <strong>application.args</strong> property is not supported.
     *
     * @since 1.22
     */
    public static final String QUICK_TEST_DEBUG = "junit-debug";

    /**
     * <p>"Test" run the given test in the profiling mode. Classfiles produced by the Java infrastructure will be
     * executed.</p>
     *
     * <p>These properties are should be set in the properties, or inferable: {@link #PROP_EXECUTE_CLASSPATH},
     * {@link #PROP_CLASSNAME}, {@link #PROP_PLATFORM_JAVA}, {@link #PROP_WORK_DIR} and {@link #PROP_RUN_JVMARGS}.</p>
     *
     * <p><strong>application.args</strong> property is not supported.</p>
     *
     * @since 1.44
     */
    public static final String QUICK_TEST_PROFILE = "junit-profile";
    
    /** <p>"Test" run the given applet. Classfiles produced by the Java infrastructure will be
     * executed.</p>
     * 
     * <p>These properties are should be set in the properties, or inferable: {@link #PROP_EXECUTE_CLASSPATH},
     * {@link #PROP_EXECUTE_FILE}, {@link #PROP_PLATFORM_JAVA}, {@link #PROP_WORK_DIR} and {@link #PROP_RUN_JVMARGS},
     * <code>applet.url</code>.</p>
     * 
     * @since 1.22
     */
    public static final String QUICK_RUN_APPLET = "run-applet";
    
    /** <p>"Test" run the given applet in debugging mode. Classfiles produced by the Java infrastructure will be
     * executed.</p>
     * 
     * <p>These properties are should be set in the properties, or inferable: {@link #PROP_EXECUTE_CLASSPATH},
     * {@link #PROP_EXECUTE_FILE}, {@link #PROP_PLATFORM_JAVA}, {@link #PROP_WORK_DIR} and {@link #PROP_RUN_JVMARGS},
     * <code>applet.url</code>.</p>
     * 
     * @since 1.22
     */
    public static final String QUICK_DEBUG_APPLET = "debug-applet";
    
    /** <p>"Test" run the given applet in the profiling mode. Classfiles produced by the Java infrastructure will be
     * executed.</p>
     * 
     * <p>These properties are should be set in the properties, or inferable: {@link #PROP_EXECUTE_CLASSPATH},
     * {@link #PROP_EXECUTE_FILE}, {@link #PROP_PLATFORM_JAVA}, {@link #PROP_WORK_DIR} and {@link #PROP_RUN_JVMARGS},
     * <code>applet.url</code>.</p>
     * 
     * @since 1.44
     */
    public static final String QUICK_PROFILE_APPLET = "profile-applet";
    
    /** Clean classfiles produced by the Java infrastructure.
     * 
     * @since 1.22
     */
    public static final String QUICK_CLEAN = "clean";

    /** File to execute. Should be either {@link String} (absolute path) or {@link FileObject}.
     *
     * @since 1.22
     */
    public static final String PROP_EXECUTE_FILE = "execute.file";

    /** Working directory for execution. Should be either {@link String} (absolute path) or {@link FileObject} or {@link java.io.File}.
     *
     * @since 1.22
     */
    public static final String PROP_WORK_DIR = "work.dir";

    /** JVM arguments to be used for the execution. Should be an {@link Iterable} of {@link String}s.
     * <p>Arguments may also be contributed by {@link org.netbeans.api.extexecution.startup.StartupExtender}s;
     * the {@link JavaPlatform} (see {@link #PROP_PLATFORM}) will be in the context,
     * as will a {@link Project} if available from {@link #PROP_EXECUTE_FILE} or {@link #PROP_WORK_DIR}.
     * @since 1.22
     */
    public static final String PROP_RUN_JVMARGS = "run.jvmargs";

    /** The name of the class to execute. Should be {@link String} - fully qualified binary name.
     *  Will be autodetected from {@link #PROP_EXECUTE_FILE} if missing.
     * 
     * @since 1.22
     */
    public static final String PROP_CLASSNAME = "classname";

    /** Execute classpath to use for execution of the class. Should be {@link ClassPath}.
     *  Will be autodetected from {@link #PROP_EXECUTE_FILE} if missing.
     *
     * @since 1.22
     */
    public static final String PROP_EXECUTE_CLASSPATH = "execute.classpath";

    /** Execute modulepath to use for execution of the class. Should be {@link ClassPath}.
     *  Will be autodetected from {@link #PROP_EXECUTE_FILE} if missing.
     *
     * @since 1.71
     */
    public static final String PROP_EXECUTE_MODULEPATH = "execute.modulepath";

    /** Java tool to use for execution. Should be {@link String} (absolute path) or {@link FileObject} or {@link java.io.File}.
     *  Will be autodetected from {@link #PROP_PLATFORM} if missing.
     *
     * @since 1.22
     */
    public static final String PROP_PLATFORM_JAVA = "platform.java";

    /** Java platform to use for execution. Should be {@link JavaPlatform}.
     *  Will be used to autodetect {@link #PROP_PLATFORM_JAVA}.
     * 
     * @since 1.22
     */
    public static final String PROP_PLATFORM = "platform";

    /** Project name to use for Output Window caption. Should be {@link String}.
     *  Will be autodetected from {@link #PROP_EXECUTE_FILE} if missing.
     * 
     * @since 1.22
     */
    public static final String PROP_PROJECT_NAME = "project.name";

    /** Application arguments to be used for the execution. Should be an {@link Iterable} of {@link String}s.
     *
     * @since 1.22
     */
    public static final String PROP_APPLICATION_ARGS = "application.args";

    /**
     * Runtime file encoding passed to the jvm (-Dfile.encoding).
     * If not given the {@link org.netbeans.api.queries.FileEncodingQuery} is used
     * to obtain the encoding.
     * @since 1.28
     */
    public static final String PROP_RUNTIME_ENCODING = "runtime.encoding";  //NOI18N

    private static final Logger LOG = Logger.getLogger(JavaRunner.class.getName());

    /**
     * Check whether the given command is supported.
     *
     * @param command command name
     * @param toRun either the file that would be executed, or the project folder
     * @return true if and only if the given command is supported for given file/folder
     *
     * @since 1.22
     */
    public static boolean isSupported(String command, Map<String, ?> properties) {
        Parameters.notNull("command", command);
        Parameters.notNull("properties", properties);

        for (JavaRunnerImplementation i : Lookup.getDefault().lookupAll(JavaRunnerImplementation.class)) {
            if (i.isSupported(command, properties)) {
                return true;
            }
        }

        return false;
    }

    /**
     * Execute the given command with given parameters. Please refer to the documentation
     * of the given command for supported properties.
     *
     * @param command command to execute
     * @param props properties
     * @param toRun file to run
     * @throws java.io.IOException if execution fails
     * @throws java.lang.UnsupportedOperationException if the given command is not supported
     *
     * @since 1.22
     */
    public static ExecutorTask execute(String command, Map<String, ?> properties) throws IOException, UnsupportedOperationException {
        Parameters.notNull("command", command);
        Parameters.notNull("properties", properties);
        
        final Collection<? extends JavaRunnerImplementation> runners = Lookup.getDefault().lookupAll(JavaRunnerImplementation.class);
        for (JavaRunnerImplementation i : runners) {
            if (i.isSupported(command, properties)) {
                return i.execute(command, properties);
            }
        }

        throw new UnsupportedOperationException(MessageFormat.format(
            "command: {0}, JavaRunner impls: {1}",  //NOI18N
            command,
            runners));
    }

}
