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 comparability.
	 * 
	 * @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 JobStatus sendExportJob(File file);
	
	/**
	 * Returns the status of any existing nF job.
	 * 
	 * @param jobId The id of the job for which you want to request the status.
	 * @return The status of any existing nF job.
	 */
	public JobStatus requestJobStatus(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 requestJobResult(int jobId);

}