/*
 *                 Sun Public License Notice
 *
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 *
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2002 Sun
 * Microsystems, Inc. All Rights Reserved.
 */
package org.netbeans.modules.xml.api.scenario;

import javax.swing.event.ChangeListener;
import java.beans.PropertyChangeListener;
import org.openide.loaders.DataObject;

/**
 * 

 * All scenarios should implement this interface.
 * A scenario implementation is created by a ScenarioFactory.
 * 
 * 
NOTE:
 * 

 * 
All implementations are required to be serializable.
 * 
The toString() method of an implementation should return the name property
 *     of this scenario
 * 
 *
 * @author  asgeir@dimonsoftware.com
 * @deprecated Experimantal SPI
 */
public interface Scenario {
    
    public static final String PROP_SCENARIO_MODIFIED = "SCENARIO_MODIFIED";
    
    /**
     * Registers PropertyChangeListener to receive events.
     * @param listener The listener to register.
     */
    public void addPropertyChangeListener(PropertyChangeListener listener);
    
    /**
     * Removes PropertyChangeListener from the list of listeners.
     * @param listener The listener to remove.
     */
    public void removePropertyChangeListener(PropertyChangeListener listener);
    
    /**
     * This method returns the a UI component which can be used to
     * customize this scenario.  To update changes done in the UI panel,
     * the saveChanges() method can be called.
     * A new or initialized instance of Component should be returned every
     * time this method is called.
     * @param dataObject The DataObject which owns this scenario
     * @param activatePropertyChange a flag that determines if PropertyChangeEvents are fired
     * @return A Component which can be used to customize this scenario
     */
    public java.awt.Component getCustomizer(DataObject dataObject, boolean activatePropertyChange);
    
    /**
     * Executes the DataObject using this scenario.
     * @param dataObject the DataObject to execute.
     */
    public void execute(DataObject dataObject);
    
    /**
     * Get the name of this scenario
     * @return The name of this scenario
     */
    public String getName();
    
    /**
     * Set the name of this scenario
     * @param name The name of this scenario
     */
    public void setName(String name);
    
    /**
     * Update this scenario with changes done by the last UI
     * component returned by the getUIComponent() method.
     */
    public void saveChanges();
    
}