mcs/class/RabbitMQ.Client/src/client/api/IConnection.cs

   1 // This source code is dual-licensed under the Apache License, version
   2 // 2.0, and the Mozilla Public License, version 1.1.
   3 //
   4 // The APL v2.0:
   5 //
   6 //---------------------------------------------------------------------------
   7 //   Copyright (C) 2007-2009 LShift Ltd., Cohesive Financial
   8 //   Technologies LLC., and Rabbit Technologies Ltd.
   9 //
  10 //   Licensed under the Apache License, Version 2.0 (the "License");
  11 //   you may not use this file except in compliance with the License.
  12 //   You may obtain a copy of the License at
  13 //
  14 //       http://www.apache.org/licenses/LICENSE-2.0
  15 //
  16 //   Unless required by applicable law or agreed to in writing, software
  17 //   distributed under the License is distributed on an "AS IS" BASIS,
  18 //   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19 //   See the License for the specific language governing permissions and
  20 //   limitations under the License.
  21 //---------------------------------------------------------------------------
  22 //
  23 // The MPL v1.1:
  24 //
  25 //---------------------------------------------------------------------------
  26 //   The contents of this file are subject to the Mozilla Public License
  27 //   Version 1.1 (the "License"); you may not use this file except in
  28 //   compliance with the License. You may obtain a copy of the License at
  29 //   http://www.rabbitmq.com/mpl.html
  30 //
  31 //   Software distributed under the License is distributed on an "AS IS"
  32 //   basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
  33 //   License for the specific language governing rights and limitations
  34 //   under the License.
  35 //
  36 //   The Original Code is The RabbitMQ .NET Client.
  37 //
  38 //   The Initial Developers of the Original Code are LShift Ltd,
  39 //   Cohesive Financial Technologies LLC, and Rabbit Technologies Ltd.
  40 //
  41 //   Portions created before 22-Nov-2008 00:00:00 GMT by LShift Ltd,
  42 //   Cohesive Financial Technologies LLC, or Rabbit Technologies Ltd
  43 //   are Copyright (C) 2007-2008 LShift Ltd, Cohesive Financial
  44 //   Technologies LLC, and Rabbit Technologies Ltd.
  45 //
  46 //   Portions created by LShift Ltd are Copyright (C) 2007-2009 LShift
  47 //   Ltd. Portions created by Cohesive Financial Technologies LLC are
  48 //   Copyright (C) 2007-2009 Cohesive Financial Technologies
  49 //   LLC. Portions created by Rabbit Technologies Ltd are Copyright
  50 //   (C) 2007-2009 Rabbit Technologies Ltd.
  51 //
  52 //   All Rights Reserved.
  53 //
  54 //   Contributor(s): ______________________________________.
  55 //
  56 //---------------------------------------------------------------------------
  57 using System;
  58 using System.Collections;
  59 using RabbitMQ.Client.Events;
  60
  61 namespace RabbitMQ.Client
  62 {
  63     ///<summary>Main interface to an AMQP connection.</summary>
  64     ///<remarks>
  65     ///<para>
  66     /// Instances of IConnection are used to create fresh
  67     /// sessions/channels. The ConnectionFactory class is used to
  68     /// construct IConnection instances. Please see the documentation
  69     /// for ConnectionFactory for an example of usage. Alternatively,
  70     /// an API tutorial can be found in the User Guide.
  71     ///</para>
  72     ///<para>
  73     /// Extends the IDisposable interface, so that the "using"
  74     /// statement can be used to scope the lifetime of a channel when
  75     /// appropriate.
  76     ///</para>
  77     ///</remarks>
  78     public interface IConnection: IDisposable
  79     {
  80         ///<summary>Raised when the connection is destroyed.</summary>
  81         ///<remarks>
  82         /// If the connection is already destroyed at the time an
  83         /// event handler is added to this event, the event handler
  84         /// will be fired immediately.
  85         ///</remarks>
  86         event ConnectionShutdownEventHandler ConnectionShutdown;
  87
  88         ///<summary>Signalled when an exception occurs in a callback
  89         ///invoked by the connection.</summary>
  90         ///<remarks>
  91         ///This event is signalled when a ConnectionShutdown handler
  92         ///throws an exception. If, in future, more events appear on
  93         ///IConnection, then this event will be signalled whenever one
  94         ///of those event handlers throws an exception, as well.
  95         ///</remarks>
  96         event CallbackExceptionEventHandler CallbackException;
  97
  98         ///<summary>Retrieve the endpoint this connection is connected
  99         ///to.</summary>
 100         AmqpTcpEndpoint Endpoint { get; }
 101
 102         ///<summary>The IProtocol this connection is using to
 103         ///communicate with its peer.</summary>
 104         IProtocol Protocol { get; }
 105
 106         ///<summary>The connection parameters used during construction
 107         ///of this connection.</summary>
 108         ConnectionParameters Parameters { get; }
 109
 110         ///<summary>The maximum channel number this connection
 111         ///supports (0 if unlimited). Usable channel numbers
 112         ///range from 1 to this number, inclusive.</summary>
 113         ushort ChannelMax { get; }
 114
 115         ///<summary>The maximum frame size this connection supports (0
 116         ///if unlimited).</summary>
 117         uint FrameMax { get; }
 118
 119         ///<summary>The current heartbeat setting for this connection
 120         ///(0 for disabled), in seconds.</summary>
 121         ushort Heartbeat { get; }
 122
 123         ///<summary>Returns the known hosts that came back from the
 124         ///broker in the connection.open-ok method at connection
 125         ///startup time. Null until the connection is completely open
 126         ///and ready for use.</summary>
 127         AmqpTcpEndpoint[] KnownHosts { get; }
 128
 129         ///<summary>Returns null if the connection is still in a state
 130         ///where it can be used, or the cause of its closure
 131         ///otherwise.</summary>
 132         ///<remarks>
 133         ///<para>
 134         /// Applications should use the ConnectionShutdown event to
 135         /// avoid race conditions. The scenario to avoid is checking
 136         /// CloseReason, seeing it is null (meaning the IConnection
 137         /// was available for use at the time of the check), and
 138         /// interpreting this mistakenly as a guarantee that the
 139         /// IConnection will remain usable for a time. Instead, the
 140         /// operation of interest should simply be attempted: if the
 141         /// IConnection is not in a usable state, an exception will be
 142         /// thrown (most likely OperationInterruptedException, but may
 143         /// vary depending on the particular operation being
 144         /// attempted).
 145         ///</para>
 146         ///</remarks>
 147         ShutdownEventArgs CloseReason { get; }
 148
 149         ///<summary>Returns true if the connection is still in a state
 150         ///where it can be used. Identical to checking if CloseReason
 151         ///== null.</summary>
 152         bool IsOpen { get; }
 153
 154         ///<summary>If true, will close the whole connection as soon
 155         ///as there are no channels open on it; if false, manual
 156         ///connection closure will be required.</summary>
 157         ///<remarks>
 158         /// Don't set AutoClose to true before opening the first
 159         /// channel, because the connection will be immediately closed
 160         /// if you do!
 161         ///</remarks>
 162         bool AutoClose { get; set; }
 163
 164         ///<summary>Create and return a fresh channel, session, and
 165         ///model.</summary>
 166         IModel CreateModel();
 167
 168         ///<summary>Close this connection and all its channels.</summary>
 169         ///<remarks>
 170         ///Note that all active channels, sessions, and models will be
 171         ///closed if this method is called. It will wait for the in-progress
 172         ///close operation to complete. This method will not return to the caller
 173         ///until the shutdown is complete. If the connection is already closed
 174         ///(or closing), then this method will throw AlreadyClosedException.
 175         ///It can also throw IOException when socket was closed unexpectedly.
 176         ///</remarks>
 177         void Close();
 178
 179         ///<summary>Close this connection and all its channels.</summary>
 180         ///<remarks>
 181         ///The method behaves in the same way as Close(), with the only
 182         ///difference that the connection is closed with the given connection
 183         ///close code and message.
 184         ///<para>
 185         ///The close code (See under "Reply Codes" in the AMQP specification)
 186         ///</para>
 187         ///<para>
 188         ///A message indicating the reason for closing the connection
 189         ///</para>
 190         ///</remarks>
 191         void Close(ushort reasonCode, string reasonText);
 192
 193         ///<summary>Close this connection and all its channels
 194         ///and wait with a timeout for all the in-progress close operations
 195         ///to complete.
 196         ///</summary>
 197         ///<remarks>
 198         ///Note that all active channels, sessions, and models will be
 199         ///closed if this method is called. It will wait for the in-progress
 200         ///close operation to complete with a timeout. If the connection is
 201         ///already closed (or closing), then this method will throw
 202         ///AlreadyClosedException.
 203         ///It can also throw IOException when socket was closed unexpectedly.
 204         ///If timeout is reached and the close operations haven't finished,
 205         ///then socket is forced to close.
 206         ///<para>
 207         ///To wait infinitely for the close operations to complete use
 208         ///Timeout.Infinite
 209         ///</para>
 210         ///</remarks>
 211         void Close(int timeout);
 212
 213         ///<summary>Close this connection and all its channels
 214         ///and wait with a timeout for all the in-progress close operations
 215         ///to complete.
 216         ///</summary>
 217         ///<remarks>
 218         ///The method behaves in the same way as Close(int timeout), with the only
 219         ///difference that the connection is closed with the given connection
 220         ///close code and message.
 221         ///<para>
 222         ///The close code (See under "Reply Codes" in the AMQP specification)
 223         ///</para>
 224         ///<para>
 225         ///A message indicating the reason for closing the connection
 226         ///</para>
 227         ///</remarks>
 228         void Close(ushort reasonCode, string reasonText, int timeout);
 229
 230         ///<summary>Abort this connection and all its channels.</summary>
 231         ///<remarks>
 232         ///Note that all active channels, sessions, and models will be
 233         ///closed if this method is called.
 234         ///In comparison to normal Close() method, Abort() will not throw
 235         ///AlreadyClosedException or IOException during closing connection.
 236         ///This method waits infinitely for the in-progress close operation
 237         ///to complete.
 238         ///</remarks>
 239         void Abort();
 240
 241         ///<summary>Abort this connection and all its channels.</summary>
 242         ///<remarks>
 243         ///The method behaves in the same way as Abort(), with the only
 244         ///difference that the connection is closed with the given connection
 245         ///close code and message.
 246         ///<para>
 247         ///The close code (See under "Reply Codes" in the AMQP specification)
 248         ///</para>
 249         ///<para>
 250         ///A message indicating the reason for closing the connection
 251         ///</para>
 252         ///</remarks>
 253         void Abort(ushort reasonCode, string reasonText);
 254
 255         ///<summary>
 256         ///Abort this connection and all its channels and wait with a
 257         ///timeout for all the in-progress close operations to complete.
 258         ///</summary>
 259         ///<remarks>
 260         ///This method, behaves in a similar way as method Abort() with the
 261         ///only difference that it explictly specifies the timeout given
 262         ///for all the in-progress close operations to complete.
 263         ///If timeout is reached and the close operations haven't finished,
 264         ///then socket is forced to close.
 265         ///<para>
 266         ///To wait infinitely for the close operations to complete use
 267         ///Timeout.Infinite
 268         ///</para>
 269         ///</remarks>
 270         void Abort(int timeout);
 271
 272         ///<summary>
 273         ///Abort this connection and all its channels and wait with a
 274         ///timeout for all the in-progress close operations to complete.
 275         ///</summary>
 276         ///<remarks>
 277         ///The method behaves in the same way as Abort(timeout), with the only
 278         ///difference that the connection is closed with the given connection
 279         ///close code and message.
 280         ///<para>
 281         ///The close code (See under "Reply Codes" in the AMQP specification)
 282         ///</para>
 283         ///<para>
 284         ///A message indicating the reason for closing the connection
 285         ///</para>
 286         ///</remarks>
 287         void Abort(ushort reasonCode, string reasonText, int timeout);
 288
 289         ///<summary>Returns the list of ShutdownReportEntry objects that
 290         ///contain information about any errors reported while closing the
 291         ///connection in the order they appeared</summary>
 292         IList ShutdownReport { get; }
 293     }
 294 }