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