/*
 * Created on Feb 14, 2005
 *
 * TODO To change the template for this generated file go to
 * Window - Preferences - Java - Code Style - Code Templates
 */
package webraveler.ravel;

import webraveler.vurl.ErrorsVURL;
import webraveler.vurl.VURL;

/**
 * @author schmitzc
 *
 * TODO To change the template for this generated type comment go to
 * Window - Preferences - Java - Code Style - Code Templates
 */
public class PluginAPI {
	
    // +------------------------+--------------------------------------
	// | User Interface Methods |
	// +------------------------+
	// Note: Not yet implemented
	
	/**
	 * Adds another button for the plugin
	 *
	 * @param pluginName a string containing the name of the plugin
	 */
	public static void addButton(String pluginName) {
		
	}
	
	/**
	 * Adds a menu for the plugin
	 *
	 * @param pluginName a string containing the name of the plugin
	 */
	public static void addMenu(String pluginName) {
		
	}
	
	
    // +-----------------+---------------------------------------------
	// | VURL Methods    |
	// +-----------------+
	
	/**
	 * Adds a temporary virtual URL for a plugin - in memory only, per-session.
	 * Flags the virtual URL as temporary.
	 *
	 * @param ravel the Raveler instance 
	 * @param pluginName a string containing the name of the plugin
	 * @param relativeURL a string containing the name of the relative URL
	 * @param proc an Object containing the procedure with two parameters:
	 *		 (1) the user name; (2) any available query string
	 *		 Raveler needs to call when the virtual URL is requested
	 * @return a string containing the full virtual URL
	 */
	public static String addTemporaryVirtuaLURL(Raveler ravel, String pluginName, String relativeURL, VURL proc) {
		return ravel.getVurlStack().addTemporaryVirtuaLURL(pluginName,relativeURL,proc);
	}
	
	/**
	 * Adds a permanent virtual URL - written to disk after the session ends
	 *
	 * @param ravel the Raveler instance 
	 * @param pluginName a string containing the name of the plugin
	 * @param relativeURL a string containing the name of the relative URL
	 * @param proc an Object containing the procedure with two parameters:
	 *		 (1) the user name; (2) any available query string
	 *		 Raveler needs to call when the virtual URL is requested
	 * @return a string containing the full virtual url
	 */
	public static String addPermanentVirtualURL(Raveler ravel, String pluginName, String relativeURL, VURL proc) {
		return ravel.getVurlStack().addPermanentVirtualURL(pluginName,relativeURL,proc);
	}
	
	/**
	 * Adds a virtual URL for the help page of a plugin
	 *
	 * @param ravel the Raveler instance 
	 * @param pluginName a string containing the name of the plugin
	 * @param proc an Object containing the procedure with two parameters:
	 *		 (1) the user name; (2) any available query string
	 *		 Raveler needs to call when the virtual URL is requested
	 * @return a string containing the full virtual url
	 */
	public static String addHelpVirtualURL(Raveler ravel, String pluginName, VURL proc) {
		return ravel.getVurlStack().addHelpVirtualURL(pluginName,proc);
	}
	
	/**
	 * Adds a virtual URL for the configuration page of a plugin
	 *
	 * @param ravel the Raveler instance 
	 * @param pluginName a string containing the name of the plugin
	 * @param proc an Object containing the procedure with two parameters:
	 *		 (1) the user name; (2) any available query string
	 *		 Raveler needs to call when the virtual URL is requested
	 * @return a string containing the full virtual url
	 */
	public static String addConfigVirtualURL(Raveler ravel, String pluginName, VURL proc) {
		return ravel.getVurlStack().addConfigVirtualURL(pluginName,proc);
	}
	
	/**
	 * Sets the virtual URL associated with the plugin named on the banner.
	 * When the user clicks on the plugin name, the user is brought to the
	 * specified URL
	 *
	 * @param ravel the Raveler instance 
	 * @param pluginName a string containing the name of the plugin
	 * @param proc an Object containing the procedure with two parameters:
	 *		 (1) the user name; (2) any available query string
	 *		 Raveler needs to call when the virtual URL is requested
	 * @return a string containing the full virtual url
	 */
	public static String addPluginVirtualURL(Raveler ravel, String pluginName, VURL proc) {
		return ravel.getVurlStack().addPluginVirtualURL(pluginName,proc);
	}
	
	/**
	 * Adds the virtual URL to the set of virtual URLs 
	 * associated with the plugin named on the banner.
	 *
	 * @param ravel the Raveler instance 
	 * @param pluginName a string containing the name of the plugin
	 * @param proc an Object containing the procedure with two parameters:
	 *		 (1) the user name; (2) any available query string
	 *		 Raveler needs to call when the virtual URL is requested
	 * @param name a string containing the name to be displayed on the banner for the vurl
	 * @return a string containing the full virtual url
	 */
	public static String addBannerVirtualURL(Raveler ravel, String pluginName, VURL proc, String name) {
		return ravel.getVurlStack().addBannerVirtualURL(pluginName,proc,name);
	}
	
    // +------------------------+--------------------------------------
	// | Error Handling Methods |
	// +------------------------+
	
	/**
	 * Print the given error to the current page (after the Raveler Bannner
	 * but before any other text).  Raveler will stop raveling the page and
	 * pass the unraveled page to the next plugin or back to the browser.
	 *
	 * @param pluginName A string containing the name of the plugin that reported the error
	 * @param err a RavelerError object that contains the error number and
	 *		a string describing the error
	 * @param url A string containing the url where the error occurred
	 */
	public static void printError(Raveler ravel, String pluginName, RavelerError err, String url) {
		/* Add the error to the error string - to be added after the Raveler Banner */
		System.out.println("Raveler: Printing error...");
		ravel.setError(true);
		/* Update the errors vurl */
		ErrorsVURL errors = (ErrorsVURL) ravel.getVurlStack().getVirtualURL("http://temp.webraveler2.errors/geterrors");
		errors.addError("<p class='level3'>"+pluginName+": "+err.getErrorString()+"</p>",url);
		
	} //printError(String,RavelerError)
	
	/**
	 * Print the given warning to the current page (after the Raveler Banner
	 * but before any other text).  Raveler will continue raveling the page.
	 *
	 * @param pluginName A string containing the name of the plugin that reported the warning
	 * @param warning a RavelerWarning object that contains the warning number and
	 *		a string describing the warning
	 * @param url A string containing the url where the error occurred
	 */
	public static void printWarning(Raveler ravel, String pluginName, RavelerWarning warning, String url) {
		/* Add the warning to the warning string - to be added after the Raveler Banner */
		System.out.println("Raveler: Printing warning...");
		ravel.setError(true);
		/* Update the errors vurl */
		ErrorsVURL errors = (ErrorsVURL) ravel.getVurlStack().getVirtualURL("http://temp.webraveler2.errors/geterrors");
		errors.addWarning("<p class='level3'>"+pluginName+": "+warning.getWarningString()+"</p>",url);
	} //printWarning(String,RavelerWarning)
	

} //class PluginAPI