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