mcs/class/RabbitMQ.Client/src/client/api/Protocols.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, 2008 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 by LShift Ltd., Cohesive Financial Technologies
  42 //   LLC., and Rabbit Technologies Ltd. are Copyright (C) 2007, 2008
  43 //   LShift Ltd., Cohesive Financial Technologies LLC., and Rabbit
  44 //   Technologies Ltd.;
  45 //
  46 //   All Rights Reserved.
  47 //
  48 //   Contributor(s): ______________________________________.
  49 //
  50 //---------------------------------------------------------------------------
  51 using System;
  52 using System.Reflection;
  53 using System.Configuration;
  54
  55 namespace RabbitMQ.Client
  56 {
  57     ///<summary>Concrete, predefined IProtocol instances ready for use
  58     ///with ConnectionFactory.</summary>
  59     ///<remarks>
  60     ///<para>
  61     /// Applications will in the common case use the FromEnvironment()
  62     /// method to search a fallback-chain of configuration sources for
  63     /// the IProtocol instance to use. However, in some cases, the
  64     /// default fallback-chain is not appropriate; in these cases,
  65     /// other methods such as FromConfiguration(string) or
  66     /// SafeLookup(string) may suffice.
  67     ///</para>
  68     ///</remarks>
  69     public class Protocols
  70     {
  71         // Hide the constructor - no instances of Protocols needed.
  72         // We'd make this class static, but for MS's .NET 1.1 compilers
  73         private Protocols() {}
  74
  75         ///<summary>The default App.config appSettings key used by
  76         ///FromConfiguration and FromEnvironment. At the time of
  77         ///writing, "AMQP_PROTOCOL".</summary>
  78         public readonly static string DefaultAppSettingsKey = "AMQP_PROTOCOL";
  79
  80         ///<summary>The environment variable read by
  81         ///FromEnvironmentVariable() and FromEnvironment(). At the
  82         ///time of writing, "AMQP_PROTOCOL".</summary>
  83         public readonly static string EnvironmentVariable = "AMQP_PROTOCOL";
  84
  85         ///<summary>Protocol version 0-8 as standardised.</summary>
  86         public static IProtocol AMQP_0_8
  87         {
  88             get { return new RabbitMQ.Client.Framing.v0_8.Protocol(); }
  89         }
  90         ///<summary>Protocol version 0-8, as modified by QPid.</summary>
  91         public static IProtocol AMQP_0_8_QPID
  92         {
  93             get { return new RabbitMQ.Client.Framing.v0_8qpid.Protocol(); }
  94         }
  95         ///<summary>Protocol version 0-9 as standardised (omitting
  96         ///sections marked "WIP", "work in progress", including in
  97         ///particular the Message class of operations).</summary>
  98         public static IProtocol AMQP_0_9
  99         {
 100             get { return new RabbitMQ.Client.Framing.v0_9.Protocol(); }
 101         }
 102
 103         ///<summary>Retrieve the current default protocol variant
 104         ///(currently AMQP_0_8)</summary>
 105         public static IProtocol DefaultProtocol
 106         {
 107             get { return AMQP_0_8; }
 108         }
 109
 110         ///<summary>Low-level method for retrieving a protocol version
 111         ///by name (of one of the static properties on this
 112         ///class)</summary>
 113         ///<remarks>
 114         ///<para>
 115         /// Returns null if no suitable property could be found.
 116         ///</para>
 117         ///<para>
 118         /// In many cases, FromEnvironment() will be a more
 119         /// appropriate method for applications to call; this method
 120         /// is provided for cases where the caller wishes to know the
 121         /// answer to the question "does a suitable IProtocol property
 122         /// with this name exist, and if so, what is its value?"
 123         ///</para>
 124         ///</remarks>
 125         public static IProtocol Lookup(string name)
 126         {
 127             PropertyInfo pi = typeof(Protocols).GetProperty(name,
 128                                                             BindingFlags.Public |
 129                                                             BindingFlags.Static);
 130             if (pi == null)
 131             {
 132                 return null;
 133             }
 134             return pi.GetValue(null, new object[0]) as IProtocol;
 135         }
 136
 137         ///<summary>Retrieve a protocol version by name (of one of the
 138         ///static properties on this class)</summary>
 139         ///<remarks>
 140         ///<para>
 141         /// If the argument is null, Protocols.DefaultProtocol is
 142         /// used. If the protocol variant named is not found,
 143         /// ConfigurationException is thrown.
 144         ///</para>
 145         ///<para>
 146         /// In many cases, FromEnvironment() will be a more
 147         /// appropriate method for applications to call; this method
 148         /// is provided for cases where the caller wishes to know the
 149         /// answer to the question "does a suitable IProtocol property
 150         /// with this name exist, and if so, what is its value?", with
 151         /// the additional guarantee that if a suitable property does
 152         /// not exist, a ConfigurationException will be thrown.
 153         ///</para>
 154         ///</remarks>
 155         ///<exception cref="ConfigurationException"/>
 156         public static IProtocol SafeLookup(string name)
 157         {
 158             if (name != null)
 159             {
 160                 IProtocol p = Lookup(name);
 161                 if (p != null)
 162                 {
 163                     return p;
 164                 }
 165                 else
 166                 {
 167                     throw new ConfigurationException("Unsupported protocol variant name: " + name);
 168                 }
 169             }
 170             return DefaultProtocol;
 171         }
 172
 173         private static string ReadEnvironmentVariable()
 174         {
 175             return Environment.GetEnvironmentVariable(EnvironmentVariable);
 176         }
 177
 178         ///<summary>Uses the process environment variable
 179         ///<code>EnvironmentVariable</code> to retrieve an IProtocol
 180         ///instance.</summary>
 181         ///<remarks>
 182         ///If the environment variable is unset,
 183         ///Protocols.DefaultProtocol is used. If the protocol variant
 184         ///named is not found, ConfigurationException is thrown.
 185         ///</remarks>
 186         ///<exception cref="ConfigurationException"/>
 187         public static IProtocol FromEnvironmentVariable()
 188         {
 189             return SafeLookup(ReadEnvironmentVariable());
 190         }
 191
 192         ///<summary>Uses App.config's appSettings section to retrieve
 193         ///an IProtocol instance.</summary>
 194         ///<remarks>
 195         ///If the appSettings key is missing,
 196         ///Protocols.DefaultProtocol is used. If the protocol variant
 197         ///named is not found, ConfigurationException is thrown.
 198         ///</remarks>
 199         ///<exception cref="ConfigurationException"/>
 200         public static IProtocol FromConfiguration(string appSettingsKey)
 201         {
 202             // FIXME: ConfigurationSettings.AppSettings is
 203             // obsolete. Use ConfigurationManager.AppSettings once we
 204             // decide that supporting .NET 1.1 is no longer required.
 205             string name = ConfigurationSettings.AppSettings[appSettingsKey];
 206             return SafeLookup(name);
 207         }
 208
 209         ///<summary>Returns FromConfiguration(DefaultAppSettingsKey).</summary>
 210         public static IProtocol FromConfiguration()
 211         {
 212             return FromConfiguration(DefaultAppSettingsKey);
 213         }
 214
 215         ///<summary>Tries FromConfiguration() first, followed by
 216         ///FromEnvironmentVariable() if no setting was found in the
 217         ///App.config.</summary>
 218         ///<exception cref="ConfigurationException"/>
 219         public static IProtocol FromEnvironment(string appSettingsKey)
 220         {
 221             // FIXME: ConfigurationSettings.AppSettings is
 222             // obsolete. Use ConfigurationManager.AppSettings once we
 223             // decide that supporting .NET 1.1 is no longer required.
 224             string name = ConfigurationSettings.AppSettings[appSettingsKey];
 225             if (name == null) {
 226                 name = ReadEnvironmentVariable();
 227             }
 228             return SafeLookup(name);
 229         }
 230
 231         ///<summary>Returns FromEnvironment(DefaultAppSettingsKey).</summary>
 232         public static IProtocol FromEnvironment()
 233         {
 234             return FromEnvironment(DefaultAppSettingsKey);
 235         }
 236     }
 237 }