--- a/java/sql-dk/src/info/globalcode/sql/dk/CLIOptions.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/CLIOptions.java Fri Jan 10 23:21:28 2014 +0100
@@ -34,6 +34,8 @@
import java.util.regex.PatternSyntaxException;
/**
+ * Holds options from command line, validates them, combines with configuration and provides derived
+ * objects.
*
* @author Ing. František Kučera (frantovo.cz)
*/
@@ -43,7 +45,7 @@
public static final String DEFAULT_NAME_SUFFIX = "(?=([^\\w]|$))";
private String sql;
private String databaseName;
- private Set<String> databaseNameToTest = new HashSet<>();
+ private Set<String> databaseNamesToTest = new HashSet<>();
private String namePrefix = DEFAULT_NAME_PREFIX;
private String nameSuffix = DEFAULT_NAME_SUFFIX;
private String formatterName;
@@ -90,7 +92,7 @@
if (!equalz(nameSuffix, DEFAULT_NAME_SUFFIX)) {
e.addProblem(new InvalidOptionsException.OptionProblem("Do not specify name suffix if just showing info."));
}
- if (showInfo.contains(InfoType.CONNECTION) && databaseNameToTest.isEmpty()) {
+ if (showInfo.contains(InfoType.CONNECTION) && databaseNamesToTest.isEmpty()) {
e.addProblem(new InvalidOptionsException.OptionProblem("Please specify which database should be tested."));
}
}
@@ -232,12 +234,12 @@
return showInfo;
}
- public Set<String> getDatabaseNameToTest() {
- return databaseNameToTest;
+ public Set<String> getDatabaseNamesToTest() {
+ return databaseNamesToTest;
}
- public void addDatabaseNameToTest(String databaseNameToTest) {
- this.databaseNameToTest.add(databaseNameToTest);
+ public void addDatabaseNamesToTest(String databaseNameToTest) {
+ this.databaseNamesToTest.add(databaseNameToTest);
}
public SQLCommand getSQLCommand() {
--- a/java/sql-dk/src/info/globalcode/sql/dk/CLIParser.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/CLIParser.java Fri Jan 10 23:21:28 2014 +0100
@@ -25,6 +25,9 @@
import java.util.Map;
/**
+ * Converts command line arguments from String array to object.
+ * Checks basic constraints (if only supported options are used and if they have correct number of
+ * parameters)
*
* @author Ing. František Kučera (frantovo.cz)
*/
@@ -127,7 +130,7 @@
break;
case Tokens.INFO_CONNECTION:
options.addShowInfo(InfoType.CONNECTION);
- options.addDatabaseNameToTest(fetchNext(args, ++i));
+ options.addDatabaseNamesToTest(fetchNext(args, ++i));
break;
default:
throw new CLIParserException("Unknown option: " + arg);
--- a/java/sql-dk/src/info/globalcode/sql/dk/CLIStarter.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/CLIStarter.java Fri Jan 10 23:21:28 2014 +0100
@@ -45,6 +45,7 @@
import javax.xml.bind.Unmarshaller;
/**
+ * Entry point of the command line interface of SQL-DK.
*
* @author Ing. František Kučera (frantovo.cz)
*/
@@ -53,6 +54,7 @@
// help:exit-codes
public static final int EXIT_SUCCESS = 0; // doc:success
public static final int EXIT_UNEXPECTED_ERROR = 1; // doc:unexpected error (probably bug)
+ // 2 is reserved: http://www.tldp.org/LDP/abs/html/exitcodes.html#EXITCODESREF
public static final int EXIT_SQL_ERROR = 3; // doc:SQL error
public static final int EXIT_CLI_PARSE_ERROR = 4; // doc:CLI options parse error
public static final int EXIT_CLI_VALIDATE_ERROR = 5; // doc:CLI options validation error
--- a/java/sql-dk/src/info/globalcode/sql/dk/ColorfulPrintWriter.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/ColorfulPrintWriter.java Fri Jan 10 23:21:28 2014 +0100
@@ -26,6 +26,10 @@
import java.util.EnumSet;
/**
+ * PrintWriter with convenience methods for printing color and formatted text.
+ *
+ * Uses ANSI Escape Sequences.
+ * See: http://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/x329.html
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/DatabaseConnection.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/DatabaseConnection.java Fri Jan 10 23:21:28 2014 +0100
@@ -34,6 +34,11 @@
import java.util.logging.Logger;
/**
+ * Represents connected database. Is derived from {@linkplain DatabaseDefinition}.
+ * Wraps {@linkplain Connection}.
+ *
+ * Is responsible for executing {@linkplain SQLCommand} and passing results to the
+ * {@linkplain Formatter}.
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/InfoLister.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/InfoLister.java Fri Jan 10 23:21:28 2014 +0100
@@ -155,7 +155,7 @@
new HeaderField("connected", SQLType.BOOLEAN));
List<Object[]> data = new ArrayList<>();
- for (String dbName : options.getDatabaseNameToTest()) {
+ for (String dbName : options.getDatabaseNamesToTest()) {
data.add(testConnection(dbName));
}
--- a/java/sql-dk/src/info/globalcode/sql/dk/Parameter.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/Parameter.java Fri Jan 10 23:21:28 2014 +0100
@@ -20,6 +20,7 @@
import java.sql.Types;
/**
+ * Parameter for {@linkplain SQLCommand}
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/SQLCommand.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/SQLCommand.java Fri Jan 10 23:21:28 2014 +0100
@@ -23,6 +23,7 @@
import java.util.List;
/**
+ * Represents SQL string and its parameters (if there are any).
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/SQLCommandNamed.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/SQLCommandNamed.java Fri Jan 10 23:21:28 2014 +0100
@@ -30,6 +30,7 @@
import java.util.regex.PatternSyntaxException;
/**
+ * Has named parameters.
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/SQLCommandNumbered.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/SQLCommandNumbered.java Fri Jan 10 23:21:28 2014 +0100
@@ -23,6 +23,7 @@
import java.util.List;
/**
+ * Has ordinal/numbered parameters.
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/SQLType.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/SQLType.java Fri Jan 10 23:21:28 2014 +0100
@@ -20,6 +20,7 @@
import java.sql.Types;
/**
+ * Data types of SQL parameters.
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/batch/Batch.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/batch/Batch.java Fri Jan 10 23:21:28 2014 +0100
@@ -20,6 +20,7 @@
import info.globalcode.sql.dk.SQLCommand;
/**
+ * Iterator which reads SQL commands from encoded (serialized) batch.
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/configuration/Configuration.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/configuration/Configuration.java Fri Jan 10 23:21:28 2014 +0100
@@ -35,6 +35,7 @@
import javax.xml.bind.annotation.XmlTransient;
/**
+ * Object representation of user configuration loaded from XML.
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/configuration/ConfigurationProvider.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/configuration/ConfigurationProvider.java Fri Jan 10 23:21:28 2014 +0100
@@ -18,6 +18,7 @@
package info.globalcode.sql.dk.configuration;
/**
+ * Use for lazy-loading of the configuration.
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/configuration/DatabaseDefinition.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/configuration/DatabaseDefinition.java Fri Jan 10 23:21:28 2014 +0100
@@ -23,6 +23,7 @@
import javax.xml.bind.annotation.XmlElement;
/**
+ * Configured (but not yet connected) database connection.
*
* @author Ing. František Kučera (frantovo.cz)
*/
@@ -81,7 +82,7 @@
}
/**
- * @param properties ad-hoc properties from CLI options
+ * @param properties ad-hoc properties from CLI options (for the JDBC driver)
*/
public DatabaseConnection connect(Properties properties) throws SQLException {
return new DatabaseConnection(this, properties);
--- a/java/sql-dk/src/info/globalcode/sql/dk/configuration/FormatterDefinition.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/configuration/FormatterDefinition.java Fri Jan 10 23:21:28 2014 +0100
@@ -27,6 +27,7 @@
import javax.xml.bind.annotation.XmlElement;
/**
+ * Configured (but not yet instantiated) formatter.
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/configuration/Properties.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/configuration/Properties.java Fri Jan 10 23:21:28 2014 +0100
@@ -26,9 +26,8 @@
* <p>List of configurables.</p>
*
* <p>Can be backed by defaults – if value for given name is nof found in this instance, we will
- * look
- * into defaults. Methods also accept defaultValue parameter – is used if property is nof found even
- * in default properties.</p>
+ * look into defaults. Methods also accept defaultValue parameter – is used if property is nof found
+ * even in default properties.</p>
*
* <p>Typical use: </p>
* <ul>
--- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/AbstractFormatter.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/AbstractFormatter.java Fri Jan 10 23:21:28 2014 +0100
@@ -25,6 +25,11 @@
import java.util.Stack;
/**
+ * <ol>
+ * <li>ensures integrity – if methods are called in correct order and context</li>
+ * <li>provides default implmentations of methods that does not produce any output for given
+ * events</li>
+ * </ol>
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/AbstractXmlFormatter.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/AbstractXmlFormatter.java Fri Jan 10 23:21:28 2014 +0100
@@ -33,6 +33,14 @@
import java.util.logging.Logger;
/**
+ * <p>
+ * Provides helper methods for printing pretty intended and optionally colorful (syntax highlighted)
+ * XML output.
+ * </p>
+ *
+ * <p>
+ * Must be used with care – bad usage can lead to invalid XML (e.g. using undeclared namespaces).
+ * </p>
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/Formatter.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/Formatter.java Fri Jan 10 23:21:28 2014 +0100
@@ -22,6 +22,9 @@
import java.util.List;
/**
+ * The formatter is responsible for printing the result sets and/or updates result (count of
+ * inserted/updated rows). The formatter can produce output in arbitrary format – text, some markup
+ * or even binary data.
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/FormatterContext.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/FormatterContext.java Fri Jan 10 23:21:28 2014 +0100
@@ -21,6 +21,7 @@
import java.io.OutputStream;
/**
+ * To be passed from the SQL-DK core to the formatter.
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularFormatter.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularFormatter.java Fri Jan 10 23:21:28 2014 +0100
@@ -25,8 +25,14 @@
import java.util.List;
/**
+ * <p>Prints human-readable output – tables of result sets and text messages with update counts.</p>
+ *
+ * <p>Longer values might break the table – overflow the cells – see alternative tabular formatters
+ * and the {@linkplain #PROPERTY_TRIM} property.</p>
*
* @author Ing. František Kučera (frantovo.cz)
+ * @see TabularPrefetchingFormatter
+ * @see TabularWrappingFormatter
*/
public class TabularFormatter extends AbstractFormatter {
--- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularPrefetchingFormatter.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularPrefetchingFormatter.java Fri Jan 10 23:21:28 2014 +0100
@@ -21,10 +21,14 @@
import java.util.List;
/**
+ * <p>
* Prefetches whole result set and computes column widths. Whole table is flushed at once in
* {@linkplain #writeEndResultSet()}.
+ * </p>
*
- * Long values will not overflow the cells, but whole result set must be loaded into memory.
+ * <p>
+ * Long values will not overflow the cells, but whole result set must be loaded into the memory.
+ * </p>
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularWrappingFormatter.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularWrappingFormatter.java Fri Jan 10 23:21:28 2014 +0100
@@ -25,6 +25,8 @@
import static info.globalcode.sql.dk.Functions.repeat;
/**
+ * Longer values are line-wrapped – the cell then contains multiple lines. Marks are added to
+ * signalize forced line ends (not present in original data).
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/XhtmlFormatter.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/XhtmlFormatter.java Fri Jan 10 23:21:28 2014 +0100
@@ -36,6 +36,9 @@
import javax.xml.namespace.QName;
/**
+ * Prints result sets and parameters as tables, SQL as preformatted and updates counts as
+ * paragraphs. You can pick XHTML fragments (usually tabular data) and use it on your website or use
+ * whole output as preview or report.
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/XmlFormatter.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/XmlFormatter.java Fri Jan 10 23:21:28 2014 +0100
@@ -29,6 +29,10 @@
import javax.xml.namespace.QName;
/**
+ * <p>Prints machine-readable output – XML document containing resultsets and updates count. Good
+ * choice for further processing – e.g. XSL transformation.</p>
+ *
+ * <p>TODO: XSD</p>
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/logging/ColorfulConsoleFormatter.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/logging/ColorfulConsoleFormatter.java Fri Jan 10 23:21:28 2014 +0100
@@ -27,6 +27,7 @@
import java.util.logging.LogRecord;
/**
+ * For console/terminal log output. Log messages are printed in brief and colorful form.
*
* @author Ing. František Kučera (frantovo.cz)
*/
--- a/java/sql-dk/src/info/globalcode/sql/dk/logging/LoggerInitializer.java Fri Jan 10 20:13:16 2014 +0100
+++ b/java/sql-dk/src/info/globalcode/sql/dk/logging/LoggerInitializer.java Fri Jan 10 23:21:28 2014 +0100
@@ -47,7 +47,7 @@
/**
- * TODO: FileHandler – detailed logs in file in ~/sql-dk/log/…
+ * TODO: optional FileHandler – detailed logs in file in ~/sql-dk/log/…
*/
}