001/**
002 * Copyright (C) 2012 FuseSource, Inc.
003 * http://fusesource.com
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *    http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.fusesource.hawtdispatch.transport;
019
020import java.io.IOException;
021import java.net.SocketAddress;
022import java.net.URI;
023import java.nio.channels.ReadableByteChannel;
024import java.nio.channels.WritableByteChannel;
025import java.util.concurrent.Executor;
026
027import org.fusesource.hawtdispatch.DispatchQueue;
028import org.fusesource.hawtdispatch.Task;
029
030/**
031 * Represents an abstract connection.  It can be a client side or server side connection.
032 * 
033 * @author <a href="http://hiramchirino.com">Hiram Chirino</a>
034 */
035public interface Transport {
036
037    /**
038     * Starts the service.  Executes the onComplete runnable once the service has fully started up.
039     *
040     * @param onComplete my be set to null if not interested in a callback.
041     */
042    void start(Runnable onComplete);
043
044    /**
045     * Stops the service.  Executes the onComplete runnable once the service has fully stopped.
046     *
047     * @param onComplete my be set to null if not interested in a callback.
048     */
049    void stop(Runnable onComplete);
050
051    /**
052     * Starts the service.  Executes the onComplete runnable once the service has fully started up.
053     *
054     * @param onComplete my be set to null if not interested in a callback.
055     */
056    void start(Task onComplete);
057
058    /**
059     * Stops the service.  Executes the onComplete runnable once the service has fully stopped.
060     *
061     * @param onComplete my be set to null if not interested in a callback.
062     */
063    void stop(Task onComplete);
064
065    boolean full();
066
067    /**
068     * A one way asynchronous send of a command.  Only sent if the the transport is not full.
069     * 
070     * @param command
071     * @return true if the command was accepted.
072     */
073    boolean offer(Object command);
074
075    /**
076     * Forces a flush of any output buffers.  Once the flush completes the listener's
077     * 'onRefill()' method will execute.
078     */
079    public void flush();
080
081    /**
082     * Returns the current transport listener
083     *
084     * @return
085     */
086    TransportListener getTransportListener();
087
088    /**
089     * Registers an inbound command listener
090     *
091     * @param transportListener
092     */
093    void setTransportListener(TransportListener transportListener);
094
095    /**
096     * Returns the dispatch queue used by the transport
097     *
098     * @return
099     */
100    DispatchQueue getDispatchQueue();
101
102    /**
103     * Sets the dispatch queue used by the transport
104     *
105     * @param queue
106     */
107    void setDispatchQueue(DispatchQueue queue);
108
109    /**
110     * suspend delivery of commands.
111     */
112    void suspendRead();
113
114    /**
115     * resume delivery of commands.
116     */
117    void resumeRead();
118
119    /**
120     * @return the remote address for this connection
121     */
122    SocketAddress getRemoteAddress();
123
124    /**
125     * @return the remote address for this connection
126     */
127    SocketAddress getLocalAddress();
128
129    public void drainInbound();
130
131    /**
132     * @return true if the transport is closed/stopped.
133     */
134    boolean isClosed();
135    
136    /**
137     * @return true if the transport is connected
138     */
139    boolean isConnected();
140    
141    /**
142     * @return The protocol codec for the transport.
143     */
144    ProtocolCodec getProtocolCodec();
145
146    /**
147     * Sets the protocol codec for the transport
148     * @param protocolCodec
149     */
150    void setProtocolCodec(ProtocolCodec protocolCodec) throws Exception;
151
152    public Executor getBlockingExecutor();
153    public void setBlockingExecutor(Executor blockingExecutor);
154
155    ReadableByteChannel getReadChannel();
156    WritableByteChannel getWriteChannel();
157}