001    /**
002     * Copyright (C) 2010-2011, FuseSource Corp.  All rights reserved.
003     *
004     *     http://fusesource.com
005     *
006     * The software in this package is published under the terms of the
007     * CDDL license a copy of which has been included with this distribution
008     * in the license.txt file.
009     */
010    package org.fusesource.hawtdispatch.transport;
011    
012    import java.io.IOException;
013    import java.net.SocketAddress;
014    import java.net.URI;
015    
016    import org.fusesource.hawtdispatch.DispatchQueue;
017    
018    /**
019     * Represents an abstract connection.  It can be a client side or server side connection.
020     * 
021     * @author <a href="http://hiramchirino.com">Hiram Chirino</a>
022     */
023    public interface Transport {
024    
025        /**
026         * Starts the service.  Executes the onComplete runnable once the service has fully started up.
027         *
028         * @param onComplete my be set to null if not interested in a callback.
029         */
030        void start(Runnable onComplete);
031    
032        /**
033         * Stops the service.  Executes the onComplete runnable once the service has fully stopped.
034         *
035         * @param onComplete my be set to null if not interested in a callback.
036         */
037        void stop(Runnable onComplete);
038    
039        boolean full();
040    
041        /**
042         * A one way asynchronous send of a command.  Only sent if the the transport is not full.
043         * 
044         * @param command
045         * @return true if the command was accepted.
046         */
047        boolean offer(Object command);
048    
049        /**
050         * Forces a flush of any output buffers.  Once the flush completes the listener's
051         * 'onRefill()' method will execute.
052         */
053        public void flush();
054    
055        /**
056         * Returns the current transport listener
057         *
058         * @return
059         */
060        TransportListener getTransportListener();
061    
062        /**
063         * Registers an inbound command listener
064         *
065         * @param commandListener
066         */
067        void setTransportListener(TransportListener commandListener);
068    
069        /**
070         * Returns the dispatch queue used by the transport
071         *
072         * @return
073         */
074        DispatchQueue getDispatchQueue();
075    
076        /**
077         * Sets the dispatch queue used by the transport
078         *
079         * @param queue
080         */
081        void setDispatchQueue(DispatchQueue queue);
082    
083        /**
084         * suspend delivery of commands.
085         */
086        void suspendRead();
087    
088        /**
089         * resume delivery of commands.
090         */
091        void resumeRead();
092    
093        /**
094         * @param target
095         * @return the target
096         */
097        <T> T narrow(Class<T> target);
098    
099        /**
100         * @return the remote address for this connection
101         */
102        SocketAddress getRemoteAddress();
103    
104        /**
105         * @return the remote address for this connection
106         */
107        SocketAddress getLocalAddress();
108    
109        /**
110         * Indicates if the transport can handle faults
111         * 
112         * @return true if fault tolerant
113         */
114        boolean isFaultTolerant();
115    
116        /**
117         * @return true if the transport is disposed
118         */
119        boolean isDisposed();
120        
121        /**
122         * @return true if the transport is connected
123         */
124        boolean isConnected();
125        
126        /**
127         * @return The protocol codec for the transport.
128         */
129        ProtocolCodec getProtocolCodec();
130    
131        /**
132         * Sets the protocol codec for the transport
133         * @param protocolCodec
134         */
135        void setProtocolCodec(ProtocolCodec protocolCodec) throws Exception;
136    
137        /**
138         * reconnect to another location
139         * @param uri
140         * @throws IOException on failure of if not supported
141         */
142        void reconnect(URI uri);
143    
144        /**
145         * @return the identifier for the transport type.  Example "tcp" for the tcp transport. 
146         */
147        String getTypeId();
148    }