/*
 *                 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-2003 Sun
 * Microsystems, Inc. All Rights Reserved.
 */

package org.netbeans.modules.j2ee.deployment.plugins.api;

import java.io.File;
import javax.enterprise.deploy.spi.DeploymentConfiguration;
import javax.enterprise.deploy.spi.exceptions.ConfigurationException;
import javax.enterprise.deploy.model.DeployableObject;
import javax.enterprise.deploy.shared.ModuleType;

/** 
 * This interface allows a plugin to describe the disk layout of a deployed
 * application or module.  Updated bits for the module can then be written
 * in place to speed deployment.
 * @author  George Finklang
 */
public interface DeploymentPlanSplitter {
    /**
     * This method persists the deployment plan to the provided files.
     * Only the file base name (excluding the directory) should 
     * be used to determine the mapping. The order may not necessarily match the 
     * file names provided in getDeploymentPlanFileNames, so the base name 
     * should be used to determine which file instance should be used to write
     * the configuration.
     * @param config the DeploymentConfiguration object to be 
     * mapped to the given files. 
     * @param module the configuration describes
     * @param files absolute paths of output files. File.exists() == true for each file.
     */ 
    public void writeDeploymentPlanFiles(DeploymentConfiguration config, DeployableObject module, File[] files) throws ConfigurationException;
    
    /**
     * This method loads the deployment plan for the given module from the given 
     * files. The file objects specified may be zero length (in the case of an 
     * optional file, the cmp-mapping.xml will always exists but may not be 
     * used), thus the implementing class must be prepared to handle this 
     * scenario as part of normal operation.
     * @param config the configuration object that the data will be read into
     * @param module the configuration describes
     * @param files absolute paths of output files to write piece of configuration to. File.exists() == true for each file.
     */ 
    public void readDeploymentPlanFiles (DeploymentConfiguration config, DeployableObject module, File[] files) throws ConfigurationException;
    
    /**
     *  get the archive relative locations for the configuration files. This 
     * method will return the set of all possible files necessary for the
     * given module type. 
     * For a configuration file which is normally present at
     * META-INF/sun-ejb-jar.xml this method would contain 
     * "META-INF/sun-ejb-jar.xml" for one of the entries.
     * @param type of J2eeModule
     * @return list of possible configuration files.
     */ 
    public String [] getDeploymentPlanFileNames (ModuleType type);
    
     /**
      *  Return relative paths for server specific configuration files used in the given J2EE module.
      *  The return list could include paths for dynamic configuration files, e.g.,
      *  supporting data files containing info referenced by static configuration files returned by
      *  calls to getDeploymentPlanFileNames.  Files in this return list will be included in the 
      *  archive or distribution content of the module.
      *
      *  @param config  DeploymentConfiguration context of the module for which the paths are requested
      *  @param module  DeployableObject representing the J2EE module.
      *  @return array of string for relative paths of the server specific descriptors.  
      */
    //public String [] getDeploymentPlanExtraFiles (DeploymentConfiguration config, DeployableObject module);
}