changeset 451:3dfcd06fd8ba

Correcting typos in documentation text. Also improved the readability of the generated javadoc documents.
author Martin van Dinther <martin.van.dinther@monetdbsolutions.com>
date Thu, 04 Mar 2021 18:57:51 +0100 (2021-03-04)
parents b9f82064fe0c
children 64789c018991
files src/main/java/org/monetdb/jdbc/MonetBlob.java src/main/java/org/monetdb/jdbc/MonetCallableStatement.java src/main/java/org/monetdb/jdbc/MonetClob.java src/main/java/org/monetdb/jdbc/MonetConnection.java src/main/java/org/monetdb/jdbc/MonetDataSource.java src/main/java/org/monetdb/jdbc/MonetDriver.java.in src/main/java/org/monetdb/jdbc/MonetPreparedStatement.java src/main/java/org/monetdb/jdbc/MonetResultSet.java src/main/java/org/monetdb/jdbc/MonetSavepoint.java src/main/java/org/monetdb/jdbc/MonetStatement.java src/main/java/org/monetdb/jdbc/MonetWrapper.java src/main/java/org/monetdb/util/Exporter.java
diffstat 12 files changed, 51 insertions(+), 28 deletions(-) [+]
line wrap: on
line diff
--- a/src/main/java/org/monetdb/jdbc/MonetBlob.java
+++ b/src/main/java/org/monetdb/jdbc/MonetBlob.java
@@ -16,14 +16,16 @@ import java.sql.SQLException;
 import java.sql.SQLFeatureNotSupportedException;
 
 /**
+ *<pre>
  * The MonetBlob class implements the {@link java.sql.Blob} interface.
  *
  * Because MonetDB/SQL currently has no support for streams, this class is a
- * shallow wrapper of a byte[].  It is more or less supplied to
- * enable an application that depends on it to run.  It may be obvious
+ * shallow wrapper of a byte[]. It is more or less supplied to
+ * enable an application that depends on it to run. It may be obvious
  * that it is a real resource expensive workaround that contradicts the
  * benefits for a Blob: avoidance of huge resource consumption.
  * <b>Use of this class is highly discouraged.</b>
+ *</pre>
  *
  * @author Fabian Groffen
  */
--- a/src/main/java/org/monetdb/jdbc/MonetCallableStatement.java
+++ b/src/main/java/org/monetdb/jdbc/MonetCallableStatement.java
@@ -31,6 +31,7 @@ import java.util.Calendar;
 import java.util.Map;
 
 /**
+ *<pre>
  * A {@link CallableStatement} suitable for the MonetDB database.
  *
  * The interface used to execute SQL stored procedures.
@@ -39,15 +40,13 @@ import java.util.Map;
  * If used, the result parameter must be registered as an OUT parameter (MonetDB does not support this).
  * The other parameters can be used for input, output or both. Parameters are referred to sequentially, by number, with the first parameter being 1.
  *
- * <code>
  *  { call procedure-name [ (arg1, arg2, ...) ] }
  *  { ?= call procedure-name [ (arg1, arg2, ...) ] }
- * </code>
  *
  * IN parameter values are set using the set methods inherited from PreparedStatement.
  * The type of all OUT parameters must be registered prior to executing the stored procedure;
  * their values are retrieved after execution via the get methods provided here.
- * Note: MonetDB does not support OUT or INOUT parameters. Only input parameters are supported.
+ * <b>Note</b>: MonetDB does not support OUT or INOUT parameters. Only input parameters are supported.
  *
  * A CallableStatement can return one ResultSet object or multiple ResultSet objects.
  * Multiple ResultSet objects are handled using operations inherited from Statement.
@@ -62,6 +61,7 @@ import java.util.Map;
  * - all registerOutParameter(parameterIndex/parameterName, int sqlType, ...) methods
  * - wasNull() method
  * because output parameters in stored procedures are not supported by MonetDB.
+ *</pre>
  *
  * @author Martin van Dinther
  * @version 1.1
--- a/src/main/java/org/monetdb/jdbc/MonetClob.java
+++ b/src/main/java/org/monetdb/jdbc/MonetClob.java
@@ -16,14 +16,16 @@ import java.sql.SQLException;
 import java.sql.SQLFeatureNotSupportedException;
 
 /**
+ *<pre>
  * The MonetClob class implements the {@link java.sql.Clob} interface.
  *
  * Because MonetDB/SQL currently has no support for streams, this class is a
- * shallow wrapper of a {@link StringBuilder}.  It is more or less supplied to
- * enable an application that depends on it to run.  It may be obvious
+ * shallow wrapper of a {@link StringBuilder}. It is more or less supplied to
+ * enable an application that depends on it to run. It may be obvious
  * that it is a real resource expensive workaround that contradicts the
  * sole reason for a Clob: avoidance of huge resource consumption.
  * <b>Use of this class is highly discouraged.</b>
+ *</pre>
  *
  * @author Fabian Groffen
  */
