Merge pull request #46 from v-ahibr/dev

Fixing Javadocs

src/main/java/com/microsoft/sqlserver/jdbc/AE.java

@@ -6,7 +6,7 @@
 // Copyright(c) Microsoft Corporation
 // All rights reserved.
 // MIT License
-// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the ""Software""), 
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), 
 //  to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
 //  and / or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions :
 // The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

src/main/java/com/microsoft/sqlserver/jdbc/ActivityCorrelator.java

@@ -6,7 +6,7 @@
 // Copyright(c) Microsoft Corporation
 // All rights reserved.
 // MIT License
-// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the ""Software""), 
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), 
 //  to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
 //  and / or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions :
 // The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

src/main/java/com/microsoft/sqlserver/jdbc/AuthenticationJNI.java

@@ -6,7 +6,7 @@
 // Copyright(c) Microsoft Corporation
 // All rights reserved.
 // MIT License
-// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the ""Software""), 
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), 
 //  to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
 //  and / or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions :
 // The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
@@ -19,10 +19,6 @@
 
 package com.microsoft.sqlserver.jdbc;
 
-/**
- * Encapsulation of the JNI native calls for trusted authentication.
- */
-
 class FedAuthDllInfo{
 	byte[] accessTokenBytes = null;
 	long expiresIn = 0;
@@ -33,6 +29,9 @@ class FedAuthDllInfo{
 	}
 }
 
+/**
+ * Encapsulation of the JNI native calls for trusted authentication.
+ */
 final class  AuthenticationJNI extends SSPIAuthentication
 {
 	private final static int maximumpointersize = 128; // we keep the SNI_Sec pointer

src/main/java/com/microsoft/sqlserver/jdbc/Column.java

@@ -6,7 +6,7 @@
 // Copyright(c) Microsoft Corporation
 // All rights reserved.
 // MIT License
-// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the ""Software""), 
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), 
 //  to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
 //  and / or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions :
 // The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

src/main/java/com/microsoft/sqlserver/jdbc/DDC.java

@@ -6,7 +6,7 @@
 // Copyright(c) Microsoft Corporation
 // All rights reserved.
 // MIT License
-// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the ""Software""), 
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), 
 //  to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
 //  and / or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions :
 // The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
@@ -355,6 +355,14 @@ static final Object convertBigDecimalToObject(BigDecimal bigDecimalVal, JDBCType
 		}
 	}
 
+	/**
+	 * Convert a Money object to desired target user type.
+	 * @param bigDecimalVal the value to convert.
+	 * @param jdbcType the jdbc type required.
+	 * @param streamType the stream type.
+	 * @param numberOfBytes the number of bytes to convert
+	 * @return the required object.
+	 */
 	static final Object convertMoneyToObject(BigDecimal bigDecimalVal, JDBCType jdbcType, StreamType streamType, int numberOfBytes)
 	{
 		switch (jdbcType)
@@ -386,7 +394,7 @@ static final Object convertMoneyToObject(BigDecimal bigDecimalVal, JDBCType jdbc
 		}
 	}
 
-	//this is how fx framework converts big decimal to money and smallmoney
+	//converts big decimal to money and smallmoney
 	private static byte[] convertToBytes(BigDecimal value, int scale, int numBytes)
 	{
 		boolean isNeg = value.signum() < 0;
@@ -419,7 +427,7 @@ private static byte[] convertToBytes(BigDecimal value, int scale, int numBytes)
 	 * @param jdbcType the jdbc type required.
 	 * @param baseTypeInfo the type information associated with bytesValue.
 	 * @return the required object.
-	 * @throws SQLServerException 
+	 * @throws SQLServerException when an error occurs.
 	 */
 	static final Object convertBytesToObject(byte[] bytesValue, JDBCType jdbcType, TypeInfo baseTypeInfo) throws SQLServerException
 	{

src/main/java/com/microsoft/sqlserver/jdbc/DLLException.java

@@ -6,7 +6,7 @@
 // Copyright(c) Microsoft Corporation
 // All rights reserved.
 // MIT License
-// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the ""Software""), 
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), 
 //  to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
 //  and / or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions :
 // The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
@@ -21,9 +21,15 @@
 
 import java.text.MessageFormat;
 
-
+/**
+ * 
+ * This class is used to handle exceptions that may be recieved from
+ * sqljdbc_auth.dll and sqljdbc_xa.dll
+ *
+ */
 class DLLException extends Exception
 {
+	private static final long serialVersionUID = -4498171382218222079L;
 	// category status and state are always either -1 or a positive number
 	// Internal Adal error category used in retry logic and building error message in managed code
 	private int category = -9;

src/main/java/com/microsoft/sqlserver/jdbc/DataTypes.java

@@ -7,7 +7,7 @@
 // Copyright(c) Microsoft Corporation
 // All rights reserved.
 // MIT License
-// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the ""Software""), 
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), 
 //  to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
 //  and / or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions :
 // The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
@@ -886,6 +886,10 @@ private JDBCType(Category category, int intValue, String className)
         this.className = className;
     }
 
+	/**
+     * Gets the integer value of JDBCType
+     * @return integer representation of JDBCType
+     */
     public int getIntValue()
     {
     	return this.intValue;

src/main/java/com/microsoft/sqlserver/jdbc/FailOverInfo.java

@@ -6,7 +6,7 @@
 // Copyright(c) Microsoft Corporation
 // All rights reserved.
 // MIT License
-// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the ""Software""), 
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), 
 //  to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
 //  and / or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions :
 // The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

