Return-Path: 
 <commits-return-9660-apmail-activemq-commits-archive=activemq.apache.org@activemq.apache.org>
Delivered-To: apmail-activemq-commits-archive@www.apache.org
Received: (qmail 41473 invoked from network); 25 Nov 2008 16:54:29 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2)
  by minotaur.apache.org with SMTP; 25 Nov 2008 16:54:29 -0000
Received: (qmail 19552 invoked by uid 500); 25 Nov 2008 16:54:40 -0000
Delivered-To: apmail-activemq-commits-archive@activemq.apache.org
Received: (qmail 19496 invoked by uid 500); 25 Nov 2008 16:54:40 -0000
Mailing-List: contact commits-help@activemq.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@activemq.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@activemq.apache.org>
List-Post: <mailto:commits@activemq.apache.org>
List-Id: <commits.activemq.apache.org>
Reply-To: dev@activemq.apache.org
Delivered-To: mailing list commits@activemq.apache.org
Received: (qmail 19487 invoked by uid 99); 25 Nov 2008 16:54:40 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 25 Nov 2008 08:54:40 -0800
X-ASF-Spam-Status: No, hits=-2000.0 required=10.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 25 Nov 2008 16:53:22 +0000
Received: by eris.apache.org (Postfix, from userid 65534)
	id F02EB238887A; Tue, 25 Nov 2008 08:54:08 -0800 (PST)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r720537 -
 /activemq/activemq-dotnet/Apache.NMS/trunk/src/main/csharp/NMSConnectionFactory.cs
Date: Tue, 25 Nov 2008 16:54:08 -0000
To: commits@activemq.apache.org
From: jgomes@apache.org
X-Mailer: svnmailer-1.0.8
Message-Id: <20081125165408.F02EB238887A@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org

Author: jgomes
Date: Tue Nov 25 08:54:08 2008
New Revision: 720537

URL: http://svn.apache.org/viewvc?rev=720537&view=rev
Log:
Contributed patch from David Keaveny.  Greatly improves the comments on the function for better IntelliSense, and improves the Tracer output when searching for provider implementations.  This aids in debugging connection factory problems.

Thanks, David!

Modified:
    activemq/activemq-dotnet/Apache.NMS/trunk/src/main/csharp/NMSConnectionFactory.cs