--- a/src/main/java/org/monetdb/jdbc/MonetConnection.java
+++ b/src/main/java/org/monetdb/jdbc/MonetConnection.java
@@ -42,6 +42,7 @@ import org.monetdb.mcl.parser.MCLParseEx
 import org.monetdb.mcl.parser.StartOfHeaderParser;
 
 /**
+ *<pre>
  * A {@link Connection} suitable for the MonetDB database.
  *
  * This connection represents a connection (session) to a MonetDB
@@ -60,8 +61,9 @@ import org.monetdb.mcl.parser.StartOfHea
  * must be called explicitly in order to commit changes; otherwise,
  * database changes will not be saved.
  *
- * The current state of this connection is that it nearly implements the
+ * The current state of this class is that it nearly implements the
  * whole Connection interface.
+ *</pre>
  *
  * @author Fabian Groffen
  * @author Martin van Dinther
--- a/src/main/java/org/monetdb/jdbc/MonetDataSource.java
+++ b/src/main/java/org/monetdb/jdbc/MonetDataSource.java
@@ -16,15 +16,17 @@ import javax.sql.DataSource;
 import java.util.Properties;
 
 /**
+ *<pre>
  * A DataSource suitable for the MonetDB database.
  *
  * This DataSource allows retrieval of a Connection using the JNDI bean like
- * framework.  A DataSource has numerous advantages over using the DriverManager
- * to retrieve a Connection object.  Using the DataSource interface enables a
+ * framework. A DataSource has numerous advantages over using the DriverManager
+ * to retrieve a Connection object. Using the DataSource interface enables a
  * more transparent application where the location or database can be changed
  * without changing any application code.
  *
  * Additionally, pooled connections can be used when using a DataSource.
+ *</pre>
  *
  * @author Fabian Groffen
  * @version 0.2
--- a/src/main/java/org/monetdb/jdbc/MonetDriver.java.in
+++ b/src/main/java/org/monetdb/jdbc/MonetDriver.java.in
@@ -20,7 +20,8 @@ import java.util.Map.Entry;
 import java.util.Properties;
 
 /**
- * A JDBC Driver suitable for the MonetDB RDBMS.
+ *<pre>
+ * A JDBC {@link Driver} suitable for the MonetDB RDBMS.
  *
  * This driver will be used by the DriverManager to determine if an URL
  * is to be handled by this driver, and if it does, then this driver
@@ -34,6 +35,7 @@ import java.util.Properties;
  * <tt>jdbc:monetdb://&lt;host&gt;[:&lt;port&gt;]/&lt;database&gt;</tt>
  * where [:&lt;port&gt;] denotes that a port is optional. If not
  * given the default (@JDBC_DEF_PORT@) will be used.
+ *</pre>
  *
  * @author Fabian Groffen
  * @version @JDBC_MAJOR@.@JDBC_MINOR@ (@JDBC_VER_SUFFIX@) based on MCL v@MCL_MAJOR@.@MCL_MINOR@"
--- a/src/main/java/org/monetdb/jdbc/MonetPreparedStatement.java
+++ b/src/main/java/org/monetdb/jdbc/MonetPreparedStatement.java
@@ -41,6 +41,7 @@ import java.util.Calendar;
 import java.util.Map;
 
 /**
+ *<pre>
  * A {@link PreparedStatement} suitable for the MonetDB database.
  *
  * This implementation of the PreparedStatement interface uses the
@@ -49,7 +50,6 @@ import java.util.Map;
  * returns the types it expects for them.
  *
  * An example of a server response on a prepare query is:
- * <pre>
  * % prepare select name from tables where id &gt; ? and id &lt; ?;
  * &amp;5 0 2 3 2
  * # prepare,      prepare,        prepare # table_name
@@ -58,7 +58,7 @@ import java.util.Map;
  * # 0,    0,      0 # length
  * [ "int",        9,      0       ]
  * [ "int",        9,      0       ]
- * </pre>
+ *</pre>
  *
  * @author Fabian Groffen
  * @author Martin van Dinther
@@ -2719,9 +2719,12 @@ public class MonetPreparedStatement
 	}
 
 	/**
-	 * @return the prepared SQL statement including parameter types and parameter values that were already set.
+	 * Return the prepared SQL statement including parameter types and parameter values that were set.
+	 *
+	 * @return a String representing this Object
 	 */
