/*
 * This file is part of muCommander, http://www.mucommander.com
 *
 * muCommander is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * muCommander is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package com.mucommander.desktop;

import java.io.IOException;

/**
 * Contract for basic desktop operations.
 * <p>
 * A desktop operation is an system dependent operation tied to the desktop, such as opening a file
 * or launching a web browser on a specified URL.
 * </p>
 * <p>
 * They are meant to be as extensible as possible. This, however, comes with a cost:
 * they can prove to be quite complex to understand and use. Before writing an implementation of
 * this interface, application developers should make sure they understand the following points:
 * <ul>
 *   <li>Generic execution</li>
 *   <li><i>Available</i> Vs <i>Supported</i></li>
 * </ul>
 * </p>
 * <h3>Generic execution</h3>
 * <p>
 * Desktop operations receive an <code>Object[]</code> as parameter to their {@link #execute(Object[])} method.
 * This allows the API to be rather flexible, if a bit more obscure.<br>
 * The basic unwritten contract that all operations must respect is that, for a given operation type, the same
 * parameters classes must be accepted. There is no way to enforce that and keep the flexibility, which means that the
 * responsibility for this lies on the application developer.
 * </p>
 * <p>
 * At the time of writing, the API uses two different types of operations: {@link DesktopManager#BROWSE URL browsing}
 *  and {@link DesktopManager#OPEN local file opening}.
 * Adapters have been provided for these: {@link UrlOperation} and {@link LocalFileOperation}.
 * </p>
 * <h3><i>Available</i> Vs <i>Supported</i></h3>
 * <p>
 * An operation is said to available if it will accept any parameter that matches its contract. For example,
 * an operation that works on local files will be available if it accepts any <code>java.io.File</code>, <code>String</code>
 * or {@link com.mucommander.commons.file.protocol.local.LocalFile} parameter.
 * </p>
 * <p>
 * An operation is said to be supported for a specific parameter subset it will accept any parameter that
 * match that subset.
 * </p>
 * <p>
 * An <i>available</i> operation is always supported. However, it's entirely possible for an operation to be supported
 * for some parameters but not others, and thus not to be available.<br>
 * For example, an operation that deals with XML files only will be supported for any parameter that describes a local XML file,
 * but won't be available as it will refuse plain text files.
 * </p>
 * @author Nicolas Rinaudo
 */
public interface DesktopOperation {
    /**
     * Returns the operation's name.
     * <p>
     * The returned value might be displayed to the user. It should thus be made as
     * human readable as possible and, if possible, localised.
     * </p>
     * @return the operation's name.
     */
    public String getName();

    /**
     * Checks whether the operation is available.
     * <p>
     * An operation is said to be available if and only if any call to
     * {@link #canExecute(Object[])} with parameters that match its constraints
     * will return <code>true</code>.
     * </p>
     * <p>
     * For example, an operation of type {@link DesktopManager#BROWSE} that accepts
     * any and all HTTP URLs is available. However, an operation of type
     * {@link DesktopManager#OPEN} that only accepts XML files isn't.
     * </p>
     * @return <code>true</code> if the operation is available, <code>false</code> otherwise.
     * @see    #canExecute(Object[])
     */
    public boolean isAvailable();

    /**
     * Checks whether an operation is supported for the specified parameters.
     * <p>
     * If the operation is {@link #isAvailable() available}, then this method must always
     * return <code>true</code>.
     * </p>
     * <p>
     * If the operation isn't available, but the specified parameters match a subset of legal
     * parameters that it knows how to deal with, this method must return <code>true</code>.
     * </p>
     * <p>
     * In any other case, this method must return <code>false</code>.
     * </p>
     * <p>
     * For example, a {@link DesktopManager#OPEN} operation that only accept XML files will return:
     * <ul>
     *   <li>
     *     <code>true</code> if the parameter array contains a single instance of either <code>java.io.File</code>,
     *     <code>String</code> or {@link com.mucommander.commons.file.protocol.local.LocalFile} and that instance describes the
     *     path to a valid XML file.
     *   </li>
     *   <li>
     *     <code>false</code> if the specified parameters are not valid or if they do not describe the path to
     *     a valid XML file.
     *   </li>
     * </ul>
     * </p
     * @param  target parameters to check.
     * @return        <code>true</code> if the operation can be executed with the specified parameters, <code>false</code> otherwise.
     */
    public boolean canExecute(Object[] target);

    /**
     * Executes the operation on the specified parameters.
     * <p>
     * There is no guarantee that this method is available for the specified parameters. This must be checked
     * through {@link #canExecute(Object[])}.
     * </p>
     * @param  target                        parameters on which to execute the operation.
     * @throws IOException                   if an error occurs.
     * @throws UnsupportedOperationException if the operation is not supported for the specified parameters.
     */
    public void execute(Object[] target) throws IOException, UnsupportedOperationException;
}
