001/*
002 * Copyright 2009 Red Hat, Inc.
003 * Red Hat licenses this file to you under the Apache License, version
004 * 2.0 (the "License"); you may not use this file except in compliance
005 * with the License.  You may obtain a copy of the License at
006 *    http://www.apache.org/licenses/LICENSE-2.0
007 * Unless required by applicable law or agreed to in writing, software
008 * distributed under the License is distributed on an "AS IS" BASIS,
009 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
010 * implied.  See the License for the specific language governing
011 * permissions and limitations under the License.
012 */
013
014package org.hornetq.spi.core.protocol;
015
016import java.util.List;
017
018import org.hornetq.api.core.HornetQBuffer;
019import org.hornetq.api.core.HornetQException;
020import org.hornetq.core.remoting.CloseListener;
021import org.hornetq.core.remoting.FailureListener;
022import org.hornetq.spi.core.remoting.BufferHandler;
023import org.hornetq.spi.core.remoting.Connection;
024
025/**
026 * A RemotingConnection is a connection between a client and a server.
027 *
028 * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a>
029 * @author <a href="mailto:jmesnil@redhat.com">Jeff Mesnil</a>
030 */
031public interface RemotingConnection extends BufferHandler
032{
033   /**
034    * returns the unique id of the Remoting Connection
035    *
036    * @return the id
037    */
038   Object getID();
039
040   /**
041    * Returns the creation time of the Remoting connection
042    */
043   long getCreationTime();
044
045   /**
046    * returns a string representation of the remote address of this connection
047    *
048    * @return the remote address
049    */
050   String getRemoteAddress();
051
052   /**
053    * add a failure listener.
054    * <p/>
055    * The listener will be called in the event of connection failure.
056    *
057    * @param listener the listener
058    */
059   void addFailureListener(FailureListener listener);
060
061   /**
062    * remove the failure listener
063    *
064    * @param listener the lister to remove
065    * @return true if removed
066    */
067   boolean removeFailureListener(FailureListener listener);
068
069   /**
070    * add a CloseListener.
071    * <p/>
072    * This will be called in the event of the connection being closed.
073    *
074    * @param listener the listener to add
075    */
076   void addCloseListener(CloseListener listener);
077
078   /**
079    * remove a Close Listener
080    *
081    * @param listener the listener to remove
082    * @return true if removed
083    */
084   boolean removeCloseListener(CloseListener listener);
085   
086   List<CloseListener> removeCloseListeners();
087   
088   void setCloseListeners(List<CloseListener> listeners);
089   
090   
091   /**
092    * return all the failure listeners
093    *
094    * @return the listeners
095    */
096   List<FailureListener> getFailureListeners();
097   
098   List<FailureListener> removeFailureListeners();
099
100
101   /**
102    * set the failure listeners.
103    * <p/>
104    * These will be called in the event of the connection being closed. Any previosuly added listeners will be removed.
105    *
106    * @param listeners the listeners to add.
107    */
108   void setFailureListeners(List<FailureListener> listeners);
109
110   /**
111    * creates a new HornetQBuffer of the specified size.
112    *
113    * @param size the size of buffer required
114    * @return the buffer
115    */
116   HornetQBuffer createBuffer(int size);
117
118   /**
119    * called when the underlying connection fails.
120    *
121    * @param me the exception that caused the failure
122    */
123   void fail(HornetQException me);
124
125   /**
126    * destroys this connection.
127    */
128   void destroy();
129
130   /**
131    * return the underlying Connection.
132    *
133    * @return the connection
134    */
135   Connection getTransportConnection();
136
137   /**
138    * returns whether or not the Remoting Connection is a client
139    *
140    * @return true if client, false if a server
141    */
142   boolean isClient();
143
144   /**
145    * returns true if this Remoting Connection has been destroyed.
146    *
147    * @return true if destroyed, otherwise false
148    */
149   boolean isDestroyed();    
150   
151   /**
152    * Disconnect the connection, closing all channels
153    */
154   void disconnect(boolean criticalError);
155   
156   /**
157    * returns true if any data has been received since the last time this method was called.
158    *
159    * @return true if data has been received.
160    */
161   boolean checkDataReceived();
162   
163   /**
164    * flush all outstanding data from the connection.
165    */
166   void flush();
167
168}