src/main/java/com/microsoft/sqlserver/jdbc/FailOverMapSingleton.java

@@ -7,7 +7,7 @@
 // Copyright(c) Microsoft Corporation
 // All rights reserved.
 // MIT License
-// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the ""Software""), 
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), 
 //  to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
 //  and / or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions :
 // The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

src/main/java/com/microsoft/sqlserver/jdbc/IOBuffer.java

@@ -6,7 +6,7 @@
 // Copyright(c) Microsoft Corporation
 // All rights reserved.
 // MIT License
-// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the ""Software""), 
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), 
 //  to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
 //  and / or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions :
 // The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
@@ -2865,13 +2865,20 @@ void updateResult(Socket socket, IOException exception, String threadId)
 
 	}
 
-	//Updates the selectedException if
-	//a) selectedException is null
-	//b) ex is a non-socketTimeoutException and selectedException is a socketTimeoutException 
-	//If there are multiple exceptions, that are not related to socketTimeout
-	//the first non-socketTimeout exception is picked.
-	//If all exceptions are related to socketTimeout, the first exception is picked.
-	//Note: This method is not thread safe. The caller should ensure thread safety.
+	/**
+	 * Updates the selectedException if
+	 * <p>
+	 * a) selectedException is null
+	 * <p>
+	 * b) ex is a non-socketTimeoutException and selectedException is a socketTimeoutException 
+	 * <p>
+	 * If there are multiple exceptions, that are not related to socketTimeout
+	 * the first non-socketTimeout exception is picked.
+	 * If all exceptions are related to socketTimeout, the first exception is picked.
+	 * Note: This method is not thread safe. The caller should ensure thread safety.
+	 * @param ex the IOException
+	 * @param traceId the traceId of the thread
+	 */
 	public void updateSelectedException(IOException ex, String traceId)
 	{
 		boolean updatedException = false;
@@ -2898,7 +2905,8 @@ else if((!(ex instanceof SocketTimeoutException)) && (selectedException instance
 	}
 
 	/**
-	 * Used for tracing
+	 * Used fof tracing
+	 * @return traceID string
 	 */
 	public String toString()
 	{
@@ -2994,6 +3002,7 @@ public void run()
 
 	/**
 	 * Used for tracing
+	 * @return traceID string
 	 */
 	public String toString()
 	{

src/main/java/com/microsoft/sqlserver/jdbc/ISQLServerBulkRecord.java

@@ -6,7 +6,7 @@
 // Copyright(c) Microsoft Corporation
 // All rights reserved.
 // MIT License
-// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the ""Software""), 
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), 
 //  to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
 //  and / or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions :
 // The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
@@ -82,14 +82,15 @@ public interface ISQLServerBulkRecord
      * 'Understanding the JDBC Driver Data Types' for the appropriate mappings.
      * 
      * @return The data for the row.
+	 * @throws SQLServerException If there are any errors in obtaining the data.
      */
     public Object[] getRowData() throws SQLServerException;
 
     /**
      * Advances to the next data row.
      * 
      * @return True if rows are available; false if there are no more rows
-     * @throws SQLServerException If there are any errors in obtaining the data.
+     * @throws SQLServerException If there are any errors in advancing to the next row.
      */
     public boolean next() throws SQLServerException;
 }

src/main/java/com/microsoft/sqlserver/jdbc/ISQLServerCallableStatement.java

@@ -6,7 +6,7 @@
 // Copyright(c) Microsoft Corporation
 // All rights reserved.
 // MIT License
-// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the ""Software""), 
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), 
 //  to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
 //  and / or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions :
 // The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
@@ -20,10 +20,43 @@
 package com.microsoft.sqlserver.jdbc;
 
 import java.sql.*;
+
+/**
+ * 
+ * This interface is implemented by SQLServerCallableStatement Class.
+ *
+ */
 public interface ISQLServerCallableStatement extends java.sql.CallableStatement, ISQLServerPreparedStatement
 {
+	/**
+	 * Sets parameter parameterName to DateTimeOffset x
+	 * @param parameterName the name of the parameter
+	 * @param x DateTimeOffset value
+	 * @throws SQLException if parameterName does not correspond to a named parameter; 
+	 * if the driver can detect that a data conversion error could occur; 
+	 * if a database access error occurs or
+     * this method is called on a closed <code>CallableStatement</code>
+	 */
     public void setDateTimeOffset(String parameterName, microsoft.sql.DateTimeOffset x)  throws SQLException;
+
+	/**
+     * Gets the DateTimeOffset value of parameter with index parameterIndex
+     * @param parameterIndex the first parameter is 1, the second is 2, and so on
+     * @return DateTimeOffset value
+     * @throws SQLException if parameterIndex is out of range; 
+	 * if a database access error occurs or
+     * this method is called on a closed <code>CallableStatement</code>
+     */
     public microsoft.sql.DateTimeOffset getDateTimeOffset(int parameterIndex) throws SQLException;
+
+	/**
+     * Gets the DateTimeOffset value of parameter with name parameterName
+     * @param parameterName the name of the parameter
+     * @return DateTimeOffset value
+     * @throws SQLException if parameterName does not correspond to a named parameter; 
+	 * if a database access error occurs or
+     * this method is called on a closed <code>CallableStatement</code>
+     */
     public microsoft.sql.DateTimeOffset getDateTimeOffset(String parameterName) throws SQLException;
 }