001package org.unix4j.command;
002
003import org.unix4j.builder.GenericCommandBuilder;
004
005/**
006 * A command interface defines the different ways a certain {@link Command} can
007 * be invoked (or instantiated). It consists of the different method signatures
008 * for the command.
009 * <p>
010 * Consider for instance the following simplified {@code ls} command. It can be
011 * called without options, with a file, with option flags or both a file and
012 * options. The command interface for {@code ls} would therefore define four
013 * methods:
014 * 
015 * <pre>
016 * R ls()
017 * R ls(File file)
018 * R ls(Ls.Option... options)
019 * R ls(File file, Ls.Option... options)
020 * </pre>
021 * 
022 * Note that all command methods in the interface usually return the generic
023 * type {@code R}. Command factories (see {@code Factory} constant of a specific
024 * command} return a new command instance. Command builders implementing many
025 * different command interfaces return an instance to itself (the BUILDER) to
026 * allow for method chaining, for instance when creating a joined command.
027 * <p>
028 * This interface does not define any methods since all methods are defined by
029 * the concrete command. The interface serves as a marker and documentation
030 * interface. Theoretically, a command interface is not required to extend this
031 * interface, but it is highly recommended. Also, if a command factory is used
032 * with {@link GenericCommandBuilder}, it must implement this interface.
033 * 
034 * @param <R>
035 *            the return type for all command signature methods, usually a new
036 *            command instance or a command fromFile providing methods for
037 *            chained invocation of following commands
038 */
039public interface CommandInterface<R> {
040        // interface defines no methods as they are all defined by the command
041        // interfaces being sub-interfaces of this class
042}