001/*
002 * Created on 16-Apr-2004
003 */
004package ca.uhn.hl7v2.protocol;
005
006import ca.uhn.hl7v2.HL7Exception;
007import ca.uhn.hl7v2.parser.Parser;  
008
009/**
010 * Routes messages to the appropriate application.  
011 * 
012 * @author <a href="mailto:bryan.tripp@uhn.on.ca">Bryan Tripp</a>
013 * @version $Revision: 1.1 $ updated on $Date: 2007-02-19 02:24:38 $ by $Author: jamesagnew $
014 */
015public interface ApplicationRouter {
016
017    /** 
018     * Attempts to route the given message to the associated <code>Application</code>  
019     * and obtain a response.  
020     * 
021     * @param theMessage the message to route 
022     * @return the response message (this may be null, for example if the given 
023     *      message doesn't require an application ACK)
024     */
025    public Transportable processMessage(Transportable theMessage) throws HL7Exception;
026    
027    /**
028     * @param theRoutingData message fields used in determining the appropriate destination  
029     * @return true if there is a destination application for messages with the given
030     *      characteristics  
031     */
032    public boolean hasActiveBinding(AppRoutingData theRoutingData);  
033        
034    /**
035     * <p>Associates the given application with the given message parameters, so that messages
036     * with matching parameters will be sent there.  Only one application can be registered 
037     * for a given set of parameters: repeated registration for a particular combination 
038     * over-writes the previous one.</p>  
039     * 
040     * <p>Because of wildcards, there may be multiple registrations that match a given message.  
041     * In this case, the first registered wins.</p>  
042     * 
043     * @param theRoutingData message fields used in determining the appropriate destination  
044     * @param theApplication the application to which messages with these parameters should be 
045     *      sent 
046     */
047    public void bindApplication(AppRoutingData theRoutingData, ReceivingApplication theApplication);
048    
049    /**
050     * Temporarily deactivates the binding on the given field data, if present.  
051     * @param theRoutingData the fields that define a set of messages that are bound to 
052     *      some <code>Application</code>  
053     */
054    public void disableBinding(AppRoutingData theRoutingData);
055    
056    /**
057     * Undoes <code>disableBinding(AppRoutingData theRoutingData)</code>.    
058     * @param theRoutingData the fields that define a set of messages that are bound to 
059     *      some <code>Application</code>  
060     */
061    public void enableBinding(AppRoutingData theRoutingData);
062    
063    /**
064     * @return the <code>Parser</code> that is used to parse inbound messages
065     * and encode outbound ones.  It may be of interest to set certain parameters 
066     * of this parser.     
067     */
068    public Parser getParser();
069        
070    /**
071     * <p>Encapsulates the message fields used for routing of messages from the 
072     * HL7 protocol to the appropriate <code>Application</code>. </p>   
073     * 
074     * <p>The wildcard "*" in any member indicates all values of the associated parameter.  For 
075     * example the conbination "ADT", "*", "*", "*" means all ADT messages.  Each value can also
076     * be a regular expression that is matched against the corresponding field.  </p>
077     * 
078     * @author <a href="mailto:bryan.tripp@uhn.on.ca">Bryan Tripp</a>
079     * @version $Revision: 1.1 $ updated on $Date: 2007-02-19 02:24:38 $ by $Author: jamesagnew $
080     */
081    public static interface AppRoutingData {
082
083        /**
084         * @return MSH-9-1
085         */        
086        public String getMessageType(); 
087        
088        /**
089         * @return MSH-9-2
090         */        
091        public String getTriggerEvent();
092        
093        /**
094         * @return MSH-11-1
095         */        
096        public String getProcessingId();
097        
098        /**
099         * @return MSH-12
100         */                
101        public String getVersion();
102    }
103
104}