package gov.nist.hl7.ws.messagegeneration;


/**
 * Message Generation  Interface
 * @author Robert Snelick (NIST)
 *
 */ 


import gov.nist.hl7.core.NoXmlObjectMatchFoundException;
import gov.nist.hl7.core.data.DataException;

import java.io.IOException;
import java.sql.SQLException;

import javax.xml.parsers.ParserConfigurationException;
import javax.xml.transform.TransformerException;
import javax.xml.transform.TransformerFactoryConfigurationError;

import org.apache.xmlbeans.XmlException;
import org.xml.sax.SAXException;


/**
 * NIST HL7 V2 Message Generation Web Service
 * <p>
 * This service provides an interface for generation of HL7 version 2 (V2) message instances 
 * for given a message profile. The message can be populated with specific data values via a
 * generation context. The interface is designed for use in a web-service environment. The methods are 
 * intended to be simple and in many cases atomic calls. Parameters and return values are intentionally 
 * made to be simple objects. This provides for a flexible interface for building a user specific interface.
 * <p>
 * This service supports generation of messages for HL7 Version 2.3.1, 2.4, 2.5, and 2.5.1. The version 
 * that is used for message generation is dictated by the message profile.
 * <p>
 * @author Robert Snelick (NIST)
 * @version 1.0
 *
 */
public interface HL7MessageGenerationInterface {

	/**
	 * Use the handle identified by the OID. A handle represents a package of resources (e.g., a profile and
	 * a table file). The repository is searched using the OID, if the handle is located all of the artifacts
	 * linked with handle are used when performing message generation.
	 * <p>
	 * @param OID referencing a handle
	 * <p>
	 * @return true if handle was located in the repository and processed successfully; false otherwise.
	 * @throws Exception 
	 */
	boolean useHandle(String OID) throws Exception;
	
	/**
	 * Load an HL7 version 2 message profile. The profile is an XML document 
	 * that follows the rules given in the HL7 version 2 profile schema.
	 * <p>
	 * @param xmlProfile an HL7 version 2 message profile. 
	 * <p>
	 * @return true if profile was loaded and processed successfully; false otherwise.
	 * @throws Exception 
	 */

	boolean loadProfile(String xmlProfile) throws Exception;
	
	/**
	 * Use the profile identified by the OID. The repository is searched using the OID, if the profile 
	 * is located it is use for performing message generation.
	 * <p>
	 * @param OID referencing an HL7 version message profile.
	 * <p>
	 * @return true if profile was located in the repository and processed successfully; false
	 * otherwise.
	 * @throws Exception 
	 */
	boolean useProfile(String OID) throws Exception;
	
	/**
	 * The loadResource method allows a user to load additional resources that can be used in the
	 * generation process. This may be a table that specifies local codes. Each resource type defines
	 * the format of the given resource. More than one resource can be associated to a generation process.
	 * <p>
	 * TBD-what are the resource types and their formats.
	 * <p>
	 * @param xmlResource a resource that is used in the generation process.
	 * <p>
	 * @param resourceType a document that describes the type of the xmlResource; for example, an XML
	 * schema.
	 * <p>
	 * @return true if the resource has been successfully loaded and processed; false otherwise.
	 * @throws Exception 
	 */
	boolean loadResource(java.lang.String xmlResource, java.lang.String resourceType) throws Exception;
	
	/**
	 * The useResource method allows a user to access a resource that can be used in the
	 * generation process. This may be a table that specifies local codes. More than one
	 * resource can be associated to a generation process. Resource files are stored in the
	 * repository.
	 * <p>
	 * TBD-what are the resource types and their formats.
	 * <p>
	 * @param OID an object identifier to reference the resource
	 * <p>
	 * @return true if the resource was located in the repository and processed successfully; false otherwise.
	 * @throws Exception 
	 */
	boolean useResource(java.lang.String OID) throws Exception;
	
	/**
	 * The generation context describes the location and values used for creating messages. The validation 
	 * context is encoded in an XML document that adheres to the generation context schema. For details of 
	 * the format see...
	 * <p>
	 * @param simpleGenerationContext the message generation context describes the location and values used for
	 * creating messages.
	 * <p>
	 * @return true is the validation context has been successfully loaded and processed; false otherwise.
	 * @throws Exception 
	 */
	boolean setGenerationContext(java.lang.String simpleGenerationContext) throws Exception; 
	

	
	/**
	 * Perform the message generation.
	 * <p>
	 * @return true if the message was successfully generated; false otherwise.
	 * @throws Exception 
	 * @throws SAXException 
	 * @throws ParserConfigurationException 
	 * @throws NoXmlObjectMatchFoundException 
	 * @throws DataException 
	 * @throws MalformedMessageException 
	 * @throws TransformerException 
	 * @throws SQLException 
	 * @throws TransformerFactoryConfigurationError 
	 * @throws IOException 
	 * @throws XmlException 
	 * @throws Exception 
	 */
	boolean generate() throws Exception ;
	
	/**
	 * Get the status of the service.
	 * <p>
	 * @return true if the service is available; false if the service unavailable (e.g., running but too busy).
	 */
	boolean getServiceStatus();
	
	/**
	 * Retrieve the message. The message can be returned in XML or ER7 encoding.
	 * <p>
	 * @param encoding - the encoding of the message; valid values are "XML" or "ER7;
	 * @return an XML document with a detailed of the message validation results. 
	 * @throws Exception 
	 * @throws SAXException 
	 * @throws ParserConfigurationException 
	 * @throws DataException 
	 * @throws SQLException 
	 * @throws MalformedMessageException 
	 * @throws IOException 
	 * @throws IllegalArgumentException 
	 */
	String getMessage() throws Exception ; 
	

	
	/**
	 * Get the web service error message of the last exception caught.
	 * <p>
	 * @return a description of the last exception.
	 */
	String getLastExceptionMessage(); 
	
	
}