Improve java doc and remove warnings of the driver manager (eclipse-b…

…irt#1825)
speckyspooky · Aug 4, 2024 · 193583d · 193583d
1 parent 674da27
commit 193583d
Show file tree

Hide file tree

Showing 2 changed files with 206 additions and 28 deletions.
diff --git a/...port.data.oda.jdbc.ui/src/org/eclipse/birt/report/data/oda/jdbc/ui/util/DriverLoader.java b/...port.data.oda.jdbc.ui/src/org/eclipse/birt/report/data/oda/jdbc/ui/util/DriverLoader.java
@@ -14,6 +14,7 @@
 
 import java.sql.Connection;
 import java.sql.SQLException;
+import java.text.CharacterIterator;
 import java.text.StringCharacterIterator;
 import java.util.Properties;
 
@@ -24,21 +25,61 @@
 import org.eclipse.datatools.connectivity.oda.OdaException;
 import org.eclipse.ui.PlatformUI;
 
+/**
+ * Driver load class
+ *
+ * @since 3.3
+ *
+ */
 public final class DriverLoader {
 	private DriverLoader() {
 	}
 
+	/**
+	 * Get a JDBC connection
+	 *
+	 * @param driverClassName  driver class name
+	 * @param connectionString connection string
+	 * @param userId           login user name
+	 * @param password         login password
+	 * @return new JDBC connection
+	 * @throws SQLException
+	 * @throws OdaException
+	 */
 	public static Connection getConnection(String driverClassName, String connectionString, String userId,
 			String password) throws SQLException, OdaException {
 		return getConnection(driverClassName, connectionString, userId, password, null);
 	}
 
+	/**
+	 * Get a JDBC connection
+	 *
+	 * @param driverClassName  driver class name
+	 * @param connectionString connection string
+	 * @param userId           login user name
+	 * @param password         login password
+	 * @param props            connection properties
+	 * @return new JDBC connection
+	 * @throws SQLException
+	 * @throws OdaException
+	 */
 	public static Connection getConnection(String driverClassName, String connectionString, String userId,
 			String password, Properties props) throws SQLException, OdaException {
 		return JDBCDriverManager.getInstance().getConnection(driverClassName, connectionString, userId, password, null,
 				props);
 	}
 
+	/**
+	 * Get a JDBC connection
+	 *
+	 * @param driverClassName  driver class name
+	 * @param connectionString connection string
+	 * @param userId           login user name
+	 * @param password         login password
+	 * @param props            connection properties
+	 * @return new JDBC connection
+	 * @throws SQLException
+	 */
 	public static Connection getConnectionWithExceptionTip(String driverClassName, String connectionString,
 			String userId, String password, Properties props) throws SQLException {
 		try {
@@ -56,7 +97,7 @@ static String escapeCharacters(String value) {
 		char character = iterator.current();
 		final StringBuilder result = new StringBuilder();
 
-		while (character != StringCharacterIterator.DONE) {
+		while (character != CharacterIterator.DONE) {
 			if (character == '\\') {
 				result.append("\\"); //$NON-NLS-1$
 			} else {
@@ -86,6 +127,19 @@ public static boolean testConnection(String driverClassName, String connectionSt
 		return testConnection(driverClassName, connectionString, null, userId, password, new Properties());
 	}
 
+	/**
+	 * Tests whether the given connection properties can be used to obtain a
+	 * connection.
+	 *
+	 * @param driverClassName  the name of driver class
+	 * @param connectionString the JDBC driver connection URL
+	 * @param userId           the login user id
+	 * @param password         the login password
+	 * @param props            connection properties
+	 * @return true if the the specified properties are valid to obtain a
+	 *         connection; false otherwise
+	 * @throws OdaException
+	 */
 	public static boolean testConnection(String driverClassName, String connectionString, String userId,
 			String password, Properties props) throws OdaException {
 		return testConnection(driverClassName, connectionString, null, userId, password, props);
@@ -110,6 +164,21 @@ public static boolean testConnection(String driverClassName, String connectionSt
 		return testConnection(driverClassName, connectionString, jndiNameUrl, userId, password, new Properties());
 	}
 
+	/**
+	 * Tests whether the given connection properties can be used to obtain a
+	 * connection.
+	 *
+	 * @param driverClassName  the name of driver class
+	 * @param connectionString the JDBC driver connection URL
+	 * @param jndiNameUrl      the JNDI name to look up a Data Source name service;
+	 *                         may be null or empty
+	 * @param userId           the login user id
+	 * @param password         the login password
+	 * @param props            connection properties
+	 * @return true if the the specified properties are valid to obtain a
+	 *         connection; false otherwise
+	 * @throws OdaException
+	 */
 	public static boolean testConnection(String driverClassName, String connectionString, String jndiNameUrl,
 			String userId, String password, Properties props) throws OdaException {
 		return JDBCDriverManager.getInstance().testConnection(driverClassName, connectionString, jndiNameUrl, userId,
@@ -118,13 +187,44 @@ public static boolean testConnection(String driverClassName, String connectionSt
 
 	// bidi_hcg: if Bidi format is defined - perform required Bidi transformations
 	// on connection properties before testing the connection
+	/**
+	 * Tests whether the given connection properties can be used to obtain a
+	 * connection.
+	 *
+	 * @param driverClassName  the name of driver class
+	 * @param connectionString the JDBC driver connection URL
+	 * @param jndiNameUrl      the JNDI name to look up a Data Source name service;
+	 *                         may be null or empty
+	 * @param userId           the login user id
+	 * @param password         the login password
+	 * @param bidiFormatStr    BIDI format string
+	 * @return true if the the specified properties are valid to obtain a
+	 *         connection; false otherwise
+	 * @throws OdaException
+	 */
 	public static boolean testConnection(String driverClassName, String connectionString, String jndiNameUrl,
 			String userId, String password, String bidiFormatStr) throws OdaException {
 
 		return testConnection(driverClassName, connectionString, jndiNameUrl, userId, password, bidiFormatStr,
 				new Properties());
 	}
 
+	/**
+	 * Tests whether the given connection properties can be used to obtain a
+	 * connection.
+	 *
+	 * @param driverClassName  the name of driver class
+	 * @param connectionString the JDBC driver connection URL
+	 * @param jndiNameUrl      the JNDI name to look up a Data Source name service;
+	 *                         may be null or empty
+	 * @param userId           the login user id
+	 * @param password         the login password
+	 * @param bidiFormatStr    BIDI format string
+	 * @param props
+	 * @return true if the the specified properties are valid to obtain a
+	 *         connection; false otherwise
+	 * @throws OdaException
+	 */
 	public static boolean testConnection(String driverClassName, String connectionString, String jndiNameUrl,
 			String userId, String password, String bidiFormatStr, Properties props) throws OdaException {