// Renderer.java
//
// Created: February 2006
//
// This file is a component of the BioMoby project.
// Copyright Martin Senger (martin.senger@gmail.com).
//

package org.biomoby.service.dashboard.renderers;

import org.biomoby.shared.MobyException;
import org.biomoby.service.dashboard.data.DataContainer;

import javax.swing.Icon;
import javax.swing.JComponent;

import java.io.File;

/**
 * SPI for rendering a data container.
 *
 * @author <A HREF="mailto:martin.senger@gmail.com">Martin Senger</A>
 * (based on work by Matthew Pocock for <a
 * href="http://taverna.sf.net">Taverna</a>)
 * @version $Id: Renderer.java,v 1.3 2006/02/19 18:42:56 senger Exp $
 */

public interface Renderer {

    final static String CLASS_NAME      = "class-name";
    final static String CLASS           = "class";
    final static String DATA_CONTAINER  = "data-container";
    final static String DATA            = "data";
    final static String MOBY_TYPE       = "moby-type";
    final static String MIME_TYPE       = "mime-type";

    /**************************************************************************
     * Return true if this SPI can handle (render) data whose type
     * complies with given value within given criterion. <p>
     *
     * Any renderer should handle also a collection of objects that it
     * can handle - see examples in {@link #getComponent} and {@link
     * #save2File}. <p>
     *
     * @param criterion is a category of the value, e.g. "MIME-TYPE"
     * @param value is a value from the category criterion, e.g. "text/xml"
     **************************************************************************/
    boolean canHandle (String criterion,
		       Object value);

    /**************************************************************************
     * Return a JComponent displaying (rendering) given data. <p>
     *
     * If it gets an array of data, it can always delegate their
     * accumulation to the {@link CollectionRenderer} by saying:
     *
     *<pre>
     *   if (data.getData().getClass().isArray())
     *      return new BoxCollectionRenderer (this).getComponent (data);
     *</pre>
     *
     * @param data to be rendered
     * @return a component for displaying data, or null if there is a
     * problem with data
     * @throws MobyException if called with wrong type of data
     **************************************************************************/
    JComponent getComponent (DataContainer data)
	throws MobyException;

    /**************************************************************************
     * Save given data in the given file. Only a renderer knows what
     * kind of data should be savd. <p>
     *
     * If it gets an array of data, ad if it wants to save them
     * separately, to more files, it can delegate it to the {@link
     * CollectionRenderer} by saying:
     *
     *<pre>
     *   if (data.getData().getClass().isArray())
     *      return new TabCollectionRenderer (this).save2File (data, file);
     *</pre>
     *
     * @return true on success, return false if you even did nt try to
     * save data (probably because it does not make sense to store
     * such data)
     * @throws MobyException if saving was tried but failed
     **************************************************************************/
    boolean save2File (DataContainer data, File file)
	throws MobyException;

    /**************************************************************************
     * A human-readable name for this SPI. Will be used in a selection
     * lists of available renderers. <p>
     *
     * @return a shortish name of this viewer
     **************************************************************************/
    String getName();

    /**************************************************************************
     * An icon for this SPI. Will be used in a selection lists of
     * available renderers. <p>
     *
     * @return an icon, or null
     **************************************************************************/
    Icon getIcon();

}