/*
 * 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.apache.ace.processlauncher;

import java.io.File;

import aQute.bnd.annotation.ProviderType;

/**
 * Denotes a particular launch configuration for a process, describing what and how to launch.
 * <p>
 * You can create a new launch configuration by "pushing" a new configuration to the ConfigAdmin
 * service. If you use something like Felix FileInstall, you can do this by creating a new
 * properties file with the following contents:
 * </p>
 * 
 * <pre>
 * # Denotes how many instances of the process should be started, >= 0.
 * # Optional, defaults to 1 instance.
 * #instance.count = 1
 * # What working directory should the executable start in?
 * # Optional, defaults to the current working directory.
 * #executable.workingDir = /path/to/cwd
 * # The executable to start, should be the fully qualified path to the
 * # executable.
 * # Mandatory, no default.
 * executable.name = /path/to/java
 * # The arguments for the executable.
 * # Mandatory, no default.
 * executable.args = -jar /path/to/jar
 * # The OSGi-filter clause which should resolve to a (single!)
 * # ProcessStreamListener instance. When given, it will be used to provide
 * # access to the launched process' stdin/stdout streams. NOTE: if you interact
 * # with the process this way, it could be that the process only terminates
 * # when you *explicitly* close the stdin stream.
 * # Optional, defaults to an empty/no filter.
 * #executable.processStreamListener =
 * # The OSGi-filter clause that should resolve to a ProcessLifecycleListener
 * # service-instance. When given, it will be used to provide hooks to when the
 * # executable is (re)started and stopped. 
 * # Optional, defaults to an empty/no filter.
 * #executable.processLifecycleListener = 
 * # When 'true' the process will automatically be restarted when it terminates
 * # with a 'abnormal' exit value (see 'executable.normalExitValue'). Any
 * # defined process stream listener will be re-invoked with the newly started
 * # process.
 * # Optional, defaults to 'false'.
 * #executable.respawnAutomatically = false
 * # Denotes what the 'normal' exit value of the process is, so the launcher can
 * # determine when a process is terminated abnormally.
 * # Optional, defaults to 0.
 * #executable.normalExitValue = 0
 * </pre>
 */
@ProviderType
public interface LaunchConfiguration {

    /**
     * Creates a fully qualified command line as array, in which the first element is the command to
     * execute, and the remainder of the array consists of the arguments that are passed to the
     * command.
     * 
     * @return the command line, as array, never <code>null</code>.
     */
    String[] getCommandLine();

    /**
     * Returns the optional arguments that should be passed to the executable.
     * 
     * @return the executable arguments, never <code>null</code>, but can be an empty array.
     * @see #getExecutableName()
     */
    String[] getExecutableArgs();

    /**
     * Returns the full path-name to the executable to launch.
     * 
     * @return the executable name, never <code>null</code>.
     */
    String getExecutableName();

    /**
     * Returns the number of instances that should be launched.
     * 
     * @return an instance count, >= 1.
     */
    int getInstanceCount();

    /**
     * Returns the exit value that indicates whether or not the process is terminated
     * successfully/normally. By convention, this is 0, but not all executables adhere to this
     * convention.
     * 
     * @return the normal exit value, defaults to 0.
     */
    int getNormalExitValue();

    /**
     * Returns a filter-string to obtain the process' stream listener that wants to interact with
     * the process.
     * <p>
     * Only a single process stream listener should be resolved by the returned filter condition.
     * When multiple listeners are returned, the one with the highest service-ID will be used as
     * defined in the OSGi specification.
     * </p>
     * 
     * @return a OSGi-filter condition, or <code>null</code> (the default) if no interaction with
     *         the process is desired.
     */
    String getProcessStreamListener();

    /**
     * Returns a filter-string to obtain the process' lifecycle listener that wants to get notified
     * about the lifecycle of the process.
     * <p>
     * Only a single process lifecycle listener should be resolved by the returned filter condition.
     * When multiple listeners are returned, the one with the highest service-ID will be used as
     * defined in the OSGi specification.
     * </p>
     * 
     * @return a OSGi-filter condition, or <code>null</code> (the default) if no notifications on
     *         the process lifecycle are desired.
     */
    String getProcessLifecycleListener();

    /**
     * Returns the working directory to use when launching the executable.
     * 
     * @return a working directory, as {@link File} object, or <code>null</code> if no working
     *         directory is to be set and the default should be used.
     */
    File getWorkingDirectory();

    /**
     * Returns whether the process should be respawned after it terminated with a non-zero exit
     * code.
     * 
     * @return <code>true</code> if the process should be respawned when it terminates with a
     *         non-zero exit code, <code>false</code> to leave it as-is (terminated).
     */
    boolean isRespawnAutomatically();

}