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 */
014public interface ApplicationRouter {
015        /**
016         * {@link Transportable#getMetadata() Metadata} key: 
017         * Charset (MSH-18)
018         */
019        String METADATA_KEY_MESSAGE_CHARSET = "MSH-18";
020
021        /**
022         * {@link Transportable#getMetadata() Metadata} key: 
023         * Message control ID (MSH-10)
024         */
025    String METADATA_KEY_MESSAGE_CONTROL_ID = MetadataKeys.IN_MESSAGE_CONTROL_ID;
026        
027    /**
028         * {@link Transportable#getMetadata() Metadata} key: 
029         * Provides the IP of the sending system for a given message
030         */
031        String METADATA_KEY_SENDING_IP = MetadataKeys.IN_SENDING_IP;
032
033    /**
034         * {@link Transportable#getMetadata() Metadata} key: 
035         * Provides the port of the sending system for a given message
036         */
037        String METADATA_KEY_SENDING_PORT = MetadataKeys.IN_SENDING_PORT;
038
039    
040    /** 
041     * Attempts to route the given message to the associated <code>Application</code>  
042     * and obtain a response.  
043     * 
044     * @param theMessage the message to route 
045     * @return the response message (this may be null, for example if the given 
046     *      message doesn't require an application ACK)
047     */
048    public Transportable processMessage(Transportable theMessage) throws HL7Exception;
049    
050    /**
051     * @param theRoutingData message fields used in determining the appropriate destination  
052     * @return true if there is a destination application for messages with the given
053     *      characteristics  
054     */
055    public boolean hasActiveBinding(AppRoutingData theRoutingData);  
056        
057    /**
058     * <p>Associates the given application with the given message parameters, so that messages
059     * with matching parameters will be sent there.  Only one application can be registered 
060     * for a given set of parameters: repeated registration for a particular combination 
061     * over-writes the previous one.</p>  
062     * 
063     * <p>Because of wildcards, there may be multiple registrations that match a given message.  
064     * In this case, the first registered wins.</p>  
065     * 
066     * @param theRoutingData message fields used in determining the appropriate destination  
067     * @param theApplication the application to which messages with these parameters should be 
068     *      sent 
069     */
070    public void bindApplication(AppRoutingData theRoutingData, ReceivingApplication theApplication);
071    
072    /**
073     * Temporarily deactivates the binding on the given field data, if present.  
074     * @param theRoutingData the fields that define a set of messages that are bound to 
075     *      some <code>Application</code>  
076     */
077    public void disableBinding(AppRoutingData theRoutingData);
078    
079    /**
080     * Undoes <code>disableBinding(AppRoutingData theRoutingData)</code>.    
081     * @param theRoutingData the fields that define a set of messages that are bound to 
082     *      some <code>Application</code>  
083     */
084    public void enableBinding(AppRoutingData theRoutingData);
085    
086    /**
087     * @return the <code>Parser</code> that is used to parse inbound messages
088     * and encode outbound ones.  It may be of interest to set certain parameters 
089     * of this parser.     
090     */
091    public Parser getParser();
092    
093    /**
094     * Sets an exception handler which will be invoked in the event of a
095     * failure during parsing, processing, or encoding of an
096     * incoming message or its response.
097     */
098    void setExceptionHandler(ReceivingApplicationExceptionHandler exceptionHandler);
099    
100    /**
101     * <p>Encapsulates the message fields used for routing of messages from the 
102     * HL7 protocol to the appropriate <code>Application</code>. </p>   
103     * 
104     * <p>The wildcard "*" in any member indicates all values of the associated parameter.  For 
105     * example the conbination "ADT", "*", "*", "*" means all ADT messages.  Each value can also
106     * be a regular expression that is matched against the corresponding field.  </p>
107     * 
108     * @author <a href="mailto:bryan.tripp@uhn.on.ca">Bryan Tripp</a>
109     */
110    public static interface AppRoutingData {
111
112        /**
113         * @return MSH-9-1
114         */        
115        public String getMessageType(); 
116        
117        /**
118         * @return MSH-9-2
119         */        
120        public String getTriggerEvent();
121        
122        /**
123         * @return MSH-11-1
124         */        
125        public String getProcessingId();
126        
127        /**
128         * @return MSH-12
129         */                
130        public String getVersion();
131    }
132
133}