package eu.simstadt.nf4j;

import java.io.File;

/**
 * NFConnector lets you communicate with your novaFACTORY (nF) server instance.
 * 
 * @param <I> The import job implementation which can be handled by the connector.
 * @param <E> The export job implementation which can be handled by the connector.
 * 
 * @author Marcel Bruse
 */
public interface Connector<I extends ImportJob<?>, E extends ExportJob<?>> {
	
	/**
	 * 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 to the nF in an appropriate XML job file.
	 * The DTD of the XML format can be obtained from the nF installation or documentation.
	 * The contents of the XML job file are detailed in the job's descriptor instance. This method is supposed to
	 * update the status of the job and the job id.
	 *  
	 * @param job The nF export job with description. If the job description is invalid, you will receive an
	 * InvalidJobDescriptorException.
	 */
	public void sendAndUpdateExportJob(E exportJob)
			throws InvalidJobDescriptorException, FailedTransmissionException;
	
	/**
	 * Sends an import job to nF. A given import job descriptor has to describe the import job file. This 
	 * method has to build the file and to zip it. The zip file 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 and the ZIP archive to be sent 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 job The nF import job to be sent. It has to contain a valid description.
	 */
	public void sendAndUpdateImportJob(I importJob) 
			throws InvalidJobDescriptorException, FailedTransmissionException;
	
	/**
	 * 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 E requestExportJob(int jobId) throws FailedTransmissionException;

	/**
	 * 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 I requestImportJob(int jobId) throws FailedTransmissionException;
	
	/**
	 * 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(E exportJob) throws FailedTransmissionException;

}