-	public String toString​() {
+	@Override
+	public String toString() {
 		final StringBuilder sb = new StringBuilder(256);
 		sb.append("Prepared SQL: ").append(sqlStatement).append("\n");
 		int param = 1;
@@ -2818,7 +2821,6 @@ public class MonetPreparedStatement
 		return buf.toString();
 	}
 
-
 	/**
 	 * Small helper method that formats the "Invalid Parameter Index number ..." message
 	 * and creates a new SQLDataException object whose SQLState is set
--- a/src/main/java/org/monetdb/jdbc/MonetResultSet.java
+++ b/src/main/java/org/monetdb/jdbc/MonetResultSet.java
@@ -42,7 +42,8 @@ import java.util.Map;
 import java.util.TimeZone;
 
 /**
- * A ResultSet suitable for the MonetDB database.
+ *<pre>
+ * A {@link ResultSet} suitable for the MonetDB database.
  *
  * A table of data representing a database result set, which is usually
  * generated by executing a statement that queries the database.
@@ -58,6 +59,7 @@ import java.util.TimeZone;
  * FORWARD_ONLY or result sets scrollable in both directions can be noticed as
  * for FORWARD_ONLY result sets the memory usage will be likely lower for large
  * result sets.
+ *</pre>
  *
  * @author Fabian Groffen
  * @author Martin van Dinther
--- a/src/main/java/org/monetdb/jdbc/MonetSavepoint.java
+++ b/src/main/java/org/monetdb/jdbc/MonetSavepoint.java
@@ -8,12 +8,16 @@
 
 package org.monetdb.jdbc;
 
+import java.sql.Savepoint;
 import java.sql.SQLException;
 import java.util.concurrent.atomic.AtomicInteger;
 
 /**
+ *<pre>
+ * A {@link Savepoint} suitable for the MonetDB database.
+ *
  * The representation of a savepoint, which is a point within the current
- * transaction that can be referenced from the Connection.rollback method.
+ * transaction that can be referenced from the Connection.rollback() method.
  * When a transaction is rolled back to a savepoint all changes made after
  * that savepoint are undone.
  * Savepoints can be either named or unnamed. Unnamed savepoints are
@@ -24,14 +28,15 @@ import java.util.concurrent.atomic.Atomi
  * internal representation of the save point.
  *
  * Because the IDs which get generated are a logical sequence, application
- * wide, two concurrent transactions are guaranteed to not to have the same
+ * wide, two concurrent transactions are guaranteed to not have the same
  * save point identifiers. In this implementation the validity of save points
  * is determined by the server, which makes this a light implementation.
+ *</pre>
  *
  * @author Fabian Groffen
  * @version 1.1
  */
-public final class MonetSavepoint implements java.sql.Savepoint {
+public final class MonetSavepoint implements Savepoint {
 	/** The id of the last created Savepoint */
 	private static final AtomicInteger highestId = new AtomicInteger(0);
 
--- a/src/main/java/org/monetdb/jdbc/MonetStatement.java
+++ b/src/main/java/org/monetdb/jdbc/MonetStatement.java
@@ -20,16 +20,17 @@ import java.util.ArrayList;
 import java.util.concurrent.locks.ReentrantLock;
 
 /**
- * A Statement suitable for the MonetDB database.
+ *<pre>
+ * A {@link Statement} suitable for the MonetDB database.
  *
  * The object used for executing a static SQL statement and returning
- * the results it produces.
+ * the result(s) it produces.
  *
  * By default, only one {@link ResultSet} object per Statement object can be
  * open at the same time. Therefore, if the reading of one ResultSet
  * object is interleaved with the reading of another, each must have
- * been generated by different {@link Statement} objects. All execution methods
- * in the Statement interface implicitly close a Statement's current
+ * been generated by different {@link Statement} objects. All execution
+ * methods in the Statement interface implicitly close a Statement's current
  * ResultSet object if an open one exists.
  *
  * The current state of this Statement is that it only implements the
@@ -38,6 +39,7 @@ import java.util.concurrent.locks.Reentr
  * Commit and rollback are implemented, as is the autoCommit mechanism
  * which relies on server side auto commit.
  * Multi-result queries are supported using the getMoreResults() method.
+ *</pre>
  *
  * @author Fabian Groffen
  * @author Martin van Dinther
--- a/src/main/java/org/monetdb/jdbc/MonetWrapper.java
+++ b/src/main/java/org/monetdb/jdbc/MonetWrapper.java
@@ -12,6 +12,7 @@ import java.sql.SQLException;
 import java.sql.SQLFeatureNotSupportedException;
 
 /**
+ *<pre>
  * A Wrapper class which provide the ability to retrieve the delegate instance
  * when the instance in question is in fact a proxy class.
  *
@@ -21,6 +22,7 @@ import java.sql.SQLFeatureNotSupportedEx
  * as proxy class instances representing the the actual resources.
  * This class contains a standard mechanism to access these wrapped resources
  * represented by their proxy, to permit direct access to the resource delegates.
+ *</pre>
  *
  * @author Fabian Groffen, Martin van Dinther
  * @version 1.2
@@ -91,7 +93,7 @@ public class MonetWrapper implements jav
 	}
 
 	/**
-	 * General utility function to add double quotes around an SQL Indentifier
+	 * General utility function to add double quotes around an SQL Identifier
 	 * such as column or table or schema name in SQL queries.
 	 * It also adds escapes for special characters: double quotes and the escape character
 	 *
--- a/src/main/java/org/monetdb/util/Exporter.java
+++ b/src/main/java/org/monetdb/util/Exporter.java
@@ -42,7 +42,7 @@ public abstract class Exporter {
 
 	/**
 	 * Convenience function to call the general utility function MonetWrapper.dq()
-	 * to add double quotes around an SQL Indentifier such as column or
+	 * to add double quotes around an SQL Identifier such as column or
 	 * table or schema name in SQL queries.
 	 * It also adds escapes for special characters: double quotes and the escape character
 	 *
@@ -81,8 +81,8 @@ public abstract class Exporter {
 	}
 
 	/**
-	 * Utility method to fetch the "query" value from sys.tables for a specific view or table in a specific schema
-	 * The "query" value contains the original SQL view creation text or the ON clause text when it is a REMOTE TABLE
+	 * Utility method to fetch the "query" column value from sys.tables for a specific view or table in a specific schema
+	 * The "query" column value contains the original SQL view creation text or the ON clause text when it is a REMOTE TABLE
 	 *
 	 * @param con the JDBC connection, may not be null
 	 * @param schema the schem name, may not be null or empty