001    /*
002     * Created on 16-Apr-2004
003     */
004    package ca.uhn.hl7v2.protocol;
005    
006    import java.util.List;
007    
008    import ca.uhn.hl7v2.HL7Exception;
009    import ca.uhn.hl7v2.model.Message;
010    import ca.uhn.hl7v2.parser.Parser;
011    
012    /**
013     * <p>A convenient way for the initiator of a message exchange to send a 
014     * message to a remote server and await the response in the same thread.</p>  
015     * 
016     * <p>Acknowledgements, threading, and accept-level retries are handled by 
017     * an associated <code>Processor</code>.</p>
018     * 
019     * <p>Recall that acknowledgement requirements are specified in MSH fields 15 
020     * and 16 (see HL7 v2.5 chapter 2), so the sender has control.  If no response is 
021     * needed, and you would like this call to return right away, specify that no 
022     * acknowledgements are required.</p> 
023     * 
024     * @author <a href="mailto:bryan.tripp@uhn.on.ca">Bryan Tripp</a>
025     * @version $Revision: 1.1 $ updated on $Date: 2007-02-19 02:24:38 $ by $Author: jamesagnew $
026     */
027    public interface Initiator {
028        
029        /**
030         * Encodes a message, sends it to a remote system, awaits the response, 
031         * parses it, and returns it.  The response may be null if the message doesn't 
032         * require an application-level acknowledgement.   
033         *  
034         * @param theMessage the message to send to the remote system
035         * @return the response from the remote system 
036         */
037        public Message sendAndReceive(Message theMessage) throws HL7Exception;
038        
039        /**
040         * @return the <code>Parser</code> that is used to encode outbound messages
041         * and parse inbound ones.  It may be of interest to set certain parameters 
042         * of this parser, for example whether to use XML encoding.   
043         */
044        public Parser getParser();
045        
046        /**
047         * @return the <code>Processor</code> instance that is used to perform the message
048         * exchange   
049         */
050        public Processor getUnderlyingProcessor();
051        
052        /**
053         * @return the list of fields that will be included as metadata when a <code>Message</code>
054         * is converted to a <code>Transportable</code>.  Each field is a <code>Terser</code>
055         * path (type String).  
056         */
057        public List<String> getMetadataFields();
058            
059    }