001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  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    package org.apache.activemq.transport;
018    
019    import java.io.IOException;
020    import java.net.URI;
021    import org.apache.activemq.Service;
022    
023    /**
024     * Represents the client side of a transport allowing messages to be sent
025     * synchronously, asynchronously and consumed.
026     * 
027     * 
028     */
029    public interface Transport extends Service {
030    
031        /**
032         * A one way asynchronous send
033         * 
034         * @param command
035         * @throws IOException
036         */
037        void oneway(Object command) throws IOException;
038    
039        /**
040         * An asynchronous request response where the Receipt will be returned in
041         * the future. If responseCallback is not null, then it will be called when
042         * the response has been completed.
043         * 
044         * @param command
045         * @param responseCallback TODO
046         * @return the FutureResponse
047         * @throws IOException
048         */
049        FutureResponse asyncRequest(Object command, ResponseCallback responseCallback) throws IOException;
050    
051        /**
052         * A synchronous request response
053         * 
054         * @param command
055         * @return the response
056         * @throws IOException
057         */
058        Object request(Object command) throws IOException;
059    
060        /**
061         * A synchronous request response
062         * 
063         * @param command
064         * @param timeout
065         * @return the repsonse or null if timeout
066         * @throws IOException
067         */
068        Object request(Object command, int timeout) throws IOException;
069    
070        // /**
071        // * A one way asynchronous send
072        // * @param command
073        // * @throws IOException
074        // */
075        // void oneway(Command command) throws IOException;
076        //
077        // /**
078        // * An asynchronous request response where the Receipt will be returned
079        // * in the future. If responseCallback is not null, then it will be called
080        // * when the response has been completed.
081        // *
082        // * @param command
083        // * @param responseCallback TODO
084        // * @return the FutureResponse
085        // * @throws IOException
086        // */
087        // FutureResponse asyncRequest(Command command, ResponseCallback
088        // responseCallback) throws IOException;
089        //    
090        // /**
091        // * A synchronous request response
092        // * @param command
093        // * @return the response
094        // * @throws IOException
095        // */
096        // Response request(Command command) throws IOException;
097        //
098        // /**
099        // * A synchronous request response
100        // * @param command
101        // * @param timeout
102        // * @return the repsonse or null if timeout
103        // * @throws IOException
104        // */
105        // Response request(Command command, int timeout) throws IOException;
106    
107        /**
108         * Returns the current transport listener
109         * 
110         * @return
111         */
112        TransportListener getTransportListener();
113    
114        /**
115         * Registers an inbound command listener
116         * 
117         * @param commandListener
118         */
119        void setTransportListener(TransportListener commandListener);
120    
121        /**
122         * @param target
123         * @return the target
124         */
125        <T> T narrow(Class<T> target);
126    
127        /**
128         * @return the remote address for this connection
129         */
130        String getRemoteAddress();
131    
132        /**
133         * Indicates if the transport can handle faults
134         * 
135         * @return true if fault tolerant
136         */
137        boolean isFaultTolerant();
138        
139        /**
140         * @return true if the transport is disposed
141         */
142        boolean isDisposed();
143        
144        /**
145         * @return true if the transport is connected
146         */
147        boolean isConnected();
148        
149        /**
150         * @return true if reconnect is supported
151         */
152        boolean isReconnectSupported();
153        
154        /**
155         * @return true if updating uris is supported
156         */
157        boolean isUpdateURIsSupported();
158        /**
159         * reconnect to another location
160         * @param uri
161         * @throws IOException on failure of if not supported
162         */
163        void reconnect(URI uri) throws IOException;
164        
165        /**
166         * Provide a list of available alternative locations
167         * @param rebalance 
168         * @param uris
169         * @throws IOException
170         */
171        void updateURIs(boolean rebalance,URI[] uris) throws IOException;
172    
173        /**
174         * Returns a counter which gets incremented as data is read from the transport.
175         * It should only be used to determine if there is progress being made in reading the next command from the transport.  
176         * The value may wrap into the negative numbers. 
177         * 
178         * @return a counter which gets incremented as data is read from the transport.
179         */
180        int getReceiveCounter();    
181    }