/*
 * Autopsy Forensic Browser
 *
 * Copyright 2011-2016 Basis Technology Corp.
 * Contact: carrier <at> sleuthkit <dot> org
 *
 * 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.sleuthkit.autopsy.corecomponentinterfaces;

import javax.swing.JPanel;

/**
 * Interface implemented by classes that add data sources of a particular type
 * (e.g., images, local disks, virtual directories of local/logical files) to a
 * case database. A data source processor is NOT responsible for analyzing the
 * data source, i.e., running ingest modules on the data source and its
 * contents.
 *
 * Data source processors plug in to the add data source wizard and should
 * provide a UI panel to allow a user to select a data source and do any
 * configuration required by the data source processor. The selection and
 * configuration panel should support addition of the add data source wizard as
 * a property change listener and should fire DSP_PANEL_EVENT property change
 * events to communicate with the wizard.
 *
 * Data source processors should perform all processing in a background task in
 * a separate thread, reporting results using a callback object.
 *
 * It is recommended that implementers provide an overload of the run method
 * that allows the data source processor to be run independently of the
 * selection and configuration panel.
 */
public interface DataSourceProcessor {

    /**
     * Property change events fired to communicate with the add data source
     * wizard.
     *
     * TODO (AUT-1891): What is needed is a single PANEL_CHANGED event so that
     * the wizard can call isPanelValid and set the enabling and focus of the
     * next button based on the result.
     */
    enum DSP_PANEL_EVENT {

        /**
         * This event is fired when the user changes something in the selection
         * and configuration panel. It notifies the add data source wizard that
         * it should call isPanelValid.
         */
        UPDATE_UI,
        /**
         * This event is fired to make the add data source wizard move focus to
         * the wizard's next button.
         * @deprecated Use UPDATE_UI.
         */
        @Deprecated
        FOCUS_NEXT
    };

    /**
     * Gets a string that describes the type of data sources this processor is
     * able to add to the case database. The string is suitable for display in a
     * type selection UI component (e.g., a combo box).
     *
     * @return A data source type display string for this data source processor.
     */
    String getDataSourceType();

    /**
     * Gets the panel that allows a user to select a data source and do any
     * configuration required by the data source. The panel is less than 544
     * pixels wide and less than 173 pixels high.
     *
     * @return A selection and configuration panel for this data source
     *         processor.
     */
    JPanel getPanel();

    /**
     * Indicates whether the settings in the selection and configuration panel
     * are valid and complete.
     *
     * @return True if the settings are valid and complete and the processor is
     *         ready to have its run method called, false otherwise.
     */
    boolean isPanelValid();

    /**
     * Adds a data source to the case database using a background task in a
     * separate thread and the settings provided by the selection and
     * configuration panel. Returns as soon as the background task is started.
     * The background task uses a callback object to signal task completion and
     * return results.
     *
     * This method should not be called unless isPanelValid returns true.
     *
     * @param progressMonitor Progress monitor that will be used by the
     *                        background task to report progress.
     * @param callback        Callback that will be used by the background task
     *                        to return results.
     */
    void run(DataSourceProcessorProgressMonitor progressMonitor, DataSourceProcessorCallback callback);

    /**
     * Requests cancellation of the background task that adds a data source to
     * the case database, after the task is started using the run method. This
     * is a "best effort" cancellation, with no guarantees that the case
     * database will be unchanged. If cancellation succeeded, the list of new
     * data sources returned by the background task will be empty.
     */
    void cancel();

    /**
     * Resets the selection and configuration panel for this data source
     * processor.
     */
    void reset();
}