Modified: activemq/activemq-dotnet/Apache.NMS/trunk/src/main/csharp/NMSConnectionFactory.cs
URL: http://svn.apache.org/viewvc/activemq/activemq-dotnet/Apache.NMS/trunk/src/main/csharp/NMSConnectionFactory.cs?rev=720537&r1=720536&r2=720537&view=diff
==============================================================================
--- activemq/activemq-dotnet/Apache.NMS/trunk/src/main/csharp/NMSConnectionFactory.cs (original)
+++ activemq/activemq-dotnet/Apache.NMS/trunk/src/main/csharp/NMSConnectionFactory.cs Tue Nov 25 08:54:08 2008
@@ -22,6 +22,9 @@
 
 namespace Apache.NMS
 {
+	/// <summary>
+	/// Implementation of a factory for <see cref="IConnection" /> instances.
+	/// </summary>
 	public class NMSConnectionFactory : IConnectionFactory
 	{
 		protected readonly IConnectionFactory factory;
@@ -30,8 +33,8 @@
 		/// The ConnectionFactory object must define a constructor that takes as a minimum a Uri object.
 		/// Any additional parameters are optional, but will typically include a Client ID string.
 		/// </summary>
-		/// <param name="providerURI"></param>
-		/// <param name="constructorParams"></param>
+		/// <param name="providerURI">The URI for the ActiveMQ provider.</param>
+		/// <param name="constructorParams">Optional parameters to use when creating the ConnectionFactory.</param>
 		public NMSConnectionFactory(string providerURI, params object[] constructorParams)
 			: this(new Uri(providerURI), constructorParams)
 		{
@@ -41,8 +44,8 @@
 		/// The ConnectionFactory object must define a constructor that takes as a minimum a Uri object.
 		/// Any additional parameters are optional, but will typically include a Client ID string.
 		/// </summary>
-		/// <param name="uriProvider"></param>
-		/// <param name="constructorParams"></param>
+		/// <param name="uriProvider">The URI for the ActiveMQ provider.</param>
+		/// <param name="constructorParams">Optional parameters to use when creating the ConnectionFactory.</param>
 		public NMSConnectionFactory(Uri uriProvider, params object[] constructorParams)
 		{
 			this.factory = CreateConnectionFactory(uriProvider, constructorParams);
@@ -51,9 +54,9 @@
 		/// <summary>
 		/// Create a connection factory that can create connections for the given scheme in the URI.
 		/// </summary>
-		/// <param name="uriProvider"></param>
-		/// <param name="constructorParams"></param>
-		/// <returns></returns>
+		/// <param name="uriProvider">The URI for the ActiveMQ provider.</param>
+		/// <param name="constructorParams">Optional parameters to use when creating the ConnectionFactory.</param>
+		/// <returns>A <see cref="IConnectionFactory" /> implementation that will be used.</returns>
 		public static IConnectionFactory CreateConnectionFactory(Uri uriProvider, params object[] constructorParams)
 		{
 			IConnectionFactory connectionFactory = null;
@@ -65,12 +68,12 @@
 				// If an implementation was found, try to instantiate it.
 				if(factoryType != null)
 				{
-#if NETCF
+#if NETCF
 					connectionFactory = (IConnectionFactory) Activator.CreateInstance(factoryType);
 #else
-					object[] parameters = MakeParameterArray(uriProvider, constructorParams);
+					object[] parameters = MakeParameterArray(uriProvider, constructorParams);
 					connectionFactory = (IConnectionFactory) Activator.CreateInstance(factoryType, parameters);
-#endif
+#endif
 				}
 
 				if(null == connectionFactory)
@@ -91,10 +94,11 @@
 		}
 
 		/// <summary>
-		/// Finds the Type associated with the given scheme.
+		/// Finds the <see cref="System.Type" /> associated with the given scheme.
 		/// </summary>
-		/// <param name="scheme"></param>
-		/// <returns></returns>
+		/// <param name="scheme">The scheme (e.g. <c>tcp</c>, <c>activemq</c> or <c>stomp</c>).</param>
+		/// <returns>The <see cref="System.Type" /> of the ConnectionFactory that will be used
+		/// to create the connection for the specified <paramref name="scheme" />.</returns>
 		private static Type GetTypeForScheme(string scheme)
 		{
 			string[] paths = GetConfigSearchPaths();
@@ -102,16 +106,21 @@
 			string factoryClassName;
 			Type factoryType = null;
 
+			Tracer.Debug("Locating provider for scheme: " + scheme);
+
 			if(LookupConnectionFactoryInfo(paths, scheme, out assemblyFileName, out factoryClassName))
-			{
+			{
 				Assembly assembly = null;
 
+				Tracer.Debug("Attempting to locate provider assembly: " + assemblyFileName);
 				foreach(string path in paths)
 				{
 					string fullpath = Path.Combine(path, assemblyFileName);
+					Tracer.Debug("\tScanning folder: " + path);
 
 					if(File.Exists(fullpath))
 					{
+						Tracer.Debug("\tAssembly found!");
 						assembly = Assembly.LoadFrom(fullpath);
 						break;
 					}
@@ -123,7 +132,7 @@
 					factoryType = assembly.GetType(factoryClassName, true);
 #else
 					factoryType = assembly.GetType(factoryClassName, true, true);
-#endif
+#endif
 				}
 			}
 
@@ -137,21 +146,22 @@
 		/// Following is a sample configuration file named nmsprovider-jms.config.  Replace
 		/// the parenthesis with angle brackets for proper XML formatting.
 		///
-		///		(?xml version="1.0" encoding="utf-8" ?)
-		///		(configuration)
-		///			(provider assembly="MyCompany.NMS.JMSProvider.dll" classFactory="MyCompany.NMS.JMSProvider.ConnectionFactory"/)
-		///		(/configuration)
+		///     (?xml version="1.0" encoding="utf-8" ?)
+		///     (configuration)
+		///         (provider assembly="MyCompany.NMS.JMSProvider.dll" classFactory="MyCompany.NMS.JMSProvider.ConnectionFactory"/)
+		///     (/configuration)
 		///
 		/// This configuration file would be loaded and parsed when a connection uri with a scheme of 'jms'
 		/// is used for the provider.  In this example the connection string might look like:
-		///		jms://localhost:7222
+		///     jms://localhost:7222
 		///
 		/// </summary>
 		/// <param name="paths">Folder paths to look in.</param>
-		/// <param name="scheme"></param>
-		/// <param name="assemblyFileName"></param>
-		/// <param name="factoryClassName"></param>
-		/// <returns></returns>
+		/// <param name="scheme">The scheme.</param>
+		/// <param name="assemblyFileName">Name of the assembly file.</param>
+		/// <param name="factoryClassName">Name of the factory class.</param>
+		/// <returns><c>true</c> if the configuration file for the specified <paramref name="scheme" /> could
+		/// be found; otherwise, <c>false</c>.</returns>
 		private static bool LookupConnectionFactoryInfo(string[] paths, string scheme, out string assemblyFileName, out string factoryClassName)
 		{
 			string configFileName = String.Format("nmsprovider-{0}.config", scheme.ToLower());
@@ -160,14 +170,17 @@
 			assemblyFileName = String.Empty;
 			factoryClassName = String.Empty;
 
+			Tracer.Debug("Attempting to locate provider configuration: " + configFileName);
 			foreach(string path in paths)
 			{
 				string fullpath = Path.Combine(path, configFileName);
+				Tracer.Debug("\tScanning folder: " + path);
 
 				try
 				{
 					if(File.Exists(fullpath))
 					{
+						Tracer.Debug("\tConfiguration file found!");
 						XmlDocument configDoc = new XmlDocument();
 
 						configDoc.Load(fullpath);
@@ -196,6 +209,10 @@
 		/// <summary>
 		/// Get an array of search paths to look for config files.
 		/// </summary>
+		/// <returns>
+		/// A collection of search paths, including the current directory, the current AppDomain's
+		/// BaseDirectory and the current AppDomain's RelativeSearchPath.
+		/// </returns>
 		private static string[] GetConfigSearchPaths()
 		{
 			ArrayList pathList = new ArrayList();
@@ -222,11 +239,11 @@
 		}
 
 		/// <summary>
-		/// Create an object array containing the parameters to pass to the constructor.
+		/// Converts a <c>params object[]</c> collection into a plain <c>object[]</c>s, to pass to the constructor.
 		/// </summary>
-		/// <param name="firstParam"></param>
-		/// <param name="varParams"></param>
-		/// <returns></returns>
+		/// <param name="firstParam">The first parameter in the collection.</param>
+		/// <param name="varParams">The remaining parameters.</param>
+		/// <returns>An array of <see cref="Object" /> instances.</returns>
 		private static object[] MakeParameterArray(object firstParam, params object[] varParams)
 		{
 			ArrayList paramList = new ArrayList();
@@ -240,26 +257,27 @@
 		}
 
 		/// <summary>
-		/// Creates a new connection
+		/// Creates a new connection.
 		/// </summary>
+		/// <returns>An <see cref="IConnection" /> created by the requested ConnectionFactory.</returns>
 		public IConnection CreateConnection()
 		{
 			return this.factory.CreateConnection();
 		}
 
 		/// <summary>
-		/// Creates a new connection with the given user name and password
+		/// Creates a new connection with the given <paramref name="userName" /> and <paramref name="password" /> credentials.
 		/// </summary>
-		/// <param name="userName"></param>
-		/// <param name="password"></param>
-		/// <returns></returns>
+		/// <param name="userName">The username to use when establishing the connection.</param>
+		/// <param name="password">The password to use when establishing the connection.</param>
+		/// <returns>An <see cref="IConnection" /> created by the requested ConnectionFactory.</returns>
 		public IConnection CreateConnection(string userName, string password)
 		{
 			return this.factory.CreateConnection(userName, password);
 		}
 
 		/// <summary>
-		/// The actual IConnectionFactory implementation that is being used.  This implemenation
+		/// The actual IConnectionFactory implementation that is being used.  This implementation
 		/// depends on the scheme of the URI used when constructed.
 		/// </summary>
 		public IConnectionFactory ConnectionFactory