001    /*
002     * Created on 15-Apr-2004
003     */
004    package ca.uhn.hl7v2.protocol;
005    
006    import java.util.Map;
007    
008    /**
009     * Encapsulates the transport layer of a connection to another 
010     * HL7 server.  This is the layer responsible for sending and receiving 
011     * message strings.  The underlying protocol used is implementation
012     * dependent, that is there may be transport layers that are implemented 
013     * over email, or JMS, or HTTP.  
014     * 
015     * @author <a href="mailto:bryan.tripp@uhn.on.ca">Bryan Tripp</a>
016     * @version $Revision: 1.1 $ updated on $Date: 2007-02-19 02:24:38 $ by $Author: jamesagnew $
017     */
018    public interface TransportLayer {
019    
020        /**
021         * Sends a message to a remote HL7 service.
022         *   
023         * @param theMessage the message to send 
024         * @throws TransportException
025         */
026        public void send(Transportable theMessage) throws TransportException;
027        
028        /**
029         * Gets the next message from the remote system.  This call blocks until
030         * the next message is available.  
031         *  
032         * @return the next available message 
033         * @throws TransportException
034         */
035        public Transportable receive() throws TransportException;
036        
037        /**
038         * @return metadata to be added to the metadata of all incoming messages.  
039         *      This provides a way of associating connection information with  
040         *      incoming messages (eg the IP address of the remote server).
041         */
042        public Map<String, Object> getCommonMetadata();    
043        
044        /**
045         * Initializes a connection to the remote server.  This can be called after 
046         * an exception is encountered, to refresh a dead connection.  
047         * @throws TransportException
048         */
049        public void connect() throws TransportException;
050        
051        /**
052         * @return true if connect() has completed successfully.  Note that true 
053         *  may be returned even if a connection is dead (ie the implementation need 
054         *  not test a connection during this call) but should return false if connect()
055         *  has not been called, or if connect() has been called and is pending.  
056         */
057        public boolean isConnected();
058        
059        /**
060         * Drops any existing connection to the remote server.  
061         * @throws TransportException
062         */
063        public void disconnect() throws TransportException;
064        
065    }