package eu.simstadt.nf;

import java.io.File;

/**
 * NFConnector lets you communicate with your novaFACTORY (nF) server instance.
 * 
 * @author Marcel Bruse
 */
public interface NFConnector {
	
	/**
	 * Callers of this NFConnector want to know the actual version of the novaFACTORY and the versions of its
	 * HTTP/FTP/WPS/etc. interfaces against which this interface has been implemented.
	 * 
	 * The various NovaFACTORY interfaces may change over time. Such changes force the SimStadt programmers to
	 * implement different versions of this NFConnector interface while keeping old implementations due to 
	 * backward compatibility.
	 * 
	 * @return The supported version of the novaFACTORY.
	 */
	public String supportsNFVersion();
	
	/**
	 * Sends an export job to nF. The job has to be passed and to be described in an appropriate XML format.
	 * The DTD of the XML format can be obtained from the nF installation or documentation.
	 * 
	 * @param file The nF export job as a prepared XML file.
	 * @return The status of the job. Could be pending or failed.
	 */
	public ExportJob sendExportJobFile(File exportJobFile);
	
	/**
	 * Sends an import job to nF. The given import job file has to be a zip file and has to obey the internal
	 * structure defined in the nF manuals. Short description:
	 * 
	 * Import jobs enable you to add, alter and delete CityGML top level objects (like buildings) in the nF.
	 * Every import job file has to contain a start file. Start files control the import process through their
	 * file names and their contents. The name of a start file has the following structure
	 * 
	 *     <Product>_<Tile>.start
	 *     
	 * The start file should contain the level to which your manipulated CityGML should be imported. Your CityGML
	 * file has to be named after the following naming convention:
	 * 
	 *     <Product>_<Tile>_<Level>_<Operation>.gml
	 *    
	 * Here operation can be ...
	 * - 'REP': Replaces whole existing buildings only,
	 * - 'REPUPD': Replaces whole existing buildings and adds new buildings, 
	 * - 'UPD': Update, same as REP,
	 * - 'CHG': Change, same as REPUPD,
	 * - 'DEL': Deletes the geometry of a particular LOD,
	 * - 'DELALL': Deletes a whole building
	 * 
	 * @param file The nF import job as a prepared ZIP file. It has to contain the CityGML file and the start file.
	 * @return Returns the job id of your import job or -1 if something went wrong.
	 */
	public ImportJob sendImportJobFile(File importJobFile);
	
	/**
	 * Returns the status of any existing export nF job.
	 * 
	 * @param jobId The id of the export job for which you want to request the status.
	 * @return The status of any existing export nF job.
	 */
	public ExportJob requestExportJob(int jobId);

	/**
	 * Returns the status of any existing import nF job.
	 * 
	 * @param jobId The id of the import job for which you want to request the status.
	 * @return The status of any existing import nF job.
	 */
	public ImportJob requestImportJob(int jobId);
	
	/**
	 * Downloads the result for a given nF export job and hands over the corresponding file handle.
	 * 
	 * @param jobId The id of the export job for which the result should be loaded.
	 * @return A file handle to the result of the nF export job. 
	 */
	public File requestExportJobResult(int jobId);

}