package jas2.plugin;

import javax.swing.*;
import java.awt.*;
import java.io.*;

import hepjas.analysis.EventData;

/**
 * Support for Java Analysis Studio Job Plugins 
 *
 * The Plugin class is used to extend the functionality of Java Analysis Studio with experiment, group, or personal
 * extensions. Java Analysis Studio plugins extend the Plugin class in a similar manner that web applets 
 * extend Applet. Plugins are a little more flexible than web applets however, since plugins can add new items to the
 * Java Analysis Studio menu, create windows in the main body of the application, and interact with event data.
 * 

 * A typical use for a plugin would be to provide an experiment specific event display within the 
 * body of the Java Analysis Studio application.
 * 

 * The current plugin functionality is fairly limited, more will be added in later releases. Send suggestions for
 * improved functionality to jas-feedback@sld-mail.slac.stanford.edu
 * 

 * Note: Most of the methods of Plugin require a context, and therefore should not be called before the 
 * Plugin is initialized (i.e. its init() method is called).
 * 
 * @see ExtensionPlugin
 */

public abstract class Plugin extends BasicPlugin
	implements IPlugin
{
	/**
	 * Called by the application before the plugins init method is called, to install the PluginContext
	 */
	public void setPluginContext(PluginContext context)
	{
		this.context = context;
		super.setPluginContext(context);
	}
	/**
	 * Provides access to the PluginContext. 
	 * It is better to use the many utility methods in Plugin rather than
	 * accessing the PluginContext directly.
	 */
	public PluginContext getPluginContext()
	{
		return context;
	}
	/**
	 * A plugin can use this method if it wants to be informed about changes in run state.
	 * Event Displays typically install a RunListener so that they know when to display a new event
	 * 
	 * @param listener The RunListener to add
	 */

	public void addRunListener(RunListener listener)
	{
		context.addRunListener(listener);
	}
	/**
	 * Remove a run listener previously added using addRunListener
	 *
	 * @param listener The RunListener to be removed
	 * @see #addRunListener(RunListener)
	 */
	public void removeRunListener(RunListener listener)
	{
		context.removeRunListener(listener);
	}
	/**
	 * Fetch the current event, as returned by the current EventSource
	 *
	 * This method is rather crude, especially in the case of a remote job, since it fetches the entire event
	 * over the network (which also implies that the event must be serializable). Some better mechanism of interacting
	 * with remote events will be provided in future.
	 *
	 * @return The current event, as returned by the current EventSource's getNextEvent method
	 * @exception NoEventAvailable if there is no current event, or if the current event cannot be fetched (because it
	 * is remote and not serializable).
	 */
	public EventData getCurrentEvent() throws NoEventAvailable
	{
		return context.getCurrentEvent();
	}
	/**
	 * The plugin can call this method to send a message to the Job.
	 * This will result in the Job's messageReceived method being called. Note that
	 * if the job is a remote job, the message must implement java.io.Serializable
	 * or it won't get to the remote server.
	 * @param message The message to send
	 * @see jas.server.HistogramServer#addMessageListener(jas.server.MessageListener)
	 */
	public void sendJob(Object message)
	{
		context.sendJob(message);
	}
	/**
	 * Called by the application when the plugin is destroyed
	 * typically when the job containing the plugin is
	 * closed.
	 */
	public void destroy()
	{
	}
	private PluginContext context;
}