001/*
002 * Created on 15-Apr-2004
003 */
004package ca.uhn.hl7v2.protocol;
005
006import 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 */
018public 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}