/* ===================================================================
 * RecipeIOBiz.java
 * 
 * Created Feb 14, 2005 3:22:29 PM
 * 
 * Copyright (c) 2005 Matt Magoffin (spamsqr@msqr.us)
 * 
 * This program is free software; you can redistribute it and/or 
 * modify it under the terms of the GNU General Public License as 
 * published by the Free Software Foundation; either version 2 of 
 * the License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful, 
 * but WITHOUT ANY WARRANTY; without even the implied warranty of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
 * General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License 
 * along with this program; if not, write to the Free Software 
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 
 * 02111-1307 USA
 * ===================================================================
 * $Id: RecipeIOBiz.java 4 2009-05-01 03:27:53Z msqr $
 * ===================================================================
 */

package magoffin.matt.ieat.biz;

import java.io.InputStream;
import java.io.OutputStream;
import java.util.Locale;

import magoffin.matt.ieat.domain.Recipe;
import magoffin.matt.ieat.util.EmailRecipeCommand;

/**
 * Business interface for importing and exporting recipe data.
 * 
 * @author Matt Magoffin (spamsqr@msqr.us)
 * @version $Revision: 4 $ $Date: 2009-05-01 15:27:53 +1200 (Fri, 01 May 2009) $
 */

public interface RecipeIOBiz {

    /**
     * Create a Recipe object from a RecipeML input stream.
     * 
     * <p>This method will attempt to convert the RecipeML ingredients to
     * iEat ingredient objects, but may not be able to find appropriate 
     * matches.</p>
     * 
     * <p>Note the returned Recipe object will not have been persisted, 
     * it is assumed some data cleaning will have to occur before the 
     * Recipe can be stored.</p>
     * 
     * @param in the RecipeML input stream
     * @return the converted Recipe object
     */
    public Recipe createFromRecipeML(InputStream in);
    
    /**
     * Get a list of the supported export format values.
     * 
     * <p>The returned value should never be <em>null</em>, and 
     * should include all valid values for passing to the 
     * {@link #exportRecipe} method.</p>
     * 
     * @return non-null array of format values
     */
    public String[] getSupportedExportFormats();
    
    /**
     * Get a string to use as the name of a file exported in the specified format.
     * 
     * <p>This allows the application to suggest sensible file names to the user 
     * when exporting different file formats, i.e. to return "My Recipe.xml" for 
     * XML output or "My Recipe.txt" for text output.</p>
     * 
     * @param recipe the recipe to get the name for
     * @param format the export format
     * @return the file name
     */
    public String getFileNameForExport(Recipe recipe, String format);
    
    /**
     * Get a MIME type string to use for a recipe exported in a specific format.
     * 
     * @param recipe the recipe trying to export
     * @param format the format to export to
     * @return the MIME type of the exported recipe
     */
    public String getMimeForExport(Recipe recipe, String format);
    
    /**
     * Export an iEat recipe as another format.
     * 
     * <p>It is up to implementations of this interface to determine 
     * the allowable <code>format</code> values. The 
     * {@link #getSupportedExportFormats()} method should return the 
     * valid values.</p>
     * 
     * @param recipe the recipe to export
     * @param locale the Locale to export to
     * @param out the output stream to export the recipe to
     * @param format the format to export as
     */
    public void exportRecipe(Recipe recipe, Locale locale, OutputStream out, String format);
    
    /**
     * Email a recipe.
     * 
     * @param emailCommand the recipe email command data object
     * @param context the biz context
     */
    public void emailRecipe(EmailRecipeCommand emailCommand, BizContext context );
}
