001/*
002 * Created on 16-Apr-2004
003 */
004package ca.uhn.hl7v2.protocol;
005
006import java.util.List;
007
008import ca.uhn.hl7v2.HL7Exception;
009import ca.uhn.hl7v2.model.Message;
010import 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 */
027public